Claude Agent Development

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

Agents vs Skills

Critical distinction:

Aspect Agents (This Skill) Skills

Purpose Specialized subagents with focused expertise Capability packages with instructions

Invocation Task tool (subagent_type parameter) Automatic (model-triggered by context)

Location agents/ directory skills/ directory

Structure Single .md file with frontmatter Directory with SKILL.md

• resources

See agent-vs-skill.md for details.

Quick Start

Using Templates

Copy a template from templates/ :

Template Use When

basic.md

Simple agents with focused expertise

advanced.md

Full-featured agents with all config options

Scaffolding

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

Workflow Overview

• Discovery - Define purpose, scope, and triggers

• Design - Choose archetype and configuration

• Implementation - Write frontmatter and instructions

• Validation - Verify against quality standards

Phase 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?

Phase 2: Design

Agent Archetypes

Type Purpose Typical Tools

Analyzer Examine without modifying Glob, Grep, Read, Skill, Task, TodoWrite

Implementer Build and modify code Full access (inherit)

Reviewer Provide feedback Glob, Grep, Read, Skill, Task, TodoWrite

Tester Create and manage tests Glob, Grep, Read, Write, Edit, Bash, ...

Researcher Find and synthesize info ..., WebSearch, WebFetch

Deployer Handle infrastructure ..., Bash(kubectl *), Bash(docker *)

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

Model When to Use

inherit

Recommended default - adapts to parent context

haiku

Fast exploration, simple tasks, low-latency

sonnet

Balanced cost/capability (default if omitted)

opus

Nuanced judgment, security/architecture review, irreversible decisions

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, TodoWrite

See tools.md for patterns.

Phase 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: [Phase Name]

• Action item
• Action item

Step 2: [Phase 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:

• Start with trigger conditions: "Use this agent when..."

• Include 3-5 trigger keywords: specific terms users would say

• Add 2-3 examples: showing user request -> assistant delegation

• 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.

Phase 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, TodoWrite

• Tools appropriate for agent's purpose

Common patterns:

Read-only

tools: Glob, Grep, Read, Skill, Task, TodoWrite

Read-only + git

tools: Glob, Grep, Read, Skill, Task, TodoWrite, Bash(git show:), Bash(git diff:)

Research

tools: Glob, Grep, Read, Skill, Task, TodoWrite, 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

Scope Location Priority Visibility

Project agents/

Highest Team via git

Personal ~/.claude/agents/

Medium You only

Plugin <plugin>/agents/

Lowest Plugin users

Project agents override personal agents with the same name.

Testing Agents

Manual Testing

• Create agent file in agents/

• In Claude Code: "Use the [agent-name] agent to [task]"

• Claude invokes via Task tool

• 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

Reference Content

agent-vs-skill.md Agents vs Skills distinction

frontmatter.md YAML schema and fields

tools.md Tool configuration patterns

task-tool.md Task tool integration

discovery.md How agents are found and loaded

agent-types.md Archetypes: analysis, implementation, etc.

patterns.md Best practices and multi-agent patterns

todowrite.md TodoWrite patterns for agents

advanced-features.md Resumable agents, CLI config

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