194 lines
5.2 KiB
Markdown
194 lines
5.2 KiB
Markdown
---
|
|
name: agent-builder
|
|
description: Create custom Claude Code sub-agents with specialized expertise and tool access. Use when you need to build reusable agents for specific tasks like code review, debugging, data analysis, or domain-specific workflows.
|
|
version: 1.0.0
|
|
---
|
|
|
|
# Build Custom Claude Code Sub-Agents
|
|
|
|
## When to Use
|
|
|
|
- Creating a specialized agent for recurring tasks (code review, debugging, testing)
|
|
- Need an agent with specific tool permissions or limited scope
|
|
- Want to share reusable agents across projects or with your team
|
|
- Building domain-specific agents (data science, DevOps, security)
|
|
- Need to preserve main conversation context while delegating complex tasks
|
|
|
|
## What This Skill Does
|
|
|
|
Guides you through creating custom sub-agents that:
|
|
|
|
- **Specialize**: Focused expertise for specific domains or tasks
|
|
- **Isolate**: Separate context windows prevent main conversation pollution
|
|
- **Reuse**: Deploy across projects and share with teams
|
|
- **Control**: Granular tool access and model selection per agent
|
|
|
|
## Quick Start
|
|
|
|
### 1. Use the Built-In Agent Creator
|
|
|
|
```bash
|
|
# Run the agents command
|
|
/agents
|
|
```
|
|
|
|
Then:
|
|
1. Select "Create New Agent"
|
|
2. Choose project-level (`.claude/agents/`) or user-level (`~/.claude/agents/`)
|
|
3. Generate with Claude or manually define configuration
|
|
4. Save and test
|
|
|
|
### 2. Manual Agent Creation
|
|
|
|
Create a markdown file in `.claude/agents/` (project) or `~/.claude/agents/` (user):
|
|
|
|
```markdown
|
|
---
|
|
name: my-agent-name
|
|
description: Use this agent when [specific trigger condition]
|
|
tools: Read, Edit, Bash
|
|
model: sonnet
|
|
---
|
|
|
|
# Agent System Prompt
|
|
|
|
Your detailed instructions for the agent go here.
|
|
|
|
Be specific about:
|
|
- What tasks this agent handles
|
|
- How to approach problems
|
|
- What outputs to produce
|
|
- Any constraints or guardrails
|
|
```
|
|
|
|
### 3. Invoke Your Agent
|
|
|
|
**Automatic**: Claude detects matching tasks based on description
|
|
**Explicit**: "Use the my-agent-name agent to [task]"
|
|
|
|
## Agent Configuration
|
|
|
|
### Required Fields
|
|
|
|
| Field | Description | Example |
|
|
|-------|-------------|---------|
|
|
| `name` | Lowercase with hyphens | `code-reviewer` |
|
|
| `description` | When to use this agent (triggers routing) | `Use PROACTIVELY to review code changes for quality and security` |
|
|
|
|
### Optional Fields
|
|
|
|
| Field | Description | Default |
|
|
|-------|-------------|---------|
|
|
| `tools` | Comma-separated tool list | All tools inherited |
|
|
| `model` | Model alias (sonnet/opus/haiku) or 'inherit' | Inherits from main |
|
|
|
|
**See**: [Configuration Reference](./reference/configuration-guide.md)
|
|
|
|
## Agent Structure
|
|
|
|
```
|
|
.claude/agents/ # Project-level agents
|
|
├── code-reviewer.md
|
|
├── debugger.md
|
|
└── custom-agent.md
|
|
|
|
~/.claude/agents/ # User-level agents (global)
|
|
├── my-helper.md
|
|
└── data-analyzer.md
|
|
```
|
|
|
|
**Priority**: Project agents override user agents with same name
|
|
|
|
## Common Agent Types
|
|
|
|
### Code Reviewer
|
|
Reviews code for quality, security, and best practices
|
|
|
|
**Triggers**: After code changes, before commits
|
|
|
|
### Debugger
|
|
Analyzes errors, identifies root causes, proposes fixes
|
|
|
|
**Triggers**: Test failures, runtime errors
|
|
|
|
### Data Scientist
|
|
Writes SQL queries, performs analysis, generates reports
|
|
|
|
**Triggers**: Data questions, BigQuery tasks
|
|
|
|
**See**: [Agent Examples](./reference/agent-examples.md)
|
|
|
|
## Best Practices
|
|
|
|
1. **Single Responsibility**: One focused task per agent
|
|
2. **Descriptive Triggers**: Use "PROACTIVELY" or "MUST BE USED" for automatic delegation
|
|
3. **Detailed Prompts**: Specific instructions yield better results
|
|
4. **Limit Tools**: Only grant necessary permissions
|
|
5. **Version Control**: Commit project agents for team collaboration
|
|
|
|
**Full Guide**: [Best Practices](./reference/best-practices.md)
|
|
|
|
## Available Tools
|
|
|
|
Sub-agents can access:
|
|
- **File Operations**: Read, Write, Edit, Glob, Grep
|
|
- **Execution**: Bash
|
|
- **MCP Tools**: Any installed MCP server tools
|
|
|
|
Use `/agents` interface to visually select tools.
|
|
|
|
## Outputs
|
|
|
|
This skill helps you create:
|
|
- Agent configuration files (`.md` with YAML frontmatter)
|
|
- Specialized system prompts
|
|
- Tool permission configurations
|
|
- Reusable agent templates
|
|
|
|
## Guardrails
|
|
|
|
- Agents must have focused, well-defined purposes
|
|
- Use lowercase-with-hyphens naming convention
|
|
- Always specify clear trigger conditions in description
|
|
- Grant minimal tool access (principle of least privilege)
|
|
- Test agents thoroughly before sharing with team
|
|
|
|
## Advanced Topics
|
|
|
|
- [Configuration Guide](./reference/configuration-guide.md) - Complete field reference
|
|
- [Agent Examples](./reference/agent-examples.md) - Real-world templates
|
|
- [Best Practices](./reference/best-practices.md) - Design patterns
|
|
- [Troubleshooting](./reference/troubleshooting.md) - Common issues
|
|
|
|
## Triggers
|
|
|
|
This skill activates when you mention:
|
|
- "create an agent" or "build an agent"
|
|
- "sub-agent" or "subagent"
|
|
- "agent configuration"
|
|
- "Task tool" or "custom agent"
|
|
- "agent best practices"
|
|
|
|
## Testing
|
|
|
|
To test your agent:
|
|
|
|
```bash
|
|
# Ask Claude to use it explicitly
|
|
"Use the [agent-name] agent to [task]"
|
|
|
|
# Or test automatic triggering
|
|
"[Describe a task matching agent's description]"
|
|
```
|
|
|
|
Verify:
|
|
- [ ] Agent triggers correctly
|
|
- [ ] Has necessary tool access
|
|
- [ ] Produces expected outputs
|
|
- [ ] Maintains scope/focus
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-10-27
|
|
**Version**: 1.0.0
|