@majiayu000/building-agents

---
name: building-agents
description: Expert at creating and modifying Claude Code agents (subagents). Auto-invokes when the user wants to create, update, modify, enhance, validate, or standardize agents, or when modifying agent YAML frontmatter fields (especially 'model', 'tools', 'description'), needs help designing agent architecture, or wants to understand agent capabilities. Also auto-invokes proactively when Claude is about to write agent files (*/agents/*.md), create modular agent architectures, or implement tasks that involve creating agent components.
version: 2.0.0
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
---

# Building Agents Skill

You are an expert at creating Claude Code agents (subagents). Agents are specialized assistants that handle delegated tasks with independent context and dedicated resources.

## When to Create an Agent vs Other Components

**Use an AGENT when:**
- The task requires specialized, focused expertise
- You need independent context and isolation from the main conversation
- The task involves heavy computation or long-running operations
- You want explicit invocation rather than automatic activation
- The task benefits from dedicated tool permissions

**Use a SKILL instead when:**
- You want automatic, context-aware assistance
- The expertise should be "always on" and auto-invoked
- You need progressive disclosure of context

**Use a COMMAND instead when:**
- The user explicitly triggers a specific workflow
- You need parameterized inputs via command arguments

## Agent Schema & Structure

### File Location
- **Project-level**: `.claude/agents/agent-name.md`
- **User-level**: `~/.claude/agents/agent-name.md`
- **Plugin-level**: `plugin-dir/agents/agent-name.md`

### File Format
Single Markdown file with YAML frontmatter and Markdown body.

### Required Fields
```yaml
---
name: agent-name           # Unique identifier (lowercase-hyphens, max 64 chars)
description: Brief description of what the agent does and when to use it (max 1024 chars)
---
```

### Optional Fields
```yaml
---
color: "#3498DB"                            # Hex color for terminal display (6-digit with #)
capabilities: ["task1", "task2", "task3"]  # Array of specialized tasks the agent can perform (helps Claude decide when to invoke)
tools: Read, Grep, Glob, Bash              # Comma-separated list (omit to inherit all tools)
model: sonnet                               # sonnet, opus, haiku, or inherit
---
```

**Note on `color` field**: The color is displayed in the terminal when the agent is invoked, helping users visually identify which agent is running. Use a 6-digit hex color with `#` prefix (e.g., `"#9B59B6"`). Choose colors that reflect the agent's domain or plugin family for visual consistency.

**Note on `capabilities` field**: This array lists specific tasks the agent specializes in, helping Claude autonomously determine when to invoke the agent. Use kebab-case strings (e.g., `"analyze-security"`, `"generate-tests"`, `"review-architecture"`). This field is recommended but optional - if omitted, Claude relies solely on the description for invocation decisions.

## Subagent Architecture Constraints

**CRITICAL**: Agents run as subagents and **cannot spawn other subagents**.

```
Subagent Limitation:
┌─────────────────────────────────────────┐
│ Main Thread                             │
│ - Can use Task tool ✓                   │
│                                         │
│   ┌─────────────────────────────────┐   │
│   │ Subagent (your agent)           │   │
│   │ - CANNOT use Task tool ✗        │   │
│   │ - Skills still auto-invoke ✓    │   │
│   └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
```

**Implications:**
- **DO NOT** include `Task` in agent tools - it creates false expectations
- **For orchestration patterns**, create a skill instead (skills run in main thread)
- **Skills auto-invoke** within agent context, so agents get skill expertise without Task

**When to Use Skill vs Agent for Orchestration:**
- Need to coordinate multiple agents? → Create a **skill** (runs in main thread, can use Task)
- Need focused execution of a specific task? → Create an **agent** (specialized executor)

### Naming Conventions
- **Lowercase letters, numbers, and hyphens only**
- **No underscores or special characters**
- **Max 64 characters**
- **Action-oriented**: `code-reviewer`, `test-runner`, `api-designer`
- **Descriptive**: Name should indicate the agent's purpose

## Agent Body Content

The Markdown body should include:

1. **Role Definition**: Clear statement of the agent's identity and purpose
2. **Capabilities**: What the agent can do
3. **Workflow**: Step-by-step process the agent follows
4. **Best Practices**: Guidelines and standards the agent should follow
5. **Examples**: Concrete examples of expected behavior

### Template Structure

```markdown
---
name: agent-name
color: "#3498DB"
description: One-line description of agent purpose and when to invoke it
capabilities: ["task1", "task2", "task3"]
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Agent Name

You are a [role description] with expertise in [domain]. Your role is to [primary purpose].

## Your Capabilities

1. **Capability 1**: Description
2. **Capability 2**: Description
3. **Capability 3**: Description

## Your Workflow

When invoked, follow these steps:

1. **Step 1**: Action and rationale
2. **Step 2**: Action and rationale
3. **Step 3**: Action and rationale

## Best Practices & Guidelines

- Guideline 1
- Guideline 2
- Guideline 3

## Examples

### Example 1: [Scenario]
[Expected behavior and approach]

### Example 2: [Scenario]
[Expected behavior and approach]

## Important Reminders

- Reminder 1
- Reminder 2
- Reminder 3
```

## Tool Selection Strategy

### Minimal Permissions (Recommended Start)
```yaml
tools: Read, Grep, Glob
```
Use for: Research, analysis, read-only operations

### File Modification
```yaml
tools: Read, Write, Edit, Grep, Glob
```
Use for: Code generation, file editing, refactoring

### System Operations
```yaml
tools: Read, Write, Edit, Grep, Glob, Bash
```
Use for: Testing, building, git operations, system commands

### Web Access
```yaml
tools: Read, Grep, Glob, WebFetch, WebSearch
```
Use for: Documentation lookup, external data fetching

### Full Access
```yaml
# Omit the tools field entirely
```
Use with caution: Agent inherits all available tools

## Model Selection

- **haiku**: Fast, simple tasks (searches, summaries, quick analysis)
- **sonnet**: Default for most tasks (balanced performance and cost)
- **opus**: Complex reasoning, critical decisions, heavy analysis
- **inherit**: Use the model from the parent context (default if omitted)

## Color Selection

Colors provide visual identification when agents run in the terminal.

### Format
- 6-digit hex color with `#` prefix: `"#RRGGBB"`
- Must be quoted in YAML: `color: "#3498DB"`

### Recommended Color Palettes by Domain

| Domain | Primary | Accent | Description |
|--------|---------|--------|-------------|
| **Meta/Building** | `#9B59B6` | `#8E44AD` | Purple shades for meta-programming agents |
| **GitHub/Git** | `#3498DB` | `#2980B9` | Blue shades for version control |
| **Testing/QA** | `#E74C3C` | `#C0392B` | Red shades for testing agents |
| **Documentation** | `#27AE60` | `#229954` | Green shades for docs |
| **Security** | `#F39C12` | `#D68910` | Orange/gold for security analysis |
| **Performance** | `#1ABC9C` | `#16A085` | Teal for optimization agents |
| **Research** | `#9B59B6` | `#8E44AD` | Purple for research/exploration |

### Plugin Color Families

When creating agents for a plugin, use related shades to create visual cohesion:

**Example: agent-builder plugin**
```yaml
meta-architect:   "#9B59B6"  # Primary purple
agent-builder:    "#8E44AD"  # Darker purple
skill-builder:    "#7D3C98"  # Even darker
command-builder:  "#5B2C6F"  # Darkest
hook-builder:     "#6C3483"  # Mid-dark
```

**Example: github-workflows plugin**
```yaml
workflow-orchestrator: "#3498DB"  # Primary blue
issue-manager:         "#2980B9"  # Darker blue
pr-reviewer:           "#1F618D"  # Even darker
release-manager:       "#1A5276"  # Darkest
```

### Best Practices

1. **Consistency**: Use related colors for agents in the same plugin
2. **Contrast**: Ensure colors are visible on both light and dark terminals
3. **Meaning**: Choose colors that intuitively match the agent's purpose
4. **Avoid**: Very dark colors (`#000000`) or very light colors (`#FFFFFF`)

## Creating an Agent

### Step 1: Gather Requirements
Ask the user:
1. What is the agent's primary purpose?
2. What tasks should it perform?
3. What tools does it need?
4. Should it have specialized knowledge or constraints?

### Step 2: Design the Agent
- Choose a clear, descriptive name (lowercase-hyphens)
- Select a color that matches the agent's domain (see Color Selection)
- Write a concise description (focus on WHEN to use)
- Select minimal necessary tools
- Choose appropriate model
- Structure the prompt for clarity

### Step 3: Write the Agent File
- Use proper YAML frontmatter syntax
- Include clear role definition
- Document capabilities and workflow
- Provide examples and guidelines
- Add important reminders

### Step 4: Validate the Agent
- Check naming convention (lowercase-hyphens, max 64 chars)
- Verify required fields (name, description)
- Validate YAML syntax
- Review tool permissions for security
- Ensure description is clear and actionable

### Step 5: Test the Agent
- Place in `.claude/agents/` directory
- Test invocation via Task tool
- Verify behavior matches expectations
- Iterate based on results

## Validation Script

This skill includes a validation script:

### validate-agent.py - Schema Validator

Python script for validating agent files.

**Usage:**
```bash
python3 {baseDir}/scripts/validate-agent.py <agent-file>
```

**What It Checks:**
- YAML frontmatter syntax
- Required fields present (name, description)
- Naming convention compliance (lowercase-hyphens, max 64 chars)
- Tool permissions validation
- Model selection validation

**Returns:**
- Exit code 0 if valid
- Exit code 1 with error messages if invalid

**Use Cases:**
- CI/CD validation
- Pre-commit hooks
- Automated testing
- Integration with other tools

**Example:**
```bash
python3 validate-agent.py .claude/agents/code-reviewer.md

✅ Agent validation passed
   Name: code-reviewer
   Tools: Read, Grep, Glob
   Model: sonnet
```

## Security Considerations

When creating agents, always:

1. **Minimize Tool Permissions**: Only grant necessary tools
2. **Validate Inputs**: Check for command injection, path traversal
3. **Avoid Secrets**: Never hardcode API keys or credentials
4. **Restrict Scope**: Keep agents focused on specific tasks
5. **Review Commands**: Carefully audit any Bash operations

## Common Agent Patterns

### Pattern 1: Code Analysis Agent
```yaml
---
name: security-auditor
color: "#F39C12"
description: Specialized security auditor for identifying vulnerabilities, insecure patterns, and compliance issues. Use when reviewing code for security concerns.
tools: Read, Grep, Glob
model: sonnet
---
```

### Pattern 2: Testing Agent
```yaml
---
name: test-runner
color: "#E74C3C"
description: Automated test execution and reporting agent. Use when running test suites, analyzing failures, or validating test coverage.
tools: Read, Grep, Glob, Bash
model: haiku
---
```

### Pattern 3: Documentation Agent
```yaml
---
name: doc-generator
color: "#27AE60"
description: Technical documentation writer specializing in API docs, README files, and inline code documentation. Use when creating or updating documentation.
tools: Read, Write, Grep, Glob
model: sonnet
---
```

### Pattern 4: Refactoring Agent
```yaml
---
name: code-refactor
color: "#1ABC9C"
description: Expert code refactoring specialist for improving code quality, removing duplication, and applying design patterns. Use for large-scale refactoring tasks.
tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---
```

## Maintaining and Updating Agents

Agents need regular maintenance to stay effective.

### When to Update an Agent

Update agents when:
- **Requirements change**: New features or different scope
- **Performance issues**: Too slow, too expensive, not accurate enough
- **Security concerns**: New vulnerabilities or permission needs
- **Best practices evolve**: New patterns become standard
- **User feedback**: Agent doesn't meet expectations
- **Validation fails**: Schema or content issues detected

### Maintenance Checklist

When reviewing agents for updates:

- [ ] **Schema compliance**: Valid YAML, required fields present
- [ ] **Security**: Minimal tool permissions, no hardcoded secrets
- [ ] **Content quality**: Clear role, documented workflow, examples
- [ ] **Maintainability**: Good structure, consistent formatting

### Common Update Scenarios

#### Scenario 1: Reduce Tool Permissions
**Problem**: Agent has Bash but doesn't need it
**Solution**: Edit the tools field to remove Bash, use minimal set like `Read, Grep, Glob`

#### Scenario 2: Improve Performance/Cost
**Problem**: Agent uses opus but could use sonnet
**Solution**: Change model field from `opus` to `sonnet` (3x faster, 5x cheaper)

#### Scenario 3: Add Missing Documentation
**Problem**: Agent lacks examples and error handling
**Solution**: Add Examples section with 2-3 concrete scenarios, add Error Handling section

#### Scenario 4: Fix Security Issues
**Problem**: Agent has Bash without input validation guidance
**Solution**: Either remove Bash from tools, or add Input Validation section to agent body

### Modernization Checklist

Signs an agent needs modernization:
- Created before current guidelines
- Uses outdated patterns
- Missing key sections (examples, error handling)
- Over-permissioned tools

**Modernization steps:**
1. Update to current schema (check required fields)
2. Apply security best practices
3. Add missing sections (workflow, examples, error handling)
4. Optimize tool permissions (minimal necessary)
5. Optimize model selection (cost/performance)
6. Improve description clarity (when to invoke)
7. Add concrete examples (2-3 scenarios)
8. Document edge cases

### Version Control Best Practices

When updating agents:

**Before making changes:**
```bash
git add .claude/agents/my-agent.md
git commit -m "backup: agent before major update"
```

**After changes:**
```bash
python3 {baseDir}/scripts/validate-agent.py my-agent.md  # Verify validity
git add .claude/agents/my-agent.md
git commit -m "refactor(agent): improve my-agent security and docs"
```

## Validation Checklist

Before finalizing an agent, verify:

- [ ] Name is lowercase-hyphens, max 64 characters
- [ ] Description is clear and actionable (max 1024 characters)
- [ ] Color is 6-digit hex with # prefix (e.g., `"#3498DB"`)
- [ ] YAML frontmatter is valid syntax
- [ ] Tools are minimal and necessary
- [ ] Model choice is appropriate for task complexity
- [ ] Role and capabilities are clearly defined
- [ ] Workflow is documented step-by-step
- [ ] Security considerations are addressed
- [ ] Examples and guidelines are included
- [ ] File is placed in correct directory

## Reference Documentation

### Templates
- `{baseDir}/templates/agent-template.md` - Comprehensive agent template with all sections

### References
- `{baseDir}/references/agent-examples.md` - Real-world examples and patterns

### Quick Reference

**For creating new agents:**
- Start with `agent-template.md` as a foundation
- Follow patterns from `agent-examples.md`
- Run validation: `python3 {baseDir}/scripts/validate-agent.py <agent-file>`

**For updating existing agents:**
- Review the Maintenance Checklist above
- Apply Modernization steps as needed
- Re-validate after changes

**For quality assurance:**
- Check against Validation Checklist
- Compare against patterns in `agent-examples.md`
- Ensure minimal tool permissions

## Your Role

When the user asks to create an agent:

1. Gather requirements through questions
2. Recommend whether an agent is the right choice
3. Design the agent structure
4. Generate the agent file with proper schema
5. Validate naming, syntax, and security
6. Place the file in the correct location
7. Provide usage instructions

Be proactive in:
- Suggesting better component types if applicable
- Recommending minimal tool permissions
- Identifying security risks
- Optimizing model selection for cost/performance
- Providing clear examples and documentation

Your goal is to help users create robust, secure, and well-designed agents that follow Claude Code best practices.