agent-docs

Original source / Raw SKILL.md

---
name: agent-docs
description: >-
  Documentation for AI agents — AGENTS.md, CLAUDE.md, and agent-readable content patterns.
  Use when creating agent entry points, structuring .claude/ directories, or when
  "CLAUDE.md", "AGENTS.md", "agent documentation", "machine-readable", or "writing for agents"
  are mentioned. Covers both configuration and content patterns for agent consumption.
metadata:
  version: "1.1.0"
  author: outfitter
  category: documentation
---

# Documentation for Agents

Structure and patterns for documentation that AI agents consume — the files and directories that help Claude, Codex, and other agents understand and work with your project.

For human-facing documentation (READMEs, guides, API docs), load the `internal:docs-write` skill.

## File Architecture

The recommended setup separates tool-agnostic agent guidelines from tool-specific configuration:

```
project/
├── AGENTS.md              # Canonical agent instructions (tool-agnostic)
├── CLAUDE.md              # Entry point that @-mentions AGENTS.md
└── .claude/
    ├── CLAUDE.md          # Claude-specific instructions
    ├── commands/          # Slash commands
    ├── skills/            # Project-specific skills
    ├── rules/             # Modular rule files
    └── settings.json      # Permissions, MCP servers
```

### Why This Structure?

- **AGENTS.md** works across tools (Claude, Codex, Cursor, etc.)
- **@-mentions** avoid duplication and keep CLAUDE.md minimal
- **.claude/** holds Claude-specific extensions without polluting shared docs
- **Modular rules** allow topic-specific guidance without bloating main files

## AGENTS.md

The canonical source of agent instructions. Tool-agnostic — works for Claude, Codex, and other AI assistants.

**Location**: Project root

**Purpose**: Project context, conventions, and guidelines that any AI agent should follow.

### Structure Template

```markdown
# AGENTS.md

Guidelines for AI agents and developers working in this repository.

## Project Overview

Brief description of what this project does and its current status.

## Project Structure

- `src/` — Source code
- `tests/` — Test files
- `docs/` — Documentation

## Commands

\`\`\`bash
bun test              # Run tests
bun run build         # Build project
bun run lint          # Lint and format
\`\`\`

## Architecture

Key architectural decisions and patterns used in this codebase.

## Development Principles

Core principles: TDD, error handling patterns, dependency policies.

## Code Style

Language-specific conventions, formatting rules, naming patterns.

## Testing

Test runner, file locations, coverage expectations.

## Git Workflow

Branch naming, commit conventions, PR process.
```

### What Belongs in AGENTS.md

| Include | Exclude |
|---------|---------|
| Project structure overview | Tool-specific instructions |
| Key commands | Claude task management |
| Architectural patterns | Codex sandbox config |
| Development principles | MCP server setup |
| Code style conventions | IDE settings |
| Testing approach | |
| Git workflow | |

### Length Guidelines

- **Target**: 100-300 lines
- **Maximum**: 500 lines
- **Principle**: Comprehensive but scannable — agents should find what they need quickly

## CLAUDE.md (Root)

Minimal entry point that @-mentions other files. Claude Code reads this first.

**Location**: Project root

**Purpose**: Bootstrap Claude's context by pointing to the right files.

### Recommended Pattern

```markdown
# CLAUDE.md

This file provides AI agents with project-specific context and conventions.

@.claude/CLAUDE.md
@AGENTS.md
```

That's it. Keep the root CLAUDE.md minimal.

### Why @-mentions Over Symlinks?

Previously, some projects used symlinks between CLAUDE.md and AGENTS.md. **Don't do this.**

Problems with symlinks:
- Git treats them inconsistently across platforms
- Some tools don't follow symlinks
- Confusing when editing — which file is canonical?
- Breaks when repo is cloned to paths with different structures

The @-mention pattern is explicit, portable, and clear about which file is authoritative.

## .claude/CLAUDE.md

Claude-specific instructions that don't apply to other tools.

**Location**: `.claude/CLAUDE.md`

**Purpose**: Claude Code features, task management, tool-specific guidance.

### Example Content

```markdown
# Claude-Specific Guidance

## Task Management

Use the task tools to track work across context windows.

### Creating Tasks

Use `TaskCreate` for multi-step work:
- `subject`: Imperative form ("Run tests")
- `activeForm`: Present continuous ("Running tests")
- `description`: Detailed requirements

### Best Practices

- Create tasks immediately when receiving multi-step instructions
- Keep exactly one task `in_progress` at a time
- Never mark completed if tests fail

## Preferred Tools

- Use `gt` for version control, not raw `git`
- Prefer `Grep` tool over bash grep
- Use `Read` tool instead of `cat`
```

### What Belongs in .claude/CLAUDE.md

| Include | Exclude |
|---------|---------|
| Task management patterns | Project architecture |
| Claude-specific tool preferences | Code style (goes in AGENTS.md) |
| MCP server usage | Testing approach |
| Subagent coordination | Git workflow |

## .claude/rules/

Modular, topic-specific rule files. Auto-loaded into Claude's context.

**Location**: `.claude/rules/*.md`

**Purpose**: Focused guidance on specific topics — language conventions, testing patterns, API standards.

### When to Use Rules Files

Use `.claude/rules/` for:
- Language-specific guidelines (TYPESCRIPT.md, RUST.md)
- Testing conventions (TESTING.md)
- API standards (API.md)
- Security requirements (SECURITY.md)

### Paths Frontmatter

Rules can be scoped to specific file patterns:

```markdown
---
paths:
  - "**/*.ts"
  - "**/*.tsx"
