/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:** descrip