write-agents-files

What this skill does

# 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](#core-principle-map-not-manual)
- [Common Sections in AGENTS.md](#common-sections-in-agentsmd)
- [Instructions](#instructions)
  - [1. Understand Context](#1-understand-context)
  - [2. Draft Core Instructions](#2-draft-core-instructions)
  - [3. Add Agentic Loop Tools](#3-add-agentic-loop-tools)
  - [4. Create Gotchas Section](#4-create-gotchas-section)
  - [5. Reference Task-Specific Files](#5-reference-task-specific-files)
  - [6. Validate Against Best Practices](#6-validate-against-best-practices)
- [Best Practices](#best-practices)
- [Examples](#examples)
- [Requirements](#requirements)
- [See Also](#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):

```text
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:**
````markdown
# 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)
- **API Design**: [API.md](./API.md)
- **Testing**: [TESTING.md](./TESTING.md)
````

**Example brief instruction:**
````markdown
## 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:**
````markdown
## 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:**
```markdown
## 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:**
```markdown
# Project Name

Core instructions here (keep under 100 lines).

## Detailed Guidelines

For specific wor