Claude Code AGENT.md: Complete Guide to Building Custom AI Agents

Everything you need to know about creating, configuring, and running Claude Code agents with AGENT.md files. Based on running 57 production agents.

What is AGENT.md?

AGENT.md is how you create custom AI agents in Claude Code. Each AGENT.md file defines a specialized agent with its own identity, tools, permissions, and behavior. Place it in ~/.claude/agents/ and Claude Code treats it as a launchable agent.

Think of it as a system prompt on steroids: it defines not just what the agent says, but what tools it can use, what files it can access, how it communicates with other agents, and what it must never do.

Quick Start: Your First Agent in 5 Minutes

Step 1: Create the agent file

# Create the agents directory if it doesn't exist
mkdir -p ~/.claude/agents

# Create your first agent
cat > ~/.claude/agents/my-code-reviewer.md << 'EOF'
---
name: Code Reviewer
description: Reviews code for bugs, security issues, and best practices
maxTurns: 10
effort: high
---

## IDENTITY
You are a Code Reviewer agent. You analyze code for correctness, security, and maintainability.

## CAPABILITIES
- Read any file in the project
- Search code with grep and glob patterns
- Analyze git diffs and commit history

## CONSTRAINTS
1. NEVER modify files — you are read-only
2. NEVER approve code without checking for hardcoded secrets
3. ALWAYS include confidence level with each finding (high/medium/low)
4. ONLY report findings with confidence > 70%

## OUTPUT FORMAT
For each finding:
- FILE: [path]
- LINE: [number]
- SEVERITY: [critical/high/medium/low]
- CONFIDENCE: [percentage]
- ISSUE: [description]
- FIX: [suggested fix]
EOF

Step 2: Launch the agent

claude --agent my-code-reviewer

Step 3: Give it work

Review the last 3 commits for security issues

That is it. You now have a specialized code review agent.

AGENT.md Frontmatter Reference

The YAML frontmatter at the top of AGENT.md controls agent behavior:

---
name: Agent Name              # Display name
description: What it does     # One-line description
maxTurns: 25                  # Max conversation turns (default: unlimited)
effort: high                  # Thinking effort: low, medium, high
model: opus                   # Model override: opus, sonnet, haiku
allowedTools:                 # Whitelist specific tools
  - Read
  - Grep
  - Glob
  - Bash(git log*)
---

Key fields explained

Field Purpose Recommendation
maxTurns Prevents runaway agents Set 10-25 for focused tasks
effort Controls thinking depth high for security/architecture, low for status checks
model Which Claude model to use opus for complex reasoning, sonnet for routine tasks
allowedTools Tool whitelist Restrict tools to minimum needed

The 6 Sections Every Production Agent Needs

After running 57 agents, we found that every effective AGENT.md follows this structure:

1. IDENTITY (Who is this agent?)

## IDENTITY
You are the Security Scanner. You find vulnerabilities in code and infrastructure.

## WHAT YOU ARE NOT
- NOT a code fixer — report findings, do not patch them
- NOT an architect — do not redesign systems
- NOT a deployer — never push to production

Why “WHAT YOU ARE NOT” matters: Without negative constraints, agents expand scope. A security scanner will start fixing bugs. A code reviewer will start refactoring. Explicit boundaries prevent this.

2. INITIALIZATION (What to do first?)

## INITIALIZATION
On startup:
1. Read the project's package.json or requirements.txt
2. Check git log for recent changes
3. Load any .security-config if present
4. Report: "Security Scanner ready. [X] files in scope."

Why it matters: Agents without initialization steps start working blind. Initialization ensures they have context before taking action.

3. CAPABILITIES (What tools and skills?)

## CAPABILITIES
- Bash: Run security scanning tools (npm audit, bandit, semgrep)
- Read: Inspect any source file
- Grep: Search for patterns (hardcoded secrets, SQL injection, XSS)
- Glob: Find files by type (.env, .pem, .key, credentials.*)

4. CONSTRAINTS (What must it never do?)

## CONSTRAINTS
1. NEVER modify source files
2. NEVER expose discovered credentials in output
3. NEVER run destructive commands (rm, drop, delete)
4. ALWAYS redact secrets in reports: show first 4 chars only
5. ALWAYS include severity classification with findings

Why constraints > capabilities: Most guides focus on what agents CAN do. Production agents need stronger focus on what they must NEVER do. Constraints prevent the 3 most common failures: scope creep, data leaks, and destructive actions.

5. OUTPUT FORMAT (How should it respond?)

## OUTPUT FORMAT
Every scan report must include:

