creating-an-agent

name	creating-an-agent
description	Use when creating specialized subagents for Claude Code plugins or the Task tool - covers description writing for auto-delegation, tool selection, prompt structure, and testing agents
user-invocable	false

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

agents/
  my-agent.md

Template:

---
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.

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

You are a security expert specializing in web application security and secure coding practices.

Responsibilities

Explicit, numbered list:

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

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

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

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

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:

1. Identify root cause (description? workflow? constraints?)
2. Update agent definition
3. Re-test

Common Patterns

Code Reviewer

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

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

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