agents-md-maintainer

Use this skill after nontrivial implementation work and before finalizing when you need to decide whether AGENTS.md should change.

Rules

• Treat AGENTS.md as durable repo guidance, not a task log.
• Run a brief AGENTS.md maintenance pass at the end of implementation.
• Do not modify AGENTS.md unless the implemented code, tests, and docs state already proves the new rule.
• Update AGENTS.md only for durable repo-wide guidance such as:
  • required build, test, lint, typecheck, or verification commands
  • architecture invariants or hard constraints
  • canonical data shapes, contracts, directory ownership, or file locations
  • repo-wide coding, review, or release expectations
  • recurring failure modes that future sessions must avoid
• Do not update AGENTS.md for one-off feature details, branch context, temporary migrations, issue notes, task plans, historical summaries, or implementation narration.
• Keep edits minimal and high-signal. Prefer replacing, tightening, deduplicating, or deleting existing bullets over appending prose.
• Keep AGENTS.md clean, concise, and production-facing.
• Do not include working-session phrasing such as Phase, plan, follow-up, or similar developer-tracking language.
• Write rules as short, concrete, imperative bullets that a coding agent can apply immediately in a new session with no prior chat context.
• Keep root AGENTS.md limited to broadly applicable guidance. Put scoped rules in the nearest folder-level AGENTS.md. Put reusable workflows in skills or referenced docs.
• Ensure every AGENTS.md edit matches the current codebase exactly, and remove stale or superseded guidance in the same pass.
• Use $reducing-entropy, $clean-code, and $hard-cut when deciding whether guidance should be added, tightened, or deleted.
• If delegation is allowed and helpful, use a small subagent to compare the implemented diff against AGENTS.md and propose the smallest valid patch.
• Before finishing, verify that each AGENTS.md change is:
  • durable
  • repo-relevant
  • non-duplicative
  • consistent with current code and tests
  • useful to a coding agent starting from zero context
• Leave AGENTS.md unchanged if any of those checks fail.

Workflow

1. Compare the implemented diff against the current AGENTS.md.
2. Decide whether the completed work changed durable repo guidance.
3. Stop if the answer is no.
4. If the answer is yes, make the smallest valid patch.
5. Re-check the edited guidance against the current codebase, tests, and docs.
6. Delete or tighten any stale, duplicated, or superseded bullets in the same pass.

Examples

• Update AGENTS.md if the repo now requires a new canonical verification command before completion.
• Do not update AGENTS.md if the work only added a feature-specific route, component, or migration note.