wimpysworld/nix-config/write-agents-md

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

1. Discover instruction files using the list in references/platforms.md.
2. Extract project-specific rules from each; drop duplicates and generic advice.
3. Flag conflicts for user resolution; do not silently pick a winner.
4. Preserve runnable commands verbatim.
5. 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.
6. Require explicit confirmation before deleting any file.

Review

Assessment scale:

Review criteria specific to AGENTS.md (agent-prompt criteria belong in write-assistant):

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 worker 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).