write-agents-files

name	write-agents-files
description	Use when setting up or improving agent instructions in AGENTS.md, CLAUDE.md or other coding agents instructions files.
version	0.1.1

Writing Effective AGENTS.md Files

Create and maintain effective AGENTS.md files following best practices.

Keep instructions brief, unlock agentic loops, document gotchas, and reference task-specific files.

Table of Contents

• Core Principle: Map, Not Manual
• Common Sections in AGENTS.md
• Instructions
  • 1. Understand Context
  • 2. Draft Core Instructions
  • 3. Add Agentic Loop Tools
  • 4. Create Gotchas Section
  • 5. Reference Task-Specific Files
  • 6. Validate Against Best Practices
• Best Practices
• Examples
• Requirements
• See Also

Core Principle: Map, Not Manual

Use progressive disclosure: the main AGENTS.md is a small, stable entry point that tells the agent where to look next.

Treat the file as a table of contents, not an encyclopedia:

• Context is scarce: long instruction blobs crowd out the task and the code.
• Too much guidance becomes non-guidance: when everything is "important", the agent pattern-matches instead of navigating.
• Monoliths rot: big manuals get stale quickly and humans stop maintaining them.
• Hard to verify: blobs are difficult to lint for freshness, ownership, and cross-links.

Practical rule of thumb:

• Keep the main AGENTS.md around ~100 lines.
• Put deeper sources of truth in dedicated files (often a structured docs/ directory) and link to them from AGENTS.md.

Example in-repo knowledge store layout (adapt as needed):

AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│   └── index.md
├── product-specs/
│   └── index.md
├── exec-plans/
│   ├── active/
│   └── completed/
└── references/
    └── topic-llms.txt

Common Sections in AGENTS.md

Based on OpenAI best practices, effective AGENTS.md files typically include these common sections:

1. Project overview and structure - Brief description and key directories
2. Build and test commands - Concrete verification commands
3. Helpful CLI tools and MCP servers - Tools and servers the agent can use
4. Workflow for implementing a feature - Step-by-step feature implementation
5. Pointers to task-specific guidance - Links to specialized documentation

Instructions

1. Understand Context

Before creating or updating an AGENTS.md file:

Gather information:

• Ask the user about their project type (web app, CLI tool, library, etc.)
• Identify key workflows (testing, building, deploying)
• Determine what tools the agent should use (linters, test runners, formatters)
• Understand common mistakes or gotchas in their codebase

Read existing context:

• Check for existing AGENTS.md, README.md, or CONTRIBUTING.md files
• Scan recent commit messages for patterns
• Review test and build scripts

2. Draft Core Instructions

Keep it brief and focused:

• Target: Under 100 lines for main AGENTS.md (most OpenAI AGENTS.md files are under 100 lines)
• Use clear, imperative language (verb-first)
• Focus on WHAT and WHY, not HOW (agents are smart enough)
• Avoid over-explaining concepts the agent already knows
• Prefer progressive disclosure: keep the top-level file scannable and link to deeper guidance.

Structure:

# Project Name

Brief 1-2 sentence project description.

## Project Overview

Brief description of the project purpose and scope.

## Repository Structure

Key directories and files:
- `src/` - Source code
- `tests/` - Test files
- `docs/` - Documentation
- `config/` - Configuration files

## Build

Commands to build the project:
```bash
npm run build
```

## Testing

Commands to run tests:
```bash
npm test
```

## Helpful Tools (CLI + MCP)

Tools and servers the agent can use:

- **CLI tools**
  - Linter: `npm run lint`
  - Type checker: `npm run typecheck`
  - Test runner: `npm test`
  - Build tool: `npm run build`

- **MCP servers**
  - List the MCP servers available in your environment
  - Include what each is for and when to use it

## Feature Workflow

Step-by-step feature implementation:
1. Identify entry points and relevant files
2. Make a small plan (if non-trivial)
3. Implement and update/add tests
4. Run verification commands
5. Update gotchas/docs if new pitfalls discovered
6. Summarize changes and remaining risks

## Gotchas Codex

[See Gotchas section below]

## Detailed Guidelines

For specific workflows, see:
- **Architecture**: [ARCHITECTURE.md](./ARCHITECTURE.md)
 : []()
 : []()

Example brief instruction:

## Testing

Run the full test suite before committing:
```bash
npm test
```

Fix any failing tests immediately. Do not commit failing tests.

3. Add Agentic Loop Tools

Unlock agentic loops by explicitly listing tools the agent can call to verify its own work.

Common verification tools:

• Linters: ESLint, Pylint, Ruff, Clippy
• Formatters: Prettier, Black, rustfmt
• Type checkers: TypeScript, mypy, pyright
• Test runners: Jest, pytest, cargo test
• Build tools: npm run build, cargo build, make
• Git hooks: pre-commit, husky

Template:

## Build

Commands to build the project:
```bash
npm run build
```

## Testing

Commands to run tests:
```bash
npm test
```

## Helpful Tools (CLI + MCP)

Tools and servers the agent can use:

- **CLI tools**
  - Linter: `npm run lint` - Check code style and catch errors
  - Type checker: `npm run typecheck` - Verify type safety
  - Tests: `npm test` - Run full test suite
  - Build: `npm run build` - Ensure production build succeeds

- **MCP servers**
  - List the MCP servers available in your environment
  - Include what each is for and when to use it
  - Example: Context7 for library API lookups, Exa for code context

Key principle: Show the agent what success looks like by listing concrete verification commands.

4. Create Gotchas Section

