Claude Agent Development

Create and validate specialized subagents that extend Claude Code with focused expertise.

Agents vs Skills

Critical distinction:

See agent-vs-skill.md for details.

Quick Start

Using Templates

Copy a template from templates/:

Scaffolding

./scripts/scaffold-agent.sh security-reviewer -t reviewer

Workflow Overview

1. Discovery - Define purpose, scope, and triggers
2. Design - Choose archetype and configuration
3. Implementation - Write frontmatter and instructions
4. Validation - Verify against quality standards

Stage 1: Discovery

Before writing code, clarify:

• Purpose: What specialized expertise does this agent provide?
• Triggers: What keywords/phrases should invoke it?
• Scope: What does it do? What does it NOT do?
• Location: Personal (~/.claude/agents/), project (agents/), or plugin?

Key questions:

• Is this a specialized role or a general capability? (Role = agent, Capability = skill)
• What user phrases should trigger this agent?
• What tools does it need access to?

Stage 2: Design

Agent Archetypes

See agent-types.md for details.

Frontmatter Schema

---
name: agent-name           # Required: kebab-case, matches filename
description: |             # Required: when to use + triggers + examples
  Use this agent when [conditions]. Triggers on [keywords].

  <example>
  Context: [Situation]
  user: "[User message]"
  assistant: "I'll use the agent-name agent to [action]."
  </example>
model: inherit             # Optional: inherit|haiku|sonnet|opus
tools: Glob, Grep, Read    # Optional: restrict tools (default: inherit all)
skills: tdd, debugging     # Optional: skills to auto-load (NOT inherited)
permissionMode: default    # Optional: default|acceptEdits|bypassPermissions
---

See frontmatter.md for complete schema.

Model Selection

Tool Configuration

Philosophy: Don't over-restrict. Only limit tools when there's a specific safety reason.

Baseline (always include when restricting):

tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet

See tools.md for patterns.

Stage 3: Implementation

Agent File Structure

---
name: security-reviewer
description: |
  Use this agent for security vulnerability detection.
  Triggers on security audits, OWASP, injection, XSS.

  <example>
  Context: User wants security review.
  user: "Review auth code for vulnerabilities"
  assistant: "I'll use the security-reviewer agent."
  </example>
model: inherit
---

# Security Reviewer

You are a security expert specializing in [expertise].

## Expertise

- Domain expertise 1
- Domain expertise 2

## Process

### Step 1: [Stage Name]
- Action item
- Action item

### Step 2: [Stage Name]
- Action item

## Output Format

For each finding:
- **Severity**: critical|high|medium|low
- **Location**: file:line
- **Issue**: Description
- **Remediation**: How to fix

## Constraints

**Always:**
- Required behavior

**Never:**
- Prohibited action

Description Guidelines

Descriptions are the most critical field for agent discovery:

1. Start with trigger conditions: "Use this agent when..."
2. Include 3-5 trigger keywords: specific terms users would say
3. Add 2-3 examples: showing user request -> assistant delegation
4. Be specific: avoid vague descriptions like "helps with code"

Best Practices

Single Responsibility

# Good: Focused
description: SQL injection vulnerability detector

# Bad: Too broad
description: Security expert handling all issues

Document Boundaries

## What I Don't Do
- I analyze, not implement fixes
- I review, not build from scratch

Consistent Output Format

Define structured output so results are predictable and parseable.

Stage 4: Validation

After creating an agent, validate against these checklists.

YAML Frontmatter Checks

• Opens with --- on line 1
• Closes with --- before content
• name present and matches filename (without .md)
• description present and non-empty
• Uses spaces (not tabs) for indentation
• tools uses comma-separated valid tool names
• model is valid: sonnet, opus, haiku, or inherit

Naming Conventions

• Kebab-case (lowercase-with-hyphens)
• Follows [role]-[specialty] or [specialty] pattern
• Specific, not generic
• Concise (1-3 words, max 4)

Good: code-reviewer, test-runner, security-auditor Bad: helper, my-agent, the-best-agent

Description Quality

• WHAT: Explains what the agent does
• WHEN: States when to invoke it
• TRIGGERS: Includes 3-5 trigger keywords
• EXAMPLES: Has 2-3 example conversations
• Specific about agent's purpose (not vague)
• Clear about scope

Anti-patterns:

• "Helps with code" - too vague
• No trigger conditions
• Missing keywords

System Prompt Quality

• Clear role definition
• Step-by-step process
• Key practices or guidelines
• Output format specification
• Specific and actionable instructions
• Constraints (what NOT to do)
• Single responsibility focus

Anti-patterns:

• "You are helpful" - too vague
• No process defined
• Missing constraints
• Scope creep

Tool Configuration

• Field name is tools: (not allowed-tools:)
• Comma-separated list
• Tool names correctly spelled and case-sensitive
• Includes baseline tools if restricting: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet
• Tools appropriate for agent's purpose

Common patterns:

# Read-only
tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet

# Read-only + git
tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet, Bash(git show:*), Bash(git diff:*)

# Research
tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet, WebSearch, WebFetch

# Full access
# (omit field to inherit all)

Validation Report Format

# Agent Validation Report: [Agent Name]

## Summary
- **Status**: PASS | FAIL | WARNINGS
- **Location**: [path]
- **Issues**: [count critical] / [count warnings]

## Critical Issues (must fix)
1. [Issue with specific fix]

## Warnings (should fix)
1. [Issue with specific fix]

## Strengths
- [What's done well]

Agent Scopes

Project agents override personal agents with the same name.

Testing Agents

Manual Testing

1. Create agent file in agents/
2. In Claude Code: "Use the [agent-name] agent to [task]"
3. Claude invokes via Task tool
4. Review results

Verify Discovery

Agents are loaded from:

• ~/.claude/agents/ (personal)
• ./agents/ (project)
• Plugins (installed)

Debug with: claude --debug

Troubleshooting

Agent Not Being Invoked

• Check file location: agents/agent-name.md
• Validate YAML frontmatter syntax
• Make description more specific with trigger keywords
• Add example conversations

Wrong Agent Invoked

• Make description more distinct
• Add specific trigger keywords
• Include negative examples (what NOT to use it for)

Agent Has Wrong Tools

Prefer model: inherit to use parent's tool access. Only specify tools: when agent needs different access.

References

See EXAMPLES.md for complete real-world agent examples. See templates/ for starter templates.

Related Skills

• skills-development: Create Skills (different from agents)
• claude-plugin-development: Bundle agents into plugins