agents-md

ADD AGENTS.md Skill v{{VERSION}}

Generate a portable AGENTS.md at project root from the project's .add/ state. AGENTS.md is the cross-tool open standard for project-level agent instructions — any agent (Claude Code, Cursor, Codex CLI, Windsurf, Amp, Devin, Copilot) will read it on session start. Publishing one lets mixed-toolchain teams respect the same invariants without installing ADD.

This skill is the only way to regenerate AGENTS.md. A PostToolUse hook marks the file stale when source inputs change — the human triggers the actual regeneration.

Invocation

/add:agents-md               # default: --write
/add:agents-md --check       # drift detection, CI-friendly (exit 1 on drift)
/add:agents-md --merge       # prepend ADD block to an existing hand-curated AGENTS.md
/add:agents-md --import      # one-time absorption (same as --merge; explicit intent)
/add:agents-md --dry-run     # preview without writing (combines with any mode)

Pre-Flight Checks

1. Read .add/config.json

   • Load project.name, project.description
   • Load maturity.level (poc | alpha | beta | ga)
   • Load architecture.languages — determines whether the TDD Discipline section applies
   • Load environments.*.autoPromote — determines the autonomy ceiling summary

2. Read docs/prd.md if present

   • The H1 + first paragraph become the project identity section
   • If absent, fall back to project.description from config

3. Read .add/handoff.md if present

   • Extract the currently-active spec reference (first specs/*.md match in the file)
   • If absent, pick the most recently mutated specs/*.md by mtime

4. Check .add/agents-md.stale

   • If present, announce the stale state and the source files that changed since the last regen
   • This marker is removed automatically after a successful --write

5. Detect existing AGENTS.md

   • No file → default --write creates it fresh
   • File with ADD marker block → --write replaces managed content, preserves user-authored content outside the markers
   • File without ADD marker → --write aborts with guidance to use --merge or --import
   • Frontmatter (YAML / TOML / +++) at top is preserved verbatim