agents-md

Agents Md

Create and maintain concise, high-signal AGENTS guidance with progressive disclosure.

Table of Contents

• When to use
• Standards snapshot
• Required inputs
• Discovery interview
• Response format
• Deliverables
• Failure mode
• Philosophy
• Constraints
• Procedure
• Validation
• Project-tailored repo baseline
• Anti-patterns
• Variation
• AGENTS.md Template Guidance
• Mandatory workflow snippet
• Examples
• Resource map
• Decision Quality Feedback

When to use

• Use this skill when the user asks to create or update AGENTS.md.
• Use this skill when AGENTS docs are too large, duplicated, or contradictory.
• Use this skill when instruction routing needs to be split into linked files.
• Use this skill when a repo needs AGENTS operating rules such as preflight, stack detection, tooling, required paths, Local Memory policy, Project Brain policy, or startup workflow tailored from real repo evidence.
• Use this skill when the user wants the project's instruction surface audited so required instruction files are present, current, correctly routed, and accurately disclosed.

Standards snapshot (April 2026)

Use this section as an adaptation guideline for generated AGENTS.md files, not runtime policy.

• Keep root AGENTS.md minimal and route depth into linked docs.
• Start with 2-3 focused surfaces for a first pass: usually the root AGENTS.md, one linked-doc tree, and only one nested override if it is truly needed.
• Teach the canonical discovery chain: global AGENTS.override.md or AGENTS.md, then per-directory AGENTS.override.md, AGENTS.md, then configured fallback filenames.
• Treat only one auto-loaded instruction file per directory as canonical; linked docs are progressive-disclosure references, not implicitly discovered project instructions.
• Keep combined project guidance under the project_doc_max_bytes budget (32 KiB default) by splitting large guidance across nested scopes instead of bloating one root file.
• Instruction budget: frontier thinking models can reliably follow ~150–200 instructions. Every token in AGENTS.md loads on every request regardless of relevance, so every instruction must earn its place.
• Minimum viable floor: the root file needs only three things — a one-sentence project description, the package manager if not npm, and any non-standard build/typecheck commands. Everything else is a candidate for progressive disclosure.
• Staleness is poison: avoid documenting file paths in AGENTS.md; they change constantly and agents read stale paths confidently. Describe capabilities and where things might be rather than hardcoding structure.
• Never auto-generate AGENTS.md files; generated files flood the budget with generic instructions that hurt performance. Write them intentionally.
• When harmonizing AGENTS.md, CLAUDE.md, and GEMINI.md, keep shared operational rules semantically aligned while respecting each tool's official instruction-file model and section conventions. For cross-tool coverage, a ln -s AGENTS.md CLAUDE.md symlink is a valid low-maintenance option when Claude Code is in scope.
• Base commands, paths, and conventions on verified repo evidence only.
• Treat contradiction detection and instruction precedence as first-class outputs.
• Prefer progressive disclosure over megadoc accumulation.