agents-md

AGENTS.md Skill

Create or review AGENTS.md files -- the per-repo instruction file for AI coding agents.

What AGENTS.md is (and isn't)

AGENTS.md is Layer 2 in a four-layer context model:

• •Layer 1 -- The code itself. Agents discover this independently. Never duplicate it in AGENTS.md.
• •Layer 2 -- Per-repo context (AGENTS.md). Non-obvious, human-written instructions. This is what we generate.
• •Layer 3 -- Org-level context. Cross-repo architecture decisions, ADRs, service boundaries. Belongs in an architecture repo, not here.
• •Layer 4 -- External references. Upstream docs, standards. Managed via BOOKMARKS.md.

Every line in AGENTS.md must pass one test: can the agent figure this out from the code? If yes, delete it. Research (ETH Zurich 2026) shows that duplicating discoverable information actively hurts agent performance and increases costs by 20%+.

Mode A: Create

Step 1 -- Check for existing AGENTS.md

Look for AGENTS.md at the repo root. If found, inform the user and suggest Review mode instead. Only regenerate if the user explicitly confirms.

Step 2 -- Explore the codebase

Before asking questions, scan for signals that answer common questions automatically:

Step 3 -- Ask only what can't be inferred

Use structured questions (AskQuestion tool when available). Typical questions:

• •Which AI agents does your team use? (Cursor, Claude Code, Copilot, Gemini CLI, other)
• •How are secrets managed? (env vars, Vault, AWS Secrets Manager, sealed secrets, other)
• •Any auth flows agents should know about? (SSO, API keys, OAuth, service accounts)
• •Any paths or operations that should be off-limits to agents?

Skip any question the codebase already answers. If the exploration in Step 2 found clear answers, don't re-ask.

Step 4 -- Generate AGENTS.md

Read template.md for the section catalog. Generate AGENTS.md at the repo root.

Rules:

• •Include only applicable sections. Omit any section that doesn't apply.
• •Write opinionated, specific instructions -- not generic descriptions.
• •Target 40-80 lines. If you need more, create a BOOKMARKS.md companion file.
• •Commands section goes first. Use exact commands with flags, not tool names.
• •Boundaries use three tiers: Always do / Ask first / Never do.
• •Reference existing code by file:line, not by pasting snippets (they go stale).

Scaffold warning (present this to the user after generating):

This is a starting point, not a finished file. Expect to rewrite or delete 30-50% of it. For every line, ask yourself: can the agent figure this out from the code? If yes, delete it. The value is in the structure and the non-obvious instructions, not in restating what's already in your codebase.

Also create thin pointer files for other AI tools the team uses (from Step 3):

• •CLAUDE.md -- See AGENTS.md for full agent instructions.
• •.cursor/rules/agents.md or .cursorrules -- reference AGENTS.md, add Cursor-specific overrides only.
• •.github/copilot-instructions.md -- reference AGENTS.md.

Only create pointers for tools the team actually uses. AGENTS.md is the single source of truth.

Step 5 -- Self-validate

Read anti-patterns.md. Run the Review checklist (Mode B) against the generated file. Flag any weak sections to the user before delivering.

Mode B: Review

Read the existing AGENTS.md and anti-patterns.md. Also explore the codebase (same signals as Create Step 2) to verify the file matches reality.

Rate five criteria. For each, assign Good, Weak, or Missing:

Output a section-by-section report with ratings and concrete fix suggestions. For each Weak or Missing item, provide the specific text to add or change.

Progressive disclosure: good-example.md is NOT loaded by default. Only read it if the user asks to see an example of a well-structured AGENTS.md.