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: sonnet
---

# 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`	Yes	`opus`, `sonnet` or `haiku`; never `inherit`, never a versioned ID; enforced by guard 135
`hooks`	No	PreToolUse/PostToolUse hooks
`isolation`	No	Set to `worktree` for agents that modify files and may run concurrently

Choosing the tier:

Guard 135 hard-pins some agents to opus: security-sentinel, spec-compliance-reviewer, architecture-strategist, strategic-mentor and data-integrity-guardian (matched by file name or name:, each matching exactly one agent), and every agent placed under agents/orchestrators/. Do not dispatch any of them with a per-invocation model outside the opus family (opus, opus[…], claude-opus-*) — in a skill, command or agent body, any text file a plugin ships to run (skill references, scripts, YAML, bin/, hooks/), markdown under configs/user-global/ or templates/, a Model column of a table, or a forked skill's frontmatter (agent: naming one of them, plain, vt-c- or plugin-namespaced, with a model: other than opus) — and do not name CLAUDE_CODE_SUBAGENT_MODEL* or ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL in a file the toolkit ships (.claude/settings*.json any non-markdown file under configs/ or templates/, profile patches and hidden directories included, and any plugin script). An agent file under .claude/agents/, configs/ or templates/ is held to the same tier rules as one under plugins/*/agents/. The guard fails on each, because each one overrides or remaps the frontmatter tier. Its body check is a tripwire, not a full defence (Decision 12): a model value within three lines of a pinned name (any case) is attributed to it, even on a line that names another agent. Prose such as "run it on the Haiku model", NUL-padded files, tables without a leading pipe and symlinked directories are not read.

opus — reasoning depth: security, spec compliance, architecture, strategy (strategic-mentor, product-challenge-reviewer), data integrity, open-ended flow analysis (spec-flow-analyzer), and every orchestrator.
sonnet — structured review, research and synthesis: most reviewers, the researchers, and the domain writers. Also test-runner: its .test-gate.md verdict is trusted downstream, so it stays above haiku until that verdict comes from the exit code.
haiku — mechanical or template-driven work: lint, learnings lookups, skill extraction, template-driven README writing.

Agents that already declared an alias before SPEC-215 kept it, which is why some tiers do not follow the rules above: among the IMS agents, isms-expert, dsms-expert and ims-content-planner are opus (their peer qms-ims-expert is sonnet, as a domain writer), and design-implementation-reviewer stays opus. specs/215-model-tiering-and-review-runtime-reduction/plan.md records the reason for every agent's tier.

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:

The agent uses Write, Edit, MultiEdit, or Bash (file-modifying) tools
The agent could run concurrently with other agents
The agent's work should be on a separate branch
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/vt-base/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