claude-agents

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

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

| Type | Purpose | Typical Tools | |------|---------|---------------| | Analyzer | Examine without modifying | Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet | | Implementer | Build and modify code | Full access (inherit) | | Reviewer | Provide feedback | Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet | | 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, 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

| 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

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

| 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 | | tasks.md | Task tool 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