review-agents-md

# 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.