When Main Claude Should Use {AgentName}

Agents

Specialized subagent definitions for Task tool delegation.

Structure

Each agent is a markdown file with YAML frontmatter:

---
model: inherit
permissionMode: default           # Optional: default, plan, acceptEdits, dontAsk, bypassPermissions
maxTokens: 4000                   # Optional: limit output length
description: "Role phrase. Capability summary."
tools:
  - ToolName
  - Bash(command:pattern)
hooks:                            # Optional: inject prompts at execution points
  Stop:
    - matcher: "*"
      hooks:
        - type: prompt
          prompt: "Final validation prompt"
---

# AgentName

{Tagline}

## Purpose
## When Main Claude Should Use {AgentName}
## Decision Table
## Input
## Output Format
## Rules
## What {AgentName} Does NOT Do

Input Format Section

The ## Input section should clearly specify what the agent expects to receive.

Template:

## Input

You'll receive a specific {task type}. Examples:
- "{Example input 1}"
- "{Example input 2}"
- "{Example input 3}"

**Required context:**
- {What must be provided}
- {Paths, specs, constraints}

**Optional context:**
- {Nice-to-have information}

Good input specifications:

• Concrete examples showing expected format
• Clear distinction between required and optional context
• Explicit about what makes a task well-formed vs poorly-formed

Example (from general-purpose delegation):

## Input

You'll receive a specific implementation task. Examples:
- "Create the UserAuth class in src/auth/UserAuth.ts with login, logout, and validateSession methods"
- "Fix the race condition in src/api/cache.ts by adding mutex locks"
- "Add input validation to all POST endpoints in src/routes/users.ts"

Required Fields

Model Inheritance (CRITICAL)

NEVER pass model: "haiku" or model: "sonnet" when spawning agents.

The Task tool's default description suggests "prefer haiku for quick tasks" - IGNORE THIS. This plugin overrides that guidance. All oh-my-claude agents are defined with model: inherit in their frontmatter, and the parent session should NEVER override this with a downgrade.

Why this matters:

• The user pays for their model tier (opus, sonnet, etc.) and expects that intelligence level
• Downgrading to haiku "to save tokens" defeats the purpose of using a premium tier
• Agent quality directly impacts task success - use maximum available intelligence

When spawning agents:

# CORRECT - inherits parent model
Task(subagent_type="oh-my-claude:critic", prompt="...")

# CORRECT - explicit inherit
Task(subagent_type="oh-my-claude:librarian", model="inherit", prompt="...")

# WRONG - NEVER DO THIS
Task(subagent_type="oh-my-claude:critic", model="haiku", prompt="...")
Task(subagent_type="oh-my-claude:validator", model="sonnet", prompt="...")

Permission Modes

Control how the agent handles permission prompts via the permissionMode frontmatter field.

Guidelines:

• Read-only agents (librarian): use plan or dontAsk
• Review agents (advisor, risk-assessor, critic): use plan to prevent accidental changes
• Validation agents (validator): use plan for safety, full Bash for test execution
• Never use bypassPermissions unless explicitly required by workflow

---
model: inherit
permissionMode: plan
description: "Read-only reconnaissance agent."
tools:
  - Read
  - Glob
  - Grep
---

Hooks Patterns

Agents can define hooks to inject prompts or validation at specific execution points.

Hook Types

PreToolUse Example

Inject verification before file modifications:

hooks:
  PreToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: prompt
          prompt: "Verify this change aligns with the task scope before proceeding."

PostToolUse Example

Process tool output for specific patterns:

hooks:
  PostToolUse:
    - matcher: "Bash"
      hooks:
        - type: prompt
          prompt: "Check for errors in command output. If errors found, document them."

Stop Example

Enforce structured output format:

hooks:
  Stop:
    - matcher: "*"
      hooks:
        - type: prompt
          prompt: |
            Before completing, ensure your response includes:
            1. A VERDICT line (PASS/FAIL/NEEDS_REVIEW)
            2. Summary of findings
            3. Specific file paths for any issues found

Matcher Patterns

Output Constraints

Control token limits via maxTokens in frontmatter for agents with specific output requirements.

When to use output constraints:

• Agents that tend to over-explain or dump content
• Read-only agents returning locations instead of content
• Review agents that should give feedback, not implementations

---
model: inherit
maxTokens: 4000
description: "Concise reconnaissance agent."
tools:
  - Glob
  - Grep
---

Tool Permissions

Default: Omit tools entirely. Agents inherit the parent session's tool access, which is governed by Claude Code's built-in permission system (settings.json, permission modes, PermissionRequest hooks). This avoids a redundant restriction layer that causes unnecessary permission prompts.

Use permissionMode to control agent behavior instead:

• plan — read-only agents (critic, advisor, risk-assessor, librarian, code-reviewer, security-auditor)
• default — standard agents

Only add explicit tools if you need to restrict beyond what permissionMode provides.

Description Pattern

Format: "{Adjective} {role} agent. {Action verbs} {capabilities}. {Limitations}."

Examples:

• "Quick reconnaissance agent. Finds files, locates definitions. Returns locations, not content."
• "Focused implementation agent. Executes ONE specific task completely."

Agent Tiers

Note: Use Claude Code's built-in agents for common tasks:

• Explore - File/definition discovery
• Plan - Complex task decomposition
• general-purpose - Implementation tasks

Team Context

Agents work the same whether spawned by a team lead, a teammate, or a solo session. When native agent teams are enabled (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1):

• Team leads should use specialist agents (librarian, advisor, risk-assessor, critic, validator) for focused analysis/verification, and teammates for implementation work
• Teammates can also spawn specialist agents as subagents for their own analysis needs
• Agent identity and tool constraints are unchanged regardless of caller

Adding New Agent

1. Create agents/{name}.md
2. Add YAML frontmatter (model, description, tools)
3. Document purpose, use cases, output format
4. Define explicit scope boundaries

Task System Integration (Optional)

Agents can participate in Task-based orchestration workflows. This is optional - agents work fine standalone.

When to Add Task Integration

Add Task integration to agents that:

• Run long-running discovery or implementation work
• Can be parallelized (multiple instances of same agent type)
• Benefit from self-discovery via owner field

Skip Task integration for advisory agents (advisor, risk-assessor, critic) that are called on-demand.

Standard Pattern

Add this section to agent system prompts that should support Task workflows:

## Task System Integration (Optional)

If assigned via owner field in a task workflow:
1. Call TaskList to find tasks where owner matches your role
2. TaskUpdate(status='in_progress') when starting
3. Perform your work
4. TaskUpdate(status='completed') when done
5. Check TaskList for newly unblocked tasks

Category-Specific Templates

Read agents (librarian):

• Report findings (summaries, extracted content, observations)
• May spawn follow-up tasks based on discoveries

Review agents (advisor, risk-assessor, critic):

• Provide analysis and feedback
• Do not make changes directly

Validation agents (validator):

• Run checks/tests as described
• Report pass/fail with specific results

Edge Case Handling

Instruct agents to handle:

• No tasks found: Report "No tasks assigned to {role}" and exit
• Task already in_progress: Skip (another agent may have claimed it)
• Task blocked: Skip and check for unblocked tasks

Claude Code has built-in Task API documentation. Focus on small, validateable tasks.

Anti-Patterns

• Don't add explicit tools unless permissionMode is insufficient
• Don't omit "What Agent Does NOT Do" section
• Don't use vague descriptions
• Don't duplicate Claude Code's permission system with agent-level restrictions