Creating Agents

How to create specialized agent personas for specific tasks.

What is an agent?

An agent is a markdown file that defines a specialized Claude persona with specific tools, skills, and instructions. Agents are invoked explicitly ("Use the security-sentinel agent") or dispatched by orchestrators.

Agent anatomy

---
name: my-agent
description: |
  Use this agent when you need to [specific task].
  Specializes in [domain expertise].
tools:
  - Read
  - Grep
  - Glob
  - WebSearch
skills:
  - relevant-skill
model: inherit
---

# My Agent Persona

You are a specialist in [domain]. Your role is to [primary function].

## Instructions

1. First, do this
2. Then, do that
3. Finally, produce this output

## Output Format

Structure your findings as:
- Summary
- Details
- Recommendations

Frontmatter fields

Field	Required	Description
name	Yes	Unique identifier
description	Yes	When to use this agent
tools	No	Claude Code tools the agent can use
skills	No	Skills to load when agent activates
model	No	inherit (default) or specific model
hooks	No	PreToolUse/PostToolUse hooks

Read-only agents

For agents that should only analyze (not modify) code, add a hook to block writes:

hooks:
  PreToolUse:
    - matcher: "Edit|Write|Bash"
      hooks:
        - type: command
          command: "~/.claude/hooks/block-writes.sh"

This prevents the agent from accidentally modifying files.

Placing agents

Agents go in a category directory under plugins/<plugin>/agents/:

plugins/core-standards/agents/
├── orchestrators/     # Workflow coordinators
├── review/            # Code reviewers
├── research/          # Researchers
├── design/            # Design specialists
├── architecture/      # Architecture analysts
├── security/          # Security auditors
├── workflow/          # Workflow helpers
└── docs/              # Documentation agents

Choose the category that best fits your agent's purpose.

Best practices

• Single responsibility — each agent should do one thing well
• Clear persona — define who the agent is and what it specializes in
• Structured output — define the expected output format
• Minimal tools — only grant the tools the agent actually needs
• Read-only when possible — use block-writes hooks for analysis agents