name: manage-agents description: Create, modify, and manage Claude Code subagents with specialized expertise. Use when you need to "work with agents", "create an agent", "modify an agent", "set up a specialist", "I need an agent for [task]", or "agent to handle [domain]". Covers agent file format, YAML frontmatter, system prompts, tool restrictions, MCP integration, model selection, and testing. allowed-tools:

Read
Write
Grep
Glob
Bash

Manage Agents

Create and manage specialized Claude Code subagents with custom capabilities, tool access, and expertise domains.

Use this skill when you need to:

Create new subagents for specialized tasks
Modify existing agent configurations
Set up domain experts (Python, Neo4j, Testing, etc.)
Configure tool access and MCP server permissions
Understand agent structure and best practices

Quick Start

To create a new agent:

Understand the Need: What specialized capability or domain expertise is needed?
Choose Location: Project-level (.claude/agents/) or user-level (~/.claude/agents/)
Define Configuration: Name, description, model, tools, and permissions
Write System Prompt: Clear instructions for the agent's specialized role
Test & Validate: Invoke with @agent-name and verify behavior

Core Sections

Instructions
- Step 1: Analyze Requirements - Determine expertise domain, tool needs, and location
- Step 2: Create Agent File - Choose project vs user location
- Step 3: Write Agent Configuration - YAML frontmatter template
- Step 4: Configure Tool Access - Explicit tools, all tools, or no tools
- Step 5: Configure MCP Access - Specific servers, all servers, or all resources
- Step 6: Select Model - Sonnet, Opus, or Haiku based on complexity
- Step 7: Write System Prompt - Clear, actionable, quality-focused instructions
- Step 8: Test the Agent - Verify behavior and tool access
- Step 9: Document Integration - Update dispatch.md and CLAUDE.md
Common Patterns
- Pattern 1: Domain Expert - Read-only analysis and recommendations
- Pattern 2: Code Generator - Write access with quality gates
- Pattern 3: Orchestrator - Planning agent that delegates
- Pattern 4: Quality Guardian - Read-only validation
- Pattern 5: Integration Specialist - MCP-focused agent

Supporting Resources

Configuration Reference - Complete field documentation

Utility Scripts

Agent Detection - Detect @agent-name patterns in prompts
Agent Memory Creation - Create MCP memory entries for agents
Agent Validation - Validate agent file format and configuration

Advanced Topics

Troubleshooting
Validation - Validate agent files with script
Quality Checklist - Pre-finalization checklist
Advanced: Agent Chaining - Agent-to-agent delegation
Advanced: Dynamic Selection - Autonomous agent selection
Integration with This Project - Project-specific guidance

Instructions

Step 1: Analyze Requirements

Before creating an agent, determine:

Expertise Domain: What specialized knowledge does this agent need?
Tool Requirements: Which tools should be allowed/restricted?
Context Needs: Does it need access to project files, memory, or MCP servers?
Location: Project-specific (.claude/agents/) or user-wide (~/.claude/agents/)?
Model Selection: Does this need Sonnet, Opus, or Haiku?

Step 2: Create Agent File

Project Agent (checked into git):

# Location: .claude/agents/my-specialist.md

User Agent (personal, not in git):

# Location: ~/.claude/agents/my-specialist.md

Priority: Project agents override user agents with the same name.

Step 3: Write Agent Configuration

Use this template:

---
name: agent-name
description: Clear description of what this agent does and when to use it
model: claude-sonnet-4
tools:
  - Read
  - Write
  - Grep
  - Glob
  - Bash
mcp_servers:
  - server-name
allow_all_tools: false
allow_all_mcp_servers: false
allow_mcp_resources_from_all_servers: false
---

# Agent Name - Specialized Role

You are a specialized agent focused on [domain/task]. Your expertise includes:
- [Key capability 1]
- [Key capability 2]
- [Key capability 3]

## Your Responsibilities

1. **[Primary Responsibility]**: Clear description
2. **[Secondary Responsibility]**: Clear description
3. **[Quality Standards]**: What standards you uphold

