---
name: Creating an Agent
slug: creating-an-agent
category: AI Engineering
description: Creating an Agent explains how to design specialized subagents for Claude Code plugins or the Task tool. It covers trigger descriptions, tool limits, prompt structure, and testing agents.
github: "https://github.com/ed3dai/ed3d-plugins/tree/main/plugins/ed3d-extending-claude/skills/creating-an-agent"
language: Python
stars: 248
forks: 32
install: "npx degit https://github.com/ed3dai/ed3d-plugins/tree/main/plugins/ed3d-extending-claude/skills/creating-an-agent ~/.claude/skills/creating-an-agent"
installs_to: ~/.claude/skills/creating-an-agent
source_path: plugins/ed3d-extending-claude/skills/creating-an-agent/SKILL.md
collection_size: 25
category_size: 2631
collection_url: "https://dirskills.com/collections/ed3dai/ed3d-plugins"
added: 2026-09-02T05:21:05.644Z
last_synced: 2026-09-02T05:21:05.644Z
canonical_url: "https://dirskills.com/skills/creating-an-agent"
---

# Creating an Agent

Creating an Agent explains how to design specialized subagents for Claude Code plugins or the Task tool. It covers trigger descriptions, tool limits, prompt structure, and testing agents.

**Install:**

```bash
npx degit https://github.com/ed3dai/ed3d-plugins/tree/main/plugins/ed3d-extending-claude/skills/creating-an-agent ~/.claude/skills/creating-an-agent
```

## README

# 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:**
```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:
1. Identify root cause (description? workflow? constraints?)
2. Update agent definition
3. 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