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