Agent Frontmatter Fields Reference¶

All agent .md files use YAML frontmatter between --- delimiters. This reference documents every supported field.

Required Fields¶

Field	Type	Description
`name`	string	Unique identifier, lowercase-with-hyphens
`description`	string	When to use this agent. Include examples for the Task tool dispatcher

Optional Fields¶

Field	Type	Default	Description
`tools`	list/string	All tools	Claude Code tools the agent can use
`skills`	list	None	Skills to load when agent activates
`model`	string	`inherit`	`inherit`, `sonnet`, `opus`, or `haiku`
`hooks`	object	None	PreToolUse/PostToolUse hooks (see below)
`isolation`	string	None	Set to `worktree` for file-modifying concurrent agents
`color`	string	None	Display color in UI
`context`	string	None	Set to `fork` for isolated sub-agent execution

Isolation Decision Checklist¶

When creating a new agent, determine if it needs isolation: worktree by answering these four questions:

Does this agent use Write, Edit, MultiEdit, or Bash (file-modifying) tools?
If NO: skip isolation (agent is read-only)
Could this agent run concurrently with other agents?
If NO: skip isolation (sequential execution is safe)
Does the agent's work need to be on a separate branch?
If NO: skip isolation (changes belong on current branch)
Does the agent need to see the current dirty working tree?
If YES: skip isolation (worktree branches from default remote, not current state)

Rule: If answers are YES, YES, YES, NO: add isolation: worktree.

Agents that should NOT be isolated¶

Read-only agents (research, review, analysis) — no file modifications
Agents needing dirty tree visibility (bugfix-orchestrator, pr-comment-resolver) — must see uncommitted work
Vault-write agents (IMS agents) — write to non-git paths (OneDrive)
Agents using context: fork — already run in isolated sub-agent context
Agents with block-writes hooks — cannot write files regardless

Examples¶

Write-capable agent with isolation¶

---
name: knowledge-work-orchestrator
description: |
  Phase orchestrator for the Knowledge Work workflow.
  Coordinates planning, execution, review, and publication.
tools:
  - Task
  - Read
  - Write
  - Glob
  - Grep
  - TodoWrite
isolation: worktree
---

Read-only agent (no isolation needed)¶

---
name: git-history-analyzer
description: |
  Analyzes git history for patterns and evolution.
tools:
  - Read
  - Grep
  - Glob
  - Bash
hooks:
  PreToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "~/.claude/hooks/block-writes.sh"
---

Hooks Field Structure¶

hooks:
  PreToolUse:
    - matcher: "Edit|Write|Bash"    # Regex pattern for tool names
      hooks:
        - type: command
          command: "path/to/script.sh"
  PostToolUse:
    - matcher: "Write"
      hooks:
        - type: command
          command: "path/to/post-write.sh"