agent-docs

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

# 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

# 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

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

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

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

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

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

## 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 — Migrate existing setups to the recommended pattern