| name | write-agents-md |
| description | Use when creating, updating, consolidating, or reviewing an AGENTS.md (or CLAUDE.md, CLAUDE.local.md, .claude/rules/*.md, .cursorrules, .cursor/rules/*.mdc, AGENTS.override.md, or .github/instructions/*.instructions.md) project instruction file. Covers the open agents.md spec, Codex precedence rules, Claude Code memory loading, and migration from legacy formats. Use even if the user only says "instructions", "rules", "project memory", or names a single legacy filename. |
Write AGENTS.md
Author and maintain project instruction files (AGENTS.md and its vendor variants) that agents read every session. One artefact, three flows: create from scratch, targeted update, or consolidate scattered files.
Decide first
- Create vs update vs consolidate. Create when no instruction file exists in scope. Update when changes are narrow. Consolidate when more than one instruction file covers the same scope; see
references/platforms.md for the discovery list.
- Root vs nested. Put repo-wide rules at the root. Put module-specific rules in the relevant subdirectory's
AGENTS.md. Nearest file wins on Codex; descendants load lazily on Claude Code. Direct user prompts override either.
- Edit vs delete. Never delete an existing instruction file without explicit user confirmation; propose deletions in the changelog.
Mechanics
- Filename:
AGENTS.md at the repo root by default. See references/platforms.md for vendor variants, discovery order, and override files.
- Format: plain Markdown. No YAML frontmatter. No required headings.
- Loading: every session, every file in the walk. Token cost is real, prompt-cached after first load. Bloat erodes adherence.
- Size: 50-200 lines for a root file; nested files much shorter. Codex truncates at 32 KiB (
project_doc_max_bytes). Claude Code degrades adherence beyond ~200 lines per file.
- Precedence: user chat prompts override AGENTS.md. Closer directories override the root.
Sections
Use the canonical set in references/sections.md. Skip any section with no project-specific content. Typical headings:
- Project overview (one sentence)
- Setup
- Build and test
- Code style
- Testing
- PR and commit conventions
- Architecture notes
- Security and secrets
- Gotchas
Content rules
- Imperatives, not descriptions. "Use TypeScript strict mode for new files" beats "the project uses TypeScript".
- Apply the removal test: "would removing this rule cause the agent to make mistakes?" If no, cut it.
- No language defaults the model already knows from reading the code.
- No persona, role, or tone instructions; those belong in agent system prompts.
- No generic LLM boilerplate ("be helpful", "ask clarifying questions").
- No time-sensitive content (dates, version numbers that drift).
- No frontmatter. Plain Markdown. The Cursor
.mdc exception is the only vendor parser that reads YAML; see references/platforms.md.
- Runnable commands only. Test them before committing.
- Flag and resolve self-contradictions before edit; arbitrary choices waste tokens.
Consolidation flow
- Discover instruction files using the list in
references/platforms.md.
- Extract project-specific rules from each; drop duplicates and generic advice.
- Flag conflicts for user resolution; do not silently pick a winner.
- Preserve runnable commands verbatim.
- Propose the canonical target (
AGENTS.md at root) and the legacy files to delete, import-shim, or symlink. Prefer @AGENTS.md import shims (Claude Code, Gemini CLI) over symlinks to avoid double-loading; symlink only where no import syntax exists. See references/migration.md.
- Require explicit confirmation before deleting any file.
Review
Assessment scale:
| Rating | Meaning |
|---|
| ✅ Strong | Follows best practices, no significant issues |
| ⚠️ Adequate | Functional but has improvement opportunities |
| 🔧 Needs Work | Missing high-value patterns or contains ineffective patterns |
| ❌ Restructure | Fundamental issues requiring significant revision |
Review criteria specific to AGENTS.md (agent-prompt criteria belong in write-assistant):
| Criterion | High value | Low or no value |
|---|
| Voice | Imperative, specific | Descriptive, generic |
| Commands | Runnable, copy-pasteable | Placeholder or untested |
| Scope | Project-specific | Restates language defaults |
| Size | Within 50-200 lines | Long sections an agent will skim past |
| Structure | Canonical sections, no empty headings | Custom taxonomy, persona text |
| Removal test | Each rule changes behaviour | Could be cut without loss |
Output
When invoked to create, produce the new file at the requested path. Pure Markdown. No frontmatter.
When invoked to update or consolidate, produce the edited file plus a short changelog:
## <path>
**Rating:** ✅|⚠️|🔧|❌
**Conflicts:** <list contradictions surfaced before edit, or "None">
**Issues:** <table: issue / criterion / recommendation>
**Changes made:** <bullet list>
**Files to delete (require confirmation):** <list, or omit>
If invoked as a sub-agent for routing reasons, follow the response contract from delegate-task.
Anti-patterns
- Frontmatter on AGENTS.md (the spec is plain Markdown).
- Persona or tone text (belongs in agent system prompts; see
write-assistant).
- File-by-file codebase tours; long API documentation (link instead).
- Generic LLM instructions.
- Time-sensitive content (dates, drifting version numbers).
- Empty sections kept "for completeness".
- Restating standard language conventions.
References
references/platforms.md - per-platform discovery, override files, disabling, and the full consolidation search list.references/sections.md - canonical section template with one minimal example each.references/migration.md - rename, import-shim, and symlink recipes for legacy filenames.
Related skills: write-skill (for SKILL.md files), write-assistant (for agent system prompts).