---

# TypeScript Conventions

Use strict mode. Avoid `any`. Prefer `unknown` for truly unknown types.
```

This rule only loads when working with TypeScript files.

### Codex Compatibility Note

Codex CLI doesn't support `.claude/rules/` or `paths` frontmatter. Keep critical conventions in AGENTS.md to ensure all tools see them.

**Guidance**: Use rules files sparingly. If a convention matters for all agents, put it in AGENTS.md. Reserve rules files for Claude-specific enhancements that won't break the experience for other tools.

## Directory Structure: .claude/

```
.claude/
├── CLAUDE.md           # Claude-specific instructions
├── commands/           # Slash commands
│   ├── build.md
│   ├── test.md
│   └── deploy.md
├── skills/             # Project-specific skills
│   └── local-skill/
│       └── SKILL.md
├── rules/              # Modular rule files
│   ├── TYPESCRIPT.md
│   ├── TESTING.md
│   └── SECURITY.md
├── hooks/              # Event hooks
│   └── hooks.json
└── settings.json       # Permissions, MCP servers
```

| Directory | Purpose |
|-----------|---------|
| `commands/` | User-invocable slash commands (`/build`, `/test`) |
| `skills/` | Project-specific skills loaded on activation |
| `rules/` | Topic-specific convention files |
| `hooks/` | Event handlers for tool calls and lifecycle |

## Writing for Agent Consumption

When writing content that agents will parse:

### Structure for Machines

```markdown
## Good: Explicit structure

| Command | Description |
|---------|-------------|
| `bun test` | Run tests |
| `bun build` | Build project |

## Bad: Prose-heavy

To run tests, you can use the bun test command. For building,
there's bun build which will compile everything.
```

### Be Explicit About Types

```markdown
## Good: Type information clear

The `timeout` option accepts a `number` in milliseconds.
Default: `30000`. Range: `1000-300000`.

## Bad: Ambiguous

Set timeout to control how long operations wait.
```

### Document Error Conditions

```markdown
## Good: Errors are first-class

| Error | Cause | Resolution |
|-------|-------|------------|
| `CONFIG_NOT_FOUND` | Missing config file | Run `init` first |
| `INVALID_FORMAT` | Malformed input | Check input schema |

