Agent Skills: AGENTS.md Manager

AGENTS.md Manager

Build and maintain high-quality AGENTS.md files that maximize AI coding agent efficiency.

Core Principle

AI coding agents are stateless. AGENTS.md is the only file that goes into every conversation. It must onboard the agent to your codebase efficiently without bloating the context window.

Critical insight: AI agents may ignore AGENTS.md contents if deemed irrelevant. Overstuffed files with non-universal instructions get ignored entirely.

Three Pillars of a Good AGENTS.md

Every AGENTS.md should answer three questions concisely:

1. WHAT - Tech stack, project structure, key directories
2. WHY - Project purpose, what each part does
3. HOW - Essential commands, verification steps, workflows

Hard Constraints

| Constraint | Limit | Rationale | |------------|-------|-----------| | Total lines | < 300 (ideal: < 100) | Context window is shared with system prompt, conversation, tools | | Instructions | < 100 | Frontier models reliably follow ~150-200 instructions; system prompt uses ~50 | | Applicability | 100% universal | Non-universal instructions cause entire file to be ignored |

What NOT to Include

• Code style guidelines - Use linters/formatters instead. LLMs learn from codebase patterns.
• One-off task instructions - Put in slash commands or separate docs
• Code snippets - Become stale; use file:line pointers instead
• Auto-generated content - Auto-init output is generic; craft manually
• Conditional instructions - Use progressive disclosure instead

Progressive Disclosure Pattern

Keep AGENTS.md lean by pointing to detailed docs:

project/
├── AGENTS.md              # Core onboarding only (<100 lines)
└── agent_docs/            # Detailed docs loaded on demand
    ├── building.md
    ├── testing.md
    ├── database_schema.md
    ├── architecture.md
    └── deployment.md

In AGENTS.md, include a brief index:

## Documentation

Read relevant docs from `agent_docs/` before starting work:
- `building.md` - Build commands and dependencies
- `testing.md` - Test execution and coverage
- `database_schema.md` - Table schemas and relationships
- `architecture.md` - Service structure and communication
- `deployment.md` - Deployment procedures and environments

Prefer pointers to copies - Reference file:line instead of embedding code.

AGENTS.md Template Structure

See references/template.md for a complete template.

Minimal structure:

# Project Name

Brief one-line description.

## Stack

- Language/Framework: X
- Database: Y
- Key dependencies: Z

## Project Structure

app/          - Main application code
lib/          - Shared utilities
tests/        - Test suite

## Commands

Build:  `command here`
Test:   `command here`
Lint:   `command here`

## Documentation

Read from `agent_docs/` as needed:
- `file.md` - Description

Creating a New AGENTS.md

1. Analyze the project - Identify stack, structure, key workflows
2. Start minimal - Begin with <50 lines covering essentials
3. Create agent_docs/ - Move detailed documentation there
4. Add pointers - Reference agent_docs from AGENTS.md
5. Validate - Run checklist from references/checklist.md

Auditing an Existing AGENTS.md

1. Count lines - Flag if >300 lines
2. Check universality - Every instruction should apply to every task
3. Find embedded code - Replace with file:line pointers
4. Identify style rules - Move to linter config
5. Extract conditionals - Move to agent_docs/
6. Validate - Run checklist from references/checklist.md

Integrations

Pre-commit Hooks (for formatting/linting)

Instead of style instructions, configure pre-commit hooks:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: lint-fix
        name: Auto-fix lint issues
        entry: npm run lint:fix && npm run format
        language: system
        pass_filenames: false

Custom Commands (for specific workflows)

Create project-specific commands directory for task-specific instructions that shouldn't bloat AGENTS.md.

Reference Files

• references/template.md - Complete AGENTS.md template with examples
• references/checklist.md - Validation checklist for auditing
• references/progressive-disclosure.md - Guide for organizing agent_docs/