aiskillstore Creating Agents
Guides creation of Claude Code subagents for task delegation.
Quick Start
- Define agent purpose (what task does it handle?)
- Choose location (project or user level)
- Select tools (minimal set needed)
- Write system prompt
- Save to
.claude/agents/
Workflow: Create New Agent
Progress:
- [ ] Define purpose and triggers
- [ ] Choose storage location
- [ ] Select tools and model
- [ ] Write system prompt
- [ ] Create agent file
Step 1: Define Purpose
Ask user:
- What specific task should this agent handle?
- When should it be invoked? (trigger phrases)
- Should it run proactively or on-demand?
Step 2: Choose Location
| Location | Path | Use For |
|---|---|---|
| Project | .claude/agents/ |
Team-shared, project-specific |
| User | ~/.claude/agents/ |
Personal, cross-project |
Project agents take priority over user agents.
Step 3: Select Tools and Model
Tools - Grant minimum needed:
| Tool | Purpose |
|---|---|
| Read | Read files |
| Write | Create files |
| Edit | Modify files |
| Glob | Find files |
| Grep | Search content |
| Bash | Run commands |
| Task | Spawn subagents |
Model - Choose based on task:
| Model | Best For |
|---|---|
opus |
Complex reasoning, nuanced decisions |
sonnet |
General tasks (default) |
haiku |
Quick lookups, simple analysis |
inherit |
Use parent's model |
Step 4: Write System Prompt
Keep prompts focused:
- State the agent's role clearly
- Define scope and constraints
- Provide examples if helpful
- Avoid unnecessary detail
Step 5: Create Agent File
---
name: {agent-name}
description: {when to use - include trigger words}
tools: Read, Grep, Glob
model: sonnet
---
{System prompt here}
Save to .claude/agents/{name}.md
Agent File Format
---
name: agent-name # Required: lowercase, hyphens
description: | # Required: when to invoke
Reviews code for quality issues.
Use when user asks for code review.
tools: Read, Grep, Glob # Optional: omit to inherit all
model: sonnet # Optional: opus, sonnet, haiku, inherit
permissionMode: default # Optional: permission handling
skills: skill1, skill2 # Optional: auto-load skills
---
System prompt defining the agent's behavior.
Built-in Agents
Before creating custom agents, know what's built-in:
| Agent | Model | Tools | Purpose |
|---|---|---|---|
| general-purpose | sonnet | All | Complex multi-step tasks |
| plan | haiku | Read, Glob, Grep, Bash | Research and strategy |
| explore | haiku | Read, Glob, Grep | Fast codebase exploration |
When to create custom agents:
- Need different tool restrictions
- Want domain-specific prompts
- Need proactive invocation
When to Use Each Type
| Need | Use |
|---|---|
| Quick file search | Built-in explore |
| Research before planning | Built-in plan |
| Multi-step code changes | Built-in general-purpose |
| Code review with specific rules | Custom reviewer agent |
| Security analysis | Custom security agent |
| Domain expertise (DB, API, etc.) | Custom specialist agent |
Proactive Invocation
To make Claude automatically use your agent, include in description:
- "PROACTIVELY" or "MUST BE USED"
- Clear trigger conditions
description: |
PROACTIVELY reviews all code changes before commit.
MUST BE USED when user mentions "review" or "check code".
Templates
Use templates from templates/ directory:
- templates/reviewer.md - Code review agent
- templates/researcher.md - Read-only research
- templates/specialist.md - Domain expert
See reference.md for complete configuration details.