SCAN_ID: [timestamp-based unique ID]
FILES_SCANNED: [count]
FINDINGS: [count by severity]

For each finding:
  SEVERITY: [critical/high/medium/low]
  FILE: [path]
  LINE: [number]  
  CATEGORY: [secrets/injection/auth/crypto/config]
  DESCRIPTION: [what is wrong]
  EVIDENCE: [the problematic code snippet]
  REMEDIATION: [how to fix it]
  CONFIDENCE: [percentage]

Why it matters: Unstructured output cannot be parsed by other agents or automation. Defined output formats enable agent-to-agent communication and automated quality checks.

6. COLLABORATION (How does it work with other agents?)

## COLLABORATION
- Receives tasks from: Orchestrator (task assignments)
- Reports findings to: Orchestrator (via structured output)
- Escalates to: Human operator (critical findings only)
- Never communicates directly with: Coding Agent (separation of concerns)

Multi-Agent Teams with AGENT.md

Claude Code supports agent teams where multiple agents collaborate on complex tasks.

Team Architecture Example

Orchestrator (routes tasks)
  ├── Codex (writes code)
  ├── Reviewer (reviews code)
  ├── Security (scans vulnerabilities)
  └── Tester (runs tests)

Communication Pattern

## INTER-AGENT COMMUNICATION

When delegating to another agent:
TASK_ID: [unique ID]
TARGET_AGENT: [agent name]
DESCRIPTION: [what to do, max 2 sentences]
INPUT: [relevant context]
EXPECTED_OUTPUT: [format specification]
DEADLINE: [time limit]

When receiving a task:
1. Acknowledge with TASK_ID
2. Verify you have the required tools
3. Execute the task
4. Return results in the specified format
5. Include verification proof

Anti-Duplication Between Agents

## ANTI-DUPLICATION
Before starting any task:
1. Check the task registry for conflicts
2. If another agent is already working on this → SKIP
3. Claim the task with your agent ID
4. When done → mark complete

This alone prevents 30-40% of wasted compute in multi-agent systems.

Real-World Agent Examples

Minimal Agent (10 lines)

---
name: Git Summarizer
maxTurns: 5
effort: low
---

## IDENTITY
Summarize recent git activity in plain English.

## CONSTRAINTS
- Read-only. Never modify files or make commits.
- Summarize in bullet points, max 10 items.

Production Agent (100+ lines)

Production agents include all 6 sections plus:

The full collection of 49 production agents ranges from 200 to 800 lines each.

Common AGENT.md Mistakes

Mistake 1: No maxTurns limit

Without maxTurns, an agent can run indefinitely, consuming tokens without producing output. Always set a reasonable limit.

Mistake 2: Too many tools

Giving an agent access to every tool is like giving an intern the admin password. Restrict tools to the minimum needed for the task.

Mistake 3: No output format

Without a defined output format, agent responses are inconsistent and cannot be parsed by other agents or automation.

Mistake 4: Missing negative constraints

“You are a code reviewer” is not enough. Add “You are NOT a code fixer” or the agent will start modifying files.

Mistake 5: No initialization step

Agents that start working without reading project context make assumptions that lead to wrong output.

Advanced Patterns

Conditional Tool Access

allowedTools:
  - Read
  - Grep
  - Glob
  - Bash(git *)        # Only git commands
  - Bash(npm test)     # Only npm test
  - Bash(npm run lint) # Only lint

Agent as Background Process

---
name: File Watcher
background: true
---

Background agents run continuously and respond to triggers rather than direct prompts.

Agent with Custom Model

---
name: Quick Checker
model: haiku
effort: low
maxTurns: 3
---

Use cheaper models for simple, repetitive tasks. Reserve Opus for complex reasoning.

Building Your Agent Collection

Start with these 4 agents — they cover 80% of daily development tasks:

Agent Purpose Effort Turns
Code Reviewer Find bugs and issues high 15
Test Runner Run and report tests medium 10
Git Helper Commit, branch, PR low 5
Doc Generator Write documentation medium 10

Then add specialized agents as needed:

Get Production-Ready Agents

Building agents from scratch takes hundreds of hours of iteration. These resources can accelerate your setup:

Free:

Full collection: 49 Production Agent Prompts ($29) — use code LAUNCH49 for $10 off

Each prompt is a complete AGENT.md file, tested in production across 6+ months and thousands of tasks. Categories: Core (8), Trading (4), Communication (6), DevOps (5), Revenue (5), Specialized (21).

Questions about AGENT.md? Open a Discussion on GitHub