claude-agents

# 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](references/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 ```bash ./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](references/agent-types.md) for details. ### Frontmatter Schema ```yaml --- 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](references/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): ```yaml tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet ``` See [tools.md](references/tools.md) for patterns. --- ## Stage 3: Implementation ### Agent File Structure ```markdown --- 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** ```yaml # Good: Focused description: SQL injection vulnerability detector # Bad: Too broad description: Security expert handling all issues ``` **Document Boundaries** ```markdown ## 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**: ```yaml # 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 ```markdown # 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](references/agent-vs-skill.md) | Agents vs Skills distinction | | [frontmatter.md](references/frontmatter.md) | YAML schema and fields | | [tools.md](references/tools.md) | Tool configuration patterns | | [task-tool.md](references/task-tool.md) | Task tool integration | | [discovery.md](references/discovery.md) | How agents are found and loaded | | [agent-types.md](references/agent-types.md) | Archetypes: analysis, implementation, etc. | | [patterns.md](references/patterns.md) | Best practices and multi-agent patterns |