## Tools Available

You have access to:
- [Tool 1]: [How to use it]
- [Tool 2]: [How to use it]
- [MCP Server]: [What it provides]

## Workflow

When invoked, follow these steps:

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Quality Gates

Before completing work:
- [ ] [Quality check 1]
- [ ] [Quality check 2]
- [ ] [Quality check 3]

## Integration with Skills

You can leverage these skills:
- [Skill 1]: [When to use]
- [Skill 2]: [When to use]

## Best Practices

- [Practice 1]
- [Practice 2]
- [Practice 3]

## Examples

[Provide concrete examples of your work]

Step 4: Configure Tool Access

Option 1: Explicit Tool List (Recommended)

tools:
  - Read
  - Write
  - Grep
  - Glob
allow_all_tools: false

Option 2: Allow All Tools

allow_all_tools: true

Option 3: No Tools (Analysis/planning only)

tools: []
allow_all_tools: false

Step 5: Configure MCP Access

Option 1: Specific MCP Servers (Recommended)

mcp_servers:
  - project-watch-mcp
  - memory
allow_all_mcp_servers: false

Option 2: All MCP Servers

allow_all_mcp_servers: true

Option 3: All MCP Resources (Use sparingly)

allow_mcp_resources_from_all_servers: true

Step 6: Select Model

Choose based on task complexity:

claude-sonnet-4: Default, balanced performance (most agents)
claude-opus-4: Complex reasoning, critical decisions
claude-haiku-3-5: Fast, simple tasks, high volume

Default if not specified: claude-sonnet-4

Step 7: Write System Prompt

The content after YAML frontmatter is the system prompt. Make it:

Specific: Define clear responsibilities and scope
Actionable: Include step-by-step workflows
Quality-Focused: Define standards and validation criteria
Integrated: Reference skills, tools, and project patterns
Example-Rich: Show concrete examples of expected work

Step 8: Test the Agent

Interactive Testing:

Invoke the agent in Claude:

@agent-name please [task description]

Programmatic Testing:

Test agents from command line using CLI tools:

# Quick test with claude_ask.py
python3 .claude/tools/agents/claude_ask.py agent-name "test question"

# Quiet mode (just the answer)
python3 .claude/tools/agents/claude_ask.py -q agent-name "test question"

# JSON output for validation
python3 .claude/tools/agents/claude_ask.py --json agent-name "test question"

# With timeout for complex tasks
python3 .claude/tools/agents/claude_ask.py agent-name "complex task" --timeout 120

For complete documentation on CLI testing tools, see:

.claude/tools/agents/README.md - Unified documentation for all agent CLI tools

Verify:

[ ] Agent appears in autocomplete
[ ] Agent has correct tool access
[ ] Agent follows its system prompt
[ ] Agent produces expected quality
[ ] Agent integrates with skills correctly
[ ] Agent responds correctly via CLI tools

Step 9: Document Integration

If this is a project agent, document in relevant files:

Add to ../orchestrate-agents/references/dispatch.md agent table
Reference in CLAUDE.md if core to workflow
Update skills that should integrate with this agent

Configuration Reference

For complete configuration field documentation, see references/reference.md.

Examples

For practical agent examples and patterns, see the utility scripts section and references/reference.md for detailed configuration examples.

Working with Agent Detection

The scripts/agent_detector_example.py script demonstrates patterns for detecting agents in hooks or tools:

The example demonstrates:

Using detect_agent() to identify agent mentions in user prompts
Getting available agents and patterns with get_available_agents()
Pattern matching for agent invocation (e.g., @unit-tester)
Integration points for hooks that need agent awareness

Run the example:

cd /Users/dawiddutoit/projects/play/temet-run/.claude
./.venv/bin/python3 skills/manage-agents/scripts/agent_detector_example.py

The script uses the shared .claude/ environment pattern:

# Setup: Add .claude to path for skill_utils
sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent))

from skill_utils import ensure_path_setup, get_project_root
ensure_path_setup()

# Now import from the shared environment
import yaml

