Skip to content

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
isolation No Set to worktree for agents that modify files and may run concurrently

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.

Write-capable agents and isolation

Agents that modify files and may run concurrently should use isolation: worktree to prevent branch contamination and merge conflicts. When set, each invocation gets its own git worktree branching from the default remote branch.

isolation: worktree

Decision checklist — add isolation: worktree when all four apply:

  1. The agent uses Write, Edit, MultiEdit, or Bash (file-modifying) tools
  2. The agent could run concurrently with other agents
  3. The agent's work should be on a separate branch
  4. The agent does NOT need to see the current dirty working tree

Do not isolate agents that: - Are read-only (research, review, analysis) - Need dirty tree visibility (bugfix-orchestrator, pr-comment-resolver) - Write to non-git paths (IMS vault agents) - Already use context: fork (different isolation mechanism) - Have block-writes hooks (cannot write regardless)

Placing agents

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

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

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

Further reading