Continuously update with real mistakes. Maintain a living "Gotchas Codex" section that evolves through:

• Pull request reviews
• Production incidents
• Repeated mistakes by the agent or team

Format:

## Gotchas Codex

Common mistakes to avoid (updated from real issues):

### API Rate Limits
- The external API has a 100 req/min limit
- Always implement exponential backoff
- Cache responses when possible
- Added: 2025-01-15 (PR #123)

### Database Migrations
- Never auto-generate migration names
- Use descriptive names: `YYYY-MM-DD-description.sql`
- Test rollback before deploying
- Added: 2025-01-10 (Incident #456)

### Test Flakiness
- Tests depending on `Date.now()` are flaky
- Use `jest.useFakeTimers()` for time-dependent tests
- Added: 2025-01-08 (PR #789)

Update protocol:

• Add new gotchas with date and source (PR number, issue, incident)
• Keep gotchas specific and actionable
• Remove resolved gotchas (if root cause is fixed)
• Review quarterly to keep relevant

5. Reference Task-Specific Files

Point to task-specific .md files instead of bloating the main AGENTS.md.

For larger repos, prefer a dedicated knowledge base (often docs/) and link to it from the main AGENTS.md. Keep it navigable with an index and clear "where to look next" pointers.

Common specialized files:

• PLANS.md: Design and iteration guidelines before implementation
• ARCHITECTURE.md: System design, component relationships
• API.md: API design standards and patterns
• TESTING.md: Detailed testing strategies and patterns
• DEPLOYMENT.md: Release and deployment procedures
• CONTRIBUTING.md: Contribution guidelines

Reference format:

# Project Name

Core instructions here (keep under 100 lines).

## Detailed Guidelines

For specific workflows, see:

- **Planning**: [PLANS.md](./PLANS.md) - Design iteration process
- **Architecture**: [ARCHITECTURE.md](./ARCHITECTURE.md) - System overview
- **Testing**: [TESTING.md](./TESTING.md) - Testing standards
- **API Design**: [API.md](./API.md) - API conventions

Consult these files before starting complex work.

When to split:

• Main AGENTS.md approaching 100 lines → Extract details to specialized files
• Complex domain-specific rules → Create dedicated .md file
• Lengthy examples or templates → Move to examples directory

6. Validate Against Best Practices

Before finalizing, check:

✓ Brevity: Under 100 lines for main AGENTS.md? ✓ Agentic loops: Are verification tools listed with commands? ✓ Gotchas: Is there a living section for real mistakes? ✓ References: Are specialized topics in separate .md files? ✓ Map: Does AGENTS.md act as a table of contents (progressive disclosure) instead of a dump? ✓ Clarity: Can a new agent understand instructions immediately? ✓ Actionability: Are all instructions concrete and executable? ✓ Common sections: Does it include project overview, build/test, tools (CLI+MCP), feature workflow?

Ask the user:

• "What verification tools should the agent run?"
• "What are the most common mistakes in this codebase?"
• "Are there complex workflows that need separate documentation?"
• "What MCP servers are available for this project?"

Best Practices

Keep It Brief

• Most OpenAI AGENTS.md files are under 100 lines
• Too many instructions confuse the coding agent
• Extract detailed guidelines to separate files
• Trust the agent's base knowledge

Common Mistakes to Avoid:

• ❌ Don't write 500-line AGENTS.md files (defeats the purpose of brevity)
• ❌ Don't skip the verification tools section (prevents agentic loops)
• ❌ Don't use vague gotchas like "be careful with API" (be specific with limits and solutions)
• ❌ Don't embed lengthy examples in AGENTS.md (move to separate files)

Unlock Agentic Loops

• Show the agent tools to verify its own work (linters, tests, etc.)
• List concrete commands, not vague instructions
• Enable self-correction without human intervention
• If you find yourself repeatedly doing the same steps after the agent runs, add those to AGENTS.md

Document Real Failures

• Keep a "Gotchas Codex" section
• Update it in version control (PRs, reviewers, changelog)
• Make it specific: "Added: 2025-01-15 (PR #123)"
• Remove obsolete gotchas as root causes are fixed
• When a human steps in to finish a task, ask: "What capability was missing, and how can we make it legible and enforceable for the agent?" Then update AGENTS.md, deeper docs, or verification commands.

Split Complex Topics

• Reference specialized .md files from main AGENTS.md
• Examples: PLANS.md for design iteration, ARCHITECTURE.md for system overview
• Keeps main file focused and scannable
• Enables deeper dives without clutter

Include Common Sections

• Follow the common sections pattern: project overview, repository structure, build/test commands, helpful tools (CLI + MCP), feature workflow, gotchas, and references
• This ensures consistency across projects and makes AGENTS.md files easier to navigate

Examples

See examples/ directory for complete examples:

• examples/MINIMAL.md: Bare minimum AGENTS.md (under 50 lines)
• examples/WEB-APP.md: Full-featured web app with verification tools and MCP server example
• examples/LIBRARY.md: Library with API guidelines and publishing workflow
• examples/GOTCHAS.md: Rich Gotchas Codex from real project

Requirements

• Project with codebase (git repository recommended)
• Access to development tools (linters, test runners, build tools)
• Understanding of project workflows and common issues

Limitations

• Cannot automatically detect all gotchas (requires human input over time)
• Best practices may need adjustment for specific domains
• Requires ongoing maintenance to keep gotchas section relevant

See Also

• evaluate-skills: Evaluate skills against best practices
• commit-message-generator: Generate conventional commit messages
• verify-release-readiness: Verify release readiness for skills and plugins