This pattern allows the script to access dependencies installed in .claude/pyproject.toml without duplicating virtual environments.

Creating Agent Core Memories

The scripts/create_agent_memories_simple.py script demonstrates programmatic memory creation:

The example demonstrates:

Extracting agent names and descriptions from agent files
Connecting to the memory MCP server using FastMCP client
Creating core memory entries for all agents (agent-{name}-core)
Batch processing of agent directory

Run the example:

cd /Users/dawiddutoit/projects/play/temet-run/.claude
uv sync --extras mcp  # Install MCP dependencies (if not already done)
./.venv/bin/python3 skills/manage-agents/scripts/create_agent_memories_simple.py

Prerequisites:

Neo4j memory server running
MCP dependencies installed via uv sync --extras mcp
Environment variables set: NEO4J_URL, NEO4J_USERNAME, NEO4J_PASSWORD, NEO4J_DATABASE

The script also uses the shared .claude/ environment pattern, allowing it to access yaml and fastmcp dependencies without duplicating virtual environments.

Common Patterns

Pattern 1: Domain Expert

Specialized knowledge agent with read-only access for analysis and recommendations.

Pattern 2: Code Generator

Write access with quality gates, focused on specific code patterns.

Pattern 3: Orchestrator

High-level planning agent that delegates to other agents.

Pattern 4: Quality Guardian

Read-only validation agent that checks against standards.

Pattern 5: Integration Specialist

MCP-focused agent with access to specific external tools.

Troubleshooting

Agent not appearing in autocomplete:

Check file is in .claude/agents/ or ~/.claude/agents/
Verify YAML frontmatter is valid
Ensure name field matches filename (without .md)

Tool access denied:

Check tools list in frontmatter
Verify allow_all_tools setting
Ensure MCP servers are configured correctly

Agent behavior incorrect:

Review system prompt clarity
Check for conflicting instructions
Verify model selection is appropriate

Integration issues:

Ensure skills referenced are available
Check MCP server connections
Verify project context is accessible

Validation

Use the scripts/validate_agent.py script to check agent files:

cd /Users/dawiddutoit/projects/play/temet-run/.claude
./.venv/bin/python3 skills/manage-agents/scripts/validate_agent.py agents/my-agent.md

The validation script checks:

Valid YAML frontmatter syntax
Required fields (name, description)
Valid tool names and model selection
Name matches filename
Description quality (includes trigger terms)
Non-empty system prompt

Quality Checklist

Before finalizing an agent:

[ ] YAML frontmatter is valid and complete
[ ] Description is clear and includes trigger terms
[ ] Tool access is appropriate (least privilege)
[ ] System prompt is specific and actionable
[ ] Quality gates are defined
[ ] Examples are provided
[ ] Integration points are documented
[ ] Agent tested with sample invocation
[ ] Documentation updated (if project agent)

Advanced: Agent Chaining

Agents can invoke other agents:

For implementation, delegate to @implementer:
@implementer please create the service class with proper dependency injection

Best Practice: Use chaining for clear separation of concerns (planning → implementation → testing).

Advanced: Dynamic Selection

Let Claude choose the right agent:

"I need help with Neo4j queries"
→ Claude autonomously selects @neo4j-expert based on description

Requirement: Agent descriptions must include trigger terms and use cases.

Integration with This Project

When creating agents for project-watch-mcp:

Align with Architecture: Reference Clean Architecture layers in system prompt
Follow Quality Standards: Integrate quality gates (pyright, vulture, pytest, ruff)
Use Project Patterns: Reference ServiceResult, fail-fast, configuration injection
Leverage Project Tools: Access to MCP tools, log_analyzer.py, check_all.sh
Reference Documentation: Link to ARCHITECTURE.md, ADRs, CLAUDE.md

Resources

Detailed Reference: references/reference.md
Utility Scripts:
- Agent Detector - Detect agent mentions in prompts
- Memory Creation - Create agent memory entries
- Validation - Validate agent files
Project Dispatch Guide: ../../docs/dispatch.md

Manage Claude Code Agents