## Bad: Errors as afterthought

This might fail if config is missing.
```

### Avoid Ambiguous Pronouns

```markdown
## Good: Specific nouns

The `UserService` validates input. The service returns
a `Result<User, ValidationError>`.

## Bad: Ambiguous "it"

The service validates input. It returns a result if it succeeds.
```

### Tables Over Prose

Agents parse tables more reliably than paragraphs.

### Explicit Over Implicit

State conventions directly. Don't assume agents will infer them.

### Concision Over Grammar

Sacrifice grammar for concision. Agents parse tokens, not prose. "Use strict mode" beats "You should always make sure to use strict mode."

## Workflow

When this skill is activated, assess the current state and present options to the user using `AskUserQuestion`:

```
1. Scan for existing AGENTS.md, CLAUDE.md, .claude/ structure
2. Compare against recommended patterns
3. Present options via AskUserQuestion tool:
   - Audit: Review current docs against patterns
   - Restructure: Reorganize to match recommended structure
   - Enhance: Keep structure, improve content
   - Create: Build missing components from scratch
4. Execute chosen action
5. Validate result against guidelines
```

**Always use AskUserQuestion** when the user needs to choose between approaches. Don't list options in prose — use the tool for interactive decisions.

## Guidelines

When creating or reviewing agent-facing documentation:

- **ALWAYS** create AGENTS.md with tool-agnostic guidelines at project root
- **ALWAYS** use @-mentions in root CLAUDE.md to reference other files
- **ALWAYS** keep .claude/CLAUDE.md focused on Claude-specific content only
- **ALWAYS** structure content for quick scanning — tables over prose
- **ALWAYS** state conventions explicitly — agents don't infer
- **NEVER** use symlinks between CLAUDE.md and AGENTS.md
- **NEVER** put critical conventions only in .claude/rules/ — Codex won't see them
- **NEVER** duplicate content across files — link instead

## References

- [MIGRATION.md](references/MIGRATION.md) — Migrate existing setups to the recommended pattern


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/MIGRATION.md

```markdown
# Migration Guide

Migrate existing agent documentation setups to the recommended AGENTS.md + @-mention pattern.

## Before You Start

Check your current setup:

```bash
# What agent docs exist?
ls -la CLAUDE.md AGENTS.md .claude/CLAUDE.md 2>/dev/null

# Are there symlinks?
file CLAUDE.md AGENTS.md 2>/dev/null | grep -i symbolic
```

## Migration Paths

### From: Single CLAUDE.md (No AGENTS.md)

**Current state**: One CLAUDE.md with all agent instructions.

**Steps**:

1. **Rename CLAUDE.md to AGENTS.md**
   ```bash
   mv CLAUDE.md AGENTS.md
   ```

2. **Remove tool-specific content from AGENTS.md**

   Move Claude-specific sections (task management, tool preferences) to `.claude/CLAUDE.md`:
   ```bash
   mkdir -p .claude
   # Extract Claude-specific content to .claude/CLAUDE.md
   ```

3. **Create minimal CLAUDE.md**
   ```bash
   cat > CLAUDE.md << 'EOF'
   # CLAUDE.md

   This file provides AI agents with project-specific context and conventions.

   @.claude/CLAUDE.md
   @AGENTS.md
   EOF
   ```

4. **Verify**
   ```bash
   # AGENTS.md should have no Claude-specific content
   grep -i "task\|TaskCreate\|TaskUpdate" AGENTS.md  # Should return nothing
   ```

### From: Symlinked CLAUDE.md → AGENTS.md

**Current state**: CLAUDE.md is a symlink to AGENTS.md (or vice versa).

**Steps**:

1. **Remove the symlink**
   ```bash
   # Check which is the symlink
   file CLAUDE.md AGENTS.md

   # Remove the symlink (keep the real file)
   rm CLAUDE.md  # if CLAUDE.md is the symlink
   ```

