claude-agents

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: claude-agents
description: This skill should be used when creating agents, writing agent frontmatter, configuring subagents, or when "create agent", "agent.md", "subagent", or "Task tool" are mentioned.
metadata:
  version: "1.0.0"
  related-skills:
    - skills-dev
    - claude-plugins
    - claude-hooks
---

# 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 ex