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:

• Identify root cause (description? workflow? constraints?)

• Update agent definition

• 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