2. **Extract tool-specific content**

   Review AGENTS.md for Claude-specific content and move to `.claude/CLAUDE.md`.

3. **Create minimal CLAUDE.md**
   ```bash
   cat > CLAUDE.md << 'EOF'
   # CLAUDE.md

   This file provides AI agents with project-specific context and conventions.

   @.claude/CLAUDE.md
   @AGENTS.md
   EOF
   ```

### From: CLAUDE.md + AGENTS.md (No @-mentions)

**Current state**: Both files exist but aren't connected.

**Steps**:

1. **Audit for duplication**

   Check if content is duplicated between files:
   ```bash
   # Quick diff to spot similarities
   diff CLAUDE.md AGENTS.md
   ```

2. **Consolidate tool-agnostic content into AGENTS.md**

   Project structure, commands, architecture, code style, testing, git workflow → AGENTS.md

3. **Move Claude-specific content to .claude/CLAUDE.md**
   ```bash
   mkdir -p .claude
   # Move task management, tool preferences, etc.
   ```

4. **Replace root CLAUDE.md with @-mentions**
   ```bash
   cat > CLAUDE.md << 'EOF'
   # CLAUDE.md

   This file provides AI agents with project-specific context and conventions.

   @.claude/CLAUDE.md
   @AGENTS.md
   EOF
   ```

### From: .claude/CLAUDE.md Only (No Root Files)

**Current state**: Instructions only in `.claude/CLAUDE.md`.

**Steps**:

1. **Create AGENTS.md from tool-agnostic content**

   Extract project overview, commands, architecture, etc. to AGENTS.md.

2. **Keep Claude-specific content in .claude/CLAUDE.md**

3. **Create minimal root CLAUDE.md**
   ```bash
   cat > CLAUDE.md << 'EOF'
   # CLAUDE.md

   This file provides AI agents with project-specific context and conventions.

   @.claude/CLAUDE.md
   @AGENTS.md
   EOF
   ```

## Content Classification

Use this table to decide where content belongs:

| Content Type | Location |
|--------------|----------|
| Project overview | AGENTS.md |
| Directory structure | AGENTS.md |
| Available commands | AGENTS.md |
| Architecture patterns | AGENTS.md |
| Development principles (TDD, etc.) | AGENTS.md |
| Code style conventions | AGENTS.md |
| Testing approach | AGENTS.md |
| Git workflow | AGENTS.md |
| Task management (TaskCreate, etc.) | .claude/CLAUDE.md |
| Claude tool preferences | .claude/CLAUDE.md |
| MCP server usage | .claude/CLAUDE.md |
| Subagent coordination | .claude/CLAUDE.md |
| Language-specific rules (scoped) | .claude/rules/*.md |

## Post-Migration Verification

After migration, confirm:

- **No symlinks** — `file CLAUDE.md AGENTS.md` shows regular files
- **Root CLAUDE.md is minimal** — Just @-mentions, no content
- **AGENTS.md is tool-agnostic** — No Claude-specific instructions
- **.claude/CLAUDE.md exists** — Contains Claude-specific content
- **No duplication** — Each piece of content lives in one place
- **Both tools work** — Test with Claude Code and Codex (if applicable)

## Common Issues

### @-mention not working

Ensure the path is correct and the file exists:
```bash
# Check file exists at the path specified in @-mention
cat .claude/CLAUDE.md
cat AGENTS.md
```

### Content showing up twice

Check for duplication:
```bash
# Look for similar content across files
grep -r "## Commands" CLAUDE.md AGENTS.md .claude/CLAUDE.md
```

Remove duplicates — content should live in exactly one place.

### Codex not seeing conventions

Critical conventions must be in AGENTS.md. Codex doesn't read:
- `.claude/CLAUDE.md`
- `.claude/rules/*.md`

Move important rules to AGENTS.md if they need to work across tools.

```