AGENTS.md Skill

Overview

Creates and refactors AGENTS.md files following progressive disclosure principles. Keeps files minimal and focused—avoiding the "ball of mud" that hurts agent performance.

When to Use

• Proactively when a project has no AGENTS.md at the root — check for this when starting work in a new project
• Creating a new AGENTS.md from scratch
• Refactoring a bloated AGENTS.md
• Reviewing an existing file for best practices
• Setting up AGENTS.md for a monorepo
• When AGENTS.md exists but CLAUDE.md is missing (should be symlinked)

Core Principles

1. Minimal by default: Only include what's relevant to every single task
2. Progressive disclosure: Point to separate files, external docs, or agent skills for domain-specific rules
3. Never document file structure: It goes stale fast and poisons agent context
4. Describe capabilities, not locations: "Auth uses JWT" not "Auth is in src/auth/"

The Instruction Budget

Frontier LLMs can follow ~150-200 instructions with reasonable consistency. Every token in AGENTS.md loads on every request, regardless of relevance. The ideal file should be as small as possible.

Why Files Get Bloated

Agent does something wrong → you add a rule → repeat hundreds of times → "ball of mud." Different developers add conflicting opinions. Nobody does a full style pass. Auto-generated files make this worse by prioritizing comprehensiveness over restraint.

Stale Docs Poison Context

Humans can be skeptical of outdated docs. Agents can't — they trust what they read on every request. File paths are especially dangerous since they change constantly. Describe capabilities and domain concepts instead.

Process

Phase 0: Detect Missing Files

Check the project root for AGENTS.md and CLAUDE.md:

1. If neither exists, offer to create AGENTS.md and symlink CLAUDE.md to it
2. If AGENTS.md exists but CLAUDE.md does not, create the symlink: ln -s AGENTS.md CLAUDE.md
3. If CLAUDE.md exists but AGENTS.md does not, rename it to AGENTS.md and create a symlink: mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
4. If both exist but CLAUDE.md is not a symlink to AGENTS.md, merge any unique content into AGENTS.md, remove the standalone CLAUDE.md, and create the symlink

Phase 1: Assess Current State

For new projects:

• Ask about the project's purpose (one sentence)
• Ask about package manager (if not npm)
• Ask about non-standard build commands

For existing files:

• Read the current AGENTS.md
• Count lines and estimate token cost
• Identify content that belongs elsewhere

Phase 2: Apply the Essential Test

Only these belong in root AGENTS.md:

Everything else goes in separate files or gets deleted.

Phase 3: Identify Anti-Patterns

Flag these for removal or relocation:

• File tree structures: Always go stale, waste tokens
• Obvious instructions: "Write clean code", "Use meaningful names"
• Contradictory rules: Often from multiple contributors
• Language-specific conventions: Move to docs/TYPESCRIPT.md etc.
• Workflow instructions: Move to docs/GIT.md or docs/TESTING.md

Phase 4: Create Progressive Disclosure Structure

For content that shouldn't be deleted:

docs/
├── TYPESCRIPT.md    # TS conventions
├── TESTING.md       # Test patterns
├── API.md           # API design rules
└── GIT.md           # Commit/PR conventions

Reference these from AGENTS.md with light-touch pointers. Keep the tone conversational — no "ALWAYS," no all-caps forcing:

For TypeScript conventions, see docs/TYPESCRIPT.md

Each file can reference the next — agents walk the tree on demand, only loading what's relevant.

Link to external docs when they're the authoritative source rather than restating them:

For database migrations, follow the Prisma migration guide.

Agent skills are another layer of progressive disclosure. Instead of embedding procedures in AGENTS.md, package them as skills the agent pulls in when needed. The root file stays focused on what and where; skills handle how.

Phase 5: Handle Monorepos

For monorepos, use nested AGENTS.md files:

Root AGENTS.md:

Monorepo for [purpose]. Uses [pnpm/yarn] workspaces.
See each package's AGENTS.md for specifics.

Package AGENTS.md (e.g., packages/api/AGENTS.md):

GraphQL API using Prisma. See docs/API_CONVENTIONS.md for patterns.

Phase 6: Output

Provide:

1. The new/refactored AGENTS.md content
2. Any new files created for progressive disclosure
3. List of removed content with reasoning

Output Format

When creating a new AGENTS.md:

# [Project Name]

[One-sentence description of what this project does.]

[Package manager if not npm]

[Non-standard commands if any]

[Light-touch pointers to separate docs if needed]

Example: Minimal AGENTS.md

# Acme Dashboard

React admin dashboard for managing customer accounts and billing.

Uses pnpm. Run `pnpm check` for type checking.

For API conventions, see docs/API.md
For component patterns, see docs/COMPONENTS.md

That's 6 lines. Every token earns its place.

Refactoring Prompt

When refactoring an existing bloated file, follow these steps:

1. Find contradictions: Identify conflicting instructions. Ask which to keep.
2. Identify essentials: Extract only what belongs in root — project description, package manager, non-standard commands, content relevant to every task.
3. Group the rest: Organize into logical categories. Create separate files.
4. Create structure: Output minimal root AGENTS.md with links to separate files.
5. Flag for deletion: Identify instructions that are redundant, vague, or obvious.

Decision Framework

Before adding anything to AGENTS.md:

Cross-Tool Compatibility

AGENTS.md is an open standard supported by 20+ tools including:

• GitHub Copilot (Coding Agent)
• Cursor
• Codex (OpenAI)
• Gemini CLI (Google)
• Windsurf, Devin (Cognition)
• Zed, Warp, VS Code
• Aider, goose, RooCode

Claude Code uses CLAUDE.md instead. AGENTS.md is always the source of truth. CLAUDE.md must always be a symlink pointing to it:

ln -s AGENTS.md CLAUDE.md

Never create a standalone CLAUDE.md. Never put content in CLAUDE.md that isn't in AGENTS.md.

Resources

• https://agents.md — The AGENTS.md specification
• https://www.aihero.dev/a-complete-guide-to-agents-md — Guide that informed this skill's best practices