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