Manage Agents

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:

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

Table of Contents

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

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

1. Specific: Define clear responsibilities and scope
2. Actionable: Include step-by-step workflows
3. Quality-Focused: Define standards and validation criteria
4. Integrated: Reference skills, tools, and project patterns
5. 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:

1. Align with Architecture: Reference Clean Architecture layers in system prompt
2. Follow Quality Standards: Integrate quality gates (pyright, vulture, pytest, ruff)
3. Use Project Patterns: Reference ServiceResult, fail-fast, configuration injection
4. Leverage Project Tools: Access to MCP tools, log_analyzer.py, check_all.sh
5. 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