Stats
Actions
Tags
From team
Documentation patterns for AI agents — AGENTS.md, CLAUDE.md, and agent-readable content. Use when creating agent entry points or structuring .claude/ directories.
How this skill is triggered — by the user, by Claude, or both
Slash command
/team:outfitter-agents-setupThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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 outfitter-documentation skill.
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
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.
See templates/AGENTS.md for the full template.
| 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 |
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.
See templates/CLAUDE-ROOT.md for the template. Keep the root CLAUDE.md minimal.
Previously, some projects used symlinks between CLAUDE.md and AGENTS.md. Don't do this.
Problems with symlinks:
The @-mention pattern is explicit, portable, and clear about which file is authoritative.
Claude-specific instructions that don't apply to other tools.
Location: .claude/CLAUDE.md
Purpose: Claude Code features, task management, tool-specific guidance.
See templates/CLAUDE-DOTCLAUDE.md for an example.
| 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 |
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.
Use .claude/rules/ for:
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 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.
.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 |
When writing content that agents will parse:
## 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.
## 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.
## 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.
## 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.
Agents parse tables more reliably than paragraphs.
State conventions directly. Don't assume agents will infer them.
Sacrifice grammar for concision. Agents parse tokens, not prose. "Use strict mode" beats "You should always make sure to use strict mode."
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.
When creating or reviewing agent-facing documentation:
npx claudepluginhub outfitter-dev/outfitter --plugin teamAdvises on creating, reviewing, and optimizing AI coding agent instruction files (AGENTS.md, CLAUDE.md). Includes best practices, diagnostics, and file generation.
Creates and maintains concise AGENTS.md / CLAUDE.md files for projects. Analyzes toolchain, linters, and conventions to produce minimal agent-facing documentation under 100 lines.
Initializes or migrates a project to nested CLAUDE.md files for progressive disclosure. Splits bloated root config into topic-specific docs/agents/ files.