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
- •Agent not appearing in autocomplete
- •Tool access denied
- •Agent behavior incorrect
- •Integration issues
•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):

bash

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

User Agent (personal, not in git):

bash

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

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

Step 3: Write Agent Configuration

Use this template:

yaml

---
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)

yaml

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

Option 2: Allow All Tools

yaml

allow_all_tools: true

Option 3: No Tools (Analysis/planning only)

yaml

tools: []
allow_all_tools: false

Step 5: Configure MCP Access

Option 1: Specific MCP Servers (Recommended)

yaml

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

Option 2: All MCP Servers

yaml

allow_all_mcp_servers: true

Option 3: All MCP Resources (Use sparingly)

yaml

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:

bash

@agent-name please [task description]

Programmatic Testing:

Test agents from command line using CLI tools:

bash

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

•CLI testing tools documentation available in project's .claude/tools/agents/ directory

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 agent dispatch documentation if available
•Reference in project 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:

bash

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:

python

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

bash

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:

bash

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:

markdown

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:

markdown

"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

Manage Agents

Quick Start

Table of Contents

Core Sections

Supporting Resources

Utility Scripts

Advanced Topics

Instructions

Step 1: Analyze Requirements

Step 2: Create Agent File

Step 3: Write Agent Configuration

Step 4: Configure Tool Access

Step 5: Configure MCP Access

Step 6: Select Model

Step 7: Write System Prompt

Step 8: Test the Agent

Step 9: Document Integration

Configuration Reference

Examples

Working with Agent Detection

Creating Agent Core Memories

Common Patterns

Pattern 1: Domain Expert

Pattern 2: Code Generator

Pattern 3: Orchestrator

Pattern 4: Quality Guardian

Pattern 5: Integration Specialist

Troubleshooting

Validation

Quality Checklist

Advanced: Agent Chaining

Advanced: Dynamic Selection

Integration with This Project

Resources