About agents-md-writer
agents-md-writer is an Agent skill for authoring and revising AGENTS.md instructions at the appropriate repository scope. It focuses on repository-specific evidence, tool-specific hierarchy, and checking the effective instruction chain after changes.
Key features
- 01Identify instruction hierarchies and tools
- 02Place and revise scoped guidance
- 03Verify tool behavior against official docs
- 04Check conflicts and validate changes
Use cases
- 01Revise instructions for a repository subtree
- 02Migrate or audit layered instruction files
- 03Review changes to instruction discovery or precedence
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/agents-md-writerin Claude Code to confirm it loaded.
Bundled filesagents/openai.yaml
Details
From the project READMEAGENTS.md Writer
Produce durable instructions at the scope that needs them. Ground additions in non-obvious repository facts, recurring failures, hard constraints, or explicit team decisions; prefer executable enforcement for mechanical rules.
Establish the effective hierarchy
Identify the requested operation and target tools. Inspect the relevant global, root, nested, tool-specific, and legacy sources and how they combine. A local wording fix needs its affected instruction chain; a hierarchy migration needs coverage of every candidate source and intended tool.
When a decision depends on filenames, discovery, precedence, overrides, size limits, or reload timing, verify current official tool documentation. For Codex, start with the AGENTS.md guide. Do not assume other clients use the same rules.
Place and revise guidance
- Keep shared guidance at the broadest intended scope inside the authorized target. User-global files are for explicitly personal or global guidance.
- Put subtree rules in the closest suitable existing file when nesting is supported. Add a file only for a distinct scope or intentional precedence change.
- Use a common cross-tool file only if every intended tool reads it. Codex's
AGENTS.override.mdintentionally replaces the same directory'sAGENTS.md; verify other tools independently. - Give duplicate or conflicting rules one authoritative owner where possible. Link to explanatory documentation; retain commands, invariants, and context needed to act. Consult scripts, CI, configuration, and docs for the claims being changed rather than requiring a full repository survey for every edit.
- State desired behavior directly. Preserve real authority boundaries and exact fragile steps; remove generic advice, redundant approvals, and unconditional reading that does not affect the task.
Verify and finish
Re-read the affected chains in documented load order for contradictions and stale commands. When hierarchy or discovery changes, inspect effective sources from the root and a representative nested directory through supported introspection or dry runs. Report changed scopes, validation, and any unverified client behavior. An audit remains read-only; an authorized revision finishes through fixes and verification.