title

Sub-Agents Reference

Overview

Purpose: Specialized Claude modes with custom tools and prompts Invocation: /agent-name [prompt] (or spawned via the Task tool) Location: agents/*.md at plugin root Format: Markdown with YAML frontmatter

Characteristics:

Custom system prompts
Controlled tool access
Dedicated workflows
Isolated execution

Built-in Agents

Explore Agent

Purpose: Read-only code research Invocation: /explore <query>

Available tools:

semantic_search - Semantic code search
grep_search - Pattern matching
read_file - Read file contents
list_dir - Directory listing

Restricted tools:

write_file - No write access
run_command - No execution
replace_string_in_file - No edits

Use cases:

Code exploration
Architecture understanding
Finding examples
API research

Example:

/explore Find all authentication-related files
/explore How is error handling implemented?

Plan Agent

Purpose: Task planning and design Invocation: /plan <task>

Available tools:

read_file - Read codebase
semantic_search - Search code
list_dir - Explore structure

Restricted tools:

run_command - No execution
write_file - No changes

Use cases:

Break down complex tasks
Design solutions
Create implementation plans
Propose approaches

Example:

/plan How should we refactor the authentication system?
/plan Design a testing strategy for this module

Custom Agent Creation

Location: agents/agent-name.md at plugin root (not inside .claude-plugin/)

Agent File Schema

YAML frontmatter:

name: string # Agent identifier (lowercase-hyphenated)
description: string # Purpose and use case
tools: # Allowed tools array — use Claude Code tool names
  - 'Read'
  - 'Grep'
  - 'Glob'

Markdown content: Agent system prompt and instructions

Minimum Viable Agent

mkdir -p my-plugin/agents
cat > my-plugin/agents/reviewer.md << 'EOF'
---
name: reviewer
description: Code review agent
tools:
  - Read
  - Grep
  - Glob
---

# Code Reviewer

You are a code reviewer. Focus on:
- Code quality
- Best practices
- Security issues
EOF

Available Tools

Use the Claude Code tool names exactly as they appear in the tool list. Common tool names:

Read-Only Tools

Tool	Purpose
`Read`	Read file contents
`Grep`	Pattern search in files
`Glob`	File name/pattern matching

Write Tools

Tool	Purpose
`Edit`	Edit existing file
`Write`	Create/replace file

Execution Tools

Tool	Purpose
`Bash`	Run shell commands
`Task`	Spawn a subagent

Tool Access Control

Allowlist Approach

Strategy: Explicitly list allowed tools (recommended for analyst/read-only agents)

tools:
  - Read
  - Grep
  - Glob

Default: All unlisted tools are restricted

Denylist Approach

Strategy: Restrict specific tools (used less commonly)

restrictedTools:
  - Bash
  - Write

Default: All unlisted tools are allowed

Combined Approach

Strategy: Explicit allow + explicit deny

tools:
  - Read
  - Grep
restrictedTools:
  - Bash

Behavior: tools takes precedence, restrictedTools adds additional restrictions

Reference the agent in manifest.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin with custom agent"
}

Agents in agents/ (at the plugin root) are automatically discovered.

3. Invoke the agent

Users can invoke with:

/my-agent Do the thing

Agent configuration

Frontmatter fields

name: agent-name
description: One-line summary
tools:
  - read_file
  - grep_search
restrictedTools:
  - run_in_terminal
permissions:
  mode: explicit
  allowFileWrite: false

Required fields

name: Agent identifier (lowercase with hyphens)
description: Brief summary

Optional fields

tools: Allowed tools (explicit list)
restrictedTools: Denied tools (takes precedence)
permissions: Permission configuration
timeout: Max execution time in seconds
maxTokens: Token limit for responses

Tool control

Three ways to control tool access:

1. Explicit allow list

tools:
  - read_file
  - grep_search
  - semantic_search

Agent can ONLY use these tools.

2. Explicit deny list

restrictedTools:
  - run_in_terminal
  - replace_string_in_file

Agent can use any tool EXCEPT these.

3. Combined

tools:
  - read_file
  - grep_search
  - run_in_terminal
restrictedTools:
  - run_in_terminal

restrictedTools takes precedence, so run_in_terminal is blocked.

Permission modes

permissions:
  mode: explicit # or 'permissive'
  allowFileWrite: false
  allowFileRead: true
  allowNetworkAccess: false

explicit: Only allowed actions permitted
permissive: All actions allowed except restricted

Agent instructions

The markdown content below the frontmatter is the agent's system prompt.

Example: Code reviewer

---
name: reviewer
description: Systematic code review agent
tools:
  - read_file
  - grep_search
  - semantic_search
restrictedTools:
  - replace_string_in_file
  - run_in_terminal
---

# Code Review Agent

You are a meticulous code reviewer focused on quality, security, and best practices.

## Review process

1. **Read the code**: Understand what it does
2. **Check for issues**:
   - Security vulnerabilities
   - Performance problems
   - Code smells
   - Missing error handling
   - Unclear naming
3. **Provide feedback**: Clear, actionable suggestions
4. **Verify tests**: Ensure adequate test coverage

## Guidelines

- Be constructive and specific
- Explain WHY something is an issue
- Suggest concrete improvements
- Consider context and constraints
- Prioritize critical issues

## Focus areas

- **Security**: SQL injection, XSS, secrets in code
- **Performance**: N+1 queries, unnecessary loops
- **Maintainability**: Clear naming, proper abstractions
- **Testing**: Edge cases, error paths

Advanced patterns

Contextual agents

Load different behavior based on context:

---
name: language-aware-agent
description: Adapts to programming language
---

# Language-Aware Agent

${language === 'python' ? `You are a Python expert. Follow PEP 8 and use type hints.` :
language === 'typescript' ?
`You are a TypeScript expert. Use strict mode and proper types.` :
`General programming assistant.`}

Chained agents

One agent can invoke another:

---
name: orchestrator
description: Coordinates multiple sub-agents
---

# Orchestrator

You coordinate specialized agents to complete complex tasks.

When analyzing code:

1. Use `/explore` to find relevant files
2. Use `/reviewer` to check code quality
3. Use `/plan` to propose improvements

Hooks integration

Trigger agents at specific lifecycle points:

---
name: session-starter
description: Runs at session start
---

# Session Start Agent

Run when a new session begins:

1. Check for uncommitted changes
2. Verify dependencies are installed
3. Display project status

Then configure in a hook (see Hooks).

Examples

Test generator agent

---
name: test-gen
description: Generate comprehensive test cases
tools:
  - read_file
  - grep_search
  - create_file
restrictedTools:
  - run_in_terminal
---

# Test Generator

You generate comprehensive test cases for code.

## Process

1. **Analyze code**: Understand the implementation
2. **Identify test cases**:
   - Happy path
   - Edge cases
   - Error conditions
   - Boundary values
3. **Generate tests**: Write clear, maintainable tests
4. **Verify coverage**: Ensure all paths tested

## Test structure

\`\`\`python import pytest

def test_happy_path(): """Test normal operation.""" result = function(valid_input)
assert result == expected_output

def test_edge_case(): """Test boundary condition.""" result = function(edge_input)
assert result == edge_output

def test_error_handling(): """Test error condition.""" with
pytest.raises(ExpectedException): function(invalid_input) \`\`\`

Documentation agent

---
name: doc-gen
description: Generate and update documentation
tools:
  - read_file
  - grep_search
  - semantic_search
  - create_file
  - replace_string_in_file
---

# Documentation Generator

You create and maintain project documentation.

## Documentation types

### API documentation

- Function signatures
- Parameter descriptions
- Return values
- Examples
- Error conditions

### README files

- Project overview
- Installation instructions
- Usage examples
- Configuration options

### Inline comments

- Complex logic explanations
- Intent clarification
- Warning about edge cases

## Style guide

- Use clear, concise language
- Provide concrete examples
- Keep formatting consistent
- Update when code changes

Security audit agent

---
name: security-audit
description: Security vulnerability scanner
tools:
  - read_file
  - grep_search
  - semantic_search
restrictedTools:
  - run_in_terminal
  - create_file
  - replace_string_in_file
---

# Security Audit Agent

You perform security audits of code.

## Scan for

### Injection vulnerabilities

- SQL injection
- Command injection
- XSS vulnerabilities

### Authentication issues

- Weak password policies
- Missing authentication
- Broken session management

### Data exposure

- Secrets in code
- Unencrypted sensitive data
- Information leakage

### Dependencies

- Known vulnerable packages
- Outdated dependencies

## Report format

For each issue:

1. **Severity**: Critical/High/Medium/Low
2. **Location**: File and line number
3. **Description**: What the issue is
4. **Impact**: Potential consequences
5. **Remediation**: How to fix it

Testing agents

Test your agent locally:

# Install plugin
/plugin install /path/to/plugin --scope local

# Invoke agent
/my-agent Test the agent behavior

Verify:

Agent responds to invocation
Tool restrictions work
Instructions are followed
Output is appropriate

Best practices

Clear instructions

Write specific, actionable instructions:

✅ Good: "Check for SQL injection by looking for string concatenation in SQL queries" ❌ Vague: "Look for security issues"

Appropriate tool access

Only grant tools needed for the task:

✅ Read-only agent: read_file, grep_search ❌ Over-permissive: All tools allowed

Focused purpose

One agent, one job:

✅ Good: Separate review and fix agents ❌ Too broad: One agent to review, fix, test, and deploy

Documentation

Document agent usage in README:

## Agents

### /reviewer

Reviews code for quality and security issues.

Usage: `/reviewer Check the login.py file`

### /test-gen

Generates test cases for code.

Usage: `/test-gen Create tests for auth module`

Debugging agents

Agent not found

Check:

Agent file in agents/ (at the plugin root)
Valid YAML frontmatter
Plugin installed and enabled

Agent not following instructions

Check:

Instructions are clear and specific
No conflicting guidelines
Examples are provided

Tool access issues

Check:

Required tools are in tools list
No overlap with restrictedTools
Permissions mode is correct

Next steps

Skills for domain knowledge
Hooks to trigger agents automatically
Plugins reference for technical details
Create plugins to package and distribute agents

FilesExpand file tree

sub-agents.md

Latest commit

History

sub-agents.md

File metadata and controls

Sub-Agents Reference

Overview

Built-in Agents

Explore Agent

Plan Agent

Custom Agent Creation

Agent File Schema

Minimum Viable Agent

Available Tools

Read-Only Tools

Write Tools

Execution Tools

Tool Access Control

Allowlist Approach

Denylist Approach

Combined Approach

3. Invoke the agent

Agent configuration

Frontmatter fields

Required fields

Optional fields

Tool control

1. Explicit allow list

2. Explicit deny list

3. Combined

Permission modes

Agent instructions

Example: Code reviewer

Advanced patterns

Contextual agents

Chained agents

Hooks integration

Examples

Test generator agent

Documentation agent

Security audit agent

Testing agents

Best practices

Clear instructions

Appropriate tool access

Focused purpose

Documentation

Debugging agents

Agent not found

Agent not following instructions

Tool access issues

Next steps