Creating an Agent
REQUIRED BACKGROUND: Read ed3d-extending-claude:writing-claude-directives for foundational guidance on token efficiency, compliance techniques, and directive structure. This skill focuses on agent-specific patterns.
What is an Agent?
An agent is a specialized Claude instance with:
- •Defined tools (Read, Edit, Bash, etc.)
- •Specific responsibilities (code review, security audit, research)
- •A focused system prompt
Agents are spawned via the Task tool or defined in plugin agents/ directories.
When to Create an Agent
Create when:
- •Task requires specialized expertise
- •Workflow benefits from tool restrictions
- •You want consistent behavior across invocations
- •Task is complex enough to warrant context isolation
Don't create for:
- •Simple, one-off tasks
- •Tasks the main Claude handles well
- •Purely conversational interactions
Agent File Structure
code
agents/ my-agent.md
Template:
markdown
--- name: agent-name description: Use when [specific triggers] - [what agent does] tools: Read, Grep, Glob, Bash model: sonnet --- # Agent Name [Agent system prompt - who they are, what they do] ## Responsibilities - Task 1 - Task 2 ## Workflow 1. Step 1 2. Step 2
Description: The Critical Field
The description field determines when Claude auto-delegates to your agent. It's searched when matching tasks to available agents.
Writing Effective Descriptions
Format: "Use when [specific triggers/symptoms] - [what the agent does]"
Write in third person. Injected into system prompt.
yaml
# Bad: vague, no triggers description: Helps with code # Bad: first person description: I review code for security issues # Good: specific triggers + action description: Use when reviewing code for security vulnerabilities, analyzing authentication flows, or checking for common security anti-patterns like SQL injection, XSS, or insecure dependencies
Include:
- •Specific symptoms that trigger use
- •Domain keywords (security, performance, testing)
- •File types or patterns if relevant
- •Actions the agent performs
Length: Max 1024 characters. Be specific, not verbose.
Tool Selection
Choose tools based on agent responsibilities:
| Tool | When to Include |
|---|---|
| Read | Reading files, analyzing code |
| Grep | Searching code patterns |
| Glob | Finding files by pattern |
| Edit | Modifying existing files |
| Write | Creating new files |
| Bash | Running commands, git, tests |
| TaskCreate/TaskUpdate | Tracking multi-step workflows (TodoWrite in older versions) |
| Task | Spawning sub-agents |
| WebFetch/WebSearch | Research tasks |
Principle: Include only what the agent needs. Fewer tools = more focused behavior.
Example restrictions:
- •Code reviewer:
Read, Grep, Glob(no write access) - •Implementor:
Read, Edit, Write, Bash, Grep, Glob - •Researcher:
Read, WebFetch, WebSearch, Glob
Agent Prompt Structure
Role Definition
Start with who the agent is:
markdown
You are a security expert specializing in web application security and secure coding practices.
Responsibilities
Explicit, numbered list:
markdown
## Your Responsibilities 1. Identify security vulnerabilities 2. Review authentication logic 3. Check for insecure dependencies 4. Report findings with severity ratings
Workflow
Step-by-step process:
markdown
## Workflow 1. **Scan:** Use Grep to find common vulnerability patterns 2. **Analyze:** Use Read to examine flagged files 3. **Verify:** Use Bash to run security audit tools 4. **Report:** Provide structured findings
Output Format
Define expected structure:
markdown
## Reporting Format For each finding: - **Severity:** Critical/High/Medium/Low - **Location:** `file:line` - **Issue:** What's vulnerable - **Impact:** What attacker could do - **Fix:** How to remediate
Constraints
What the agent should NOT do:
markdown
## Constraints - Report findings only; do not modify code - Ask for clarification if scope is unclear - Escalate to human for ambiguous security decisions
Model Selection
| Model | Use For |
|---|---|
| haiku | Simple tasks, fast iteration, high volume |
| sonnet | Balanced capability/cost, most tasks |
| opus | Complex reasoning, critical decisions, code review |
Specify in frontmatter:
yaml
model: opus
Testing Agents
1. Baseline Test
Run the task WITHOUT the agent. Document:
- •What went wrong
- •What was missing
- •How long it took
2. Agent Test
Run with agent. Verify:
- •Agent is auto-delegated (description triggers correctly)
- •Workflow is followed
- •Output matches expected format
- •Tool restrictions are respected
3. Edge Case Testing
Test with:
- •Ambiguous inputs
- •Missing context
- •Large/complex inputs
- •Tasks outside scope (should refuse gracefully)
4. Iteration
If agent fails:
- •Identify root cause (description? workflow? constraints?)
- •Update agent definition
- •Re-test
Common Patterns
Code Reviewer
markdown
--- name: code-reviewer description: Use when reviewing code changes, pull requests, or verifying implementation quality - analyzes for bugs, style issues, and best practices tools: Read, Grep, Glob, Bash model: opus --- # Code Reviewer You are a senior engineer reviewing code for correctness, readability, and maintainability. ## Responsibilities 1. Identify bugs and edge cases 2. Check error handling 3. Verify naming and style consistency 4. Suggest improvements ## Workflow 1. Read the changed files 2. Analyze for issues 3. Provide structured feedback ## Output Format For each issue: - **File:Line:** location - **Severity:** Critical/Major/Minor - **Issue:** description - **Suggestion:** how to fix
Research Agent
markdown
--- name: researcher description: Use when gathering information from the web, investigating APIs, or synthesizing documentation from multiple sources tools: Read, WebFetch, WebSearch, Glob model: sonnet --- # Research Agent You are a research specialist gathering and synthesizing information. ## Responsibilities 1. Search for relevant sources 2. Extract key information 3. Synthesize findings 4. Cite sources ## Workflow 1. WebSearch for relevant sources 2. WebFetch promising results 3. Extract and organize findings 4. Return structured synthesis with citations
Implementor Agent
markdown
--- name: task-implementor description: Use when implementing specific tasks from plans - writes code, runs tests, commits changes following TDD workflow tools: Read, Edit, Write, Bash, Grep, Glob, TaskCreate, TaskUpdate, TaskList model: sonnet --- # Task Implementor You implement tasks following TDD principles. ## Responsibilities 1. Write failing test first 2. Implement minimal code to pass 3. Refactor if needed 4. Commit with descriptive message ## Constraints - Never write implementation before test - Run tests after each change - Commit atomic, working changes only
Common Mistakes
| Mistake | Fix |
|---|---|
| Vague description | Include specific triggers and symptoms |
| Too many tools | Restrict to what's needed |
| No workflow | Add step-by-step process |
| No output format | Define expected structure |
| First-person description | Write in third person |
| Overly broad scope | Narrow to specific responsibility |
| No testing | Test auto-delegation and output quality |
Checklist
- • Description starts with "Use when...", third person
- • Description includes specific triggers/symptoms
- • Tools restricted to necessary set
- • Model appropriate for task complexity
- • Responsibilities clearly listed
- • Workflow is step-by-step
- • Output format defined
- • Constraints/limitations stated
- • Tested for auto-delegation
- • Tested for output quality