@dawiddutoit/manage-agents

---
name: manage-agents
description: |
  Creates, modifies, and manages Claude Code subagents by writing agent files with YAML frontmatter,
  system prompts, and tool configurations. Use when you need to "create an agent", "modify an agent",
  "set up a specialist", "I need an agent for [task]", "agent to handle [domain]", or "configure
  agent tools". 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:

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](#instructions)
  - [Step 1: Analyze Requirements](#step-1-analyze-requirements) - Determine expertise domain, tool needs, and location
  - [Step 2: Create Agent File](#step-2-create-agent-file) - Choose project vs user location
  - [Step 3: Write Agent Configuration](#step-3-write-agent-configuration) - YAML frontmatter template
  - [Step 4: Configure Tool Access](#step-4-configure-tool-access) - Explicit tools, all tools, or no tools
  - [Step 5: Configure MCP Access](#step-5-configure-mcp-access) - Specific servers, all servers, or all resources
  - [Step 6: Select Model](#step-6-select-model) - Sonnet, Opus, or Haiku based on complexity
  - [Step 7: Write System Prompt](#step-7-write-system-prompt) - Clear, actionable, quality-focused instructions
  - [Step 8: Test the Agent](#step-8-test-the-agent) - Verify behavior and tool access
  - [Step 9: Document Integration](#step-9-document-integration) - Update dispatch.md and CLAUDE.md

- [Common Patterns](#common-patterns)
  - [Pattern 1: Domain Expert](#pattern-1-domain-expert) - Read-only analysis and recommendations
  - [Pattern 2: Code Generator](#pattern-2-code-generator) - Write access with quality gates
  - [Pattern 3: Orchestrator](#pattern-3-orchestrator) - Planning agent that delegates
  - [Pattern 4: Quality Guardian](#pattern-4-quality-guardian) - Read-only validation
  - [Pattern 5: Integration Specialist](#pattern-5-integration-specialist) - MCP-focused agent

### Supporting Resources

- [Configuration Reference](./references/reference.md) - Complete field documentation

### Utility Scripts

- [Agent Detection](./scripts/agent_detector_example.py) - Detect @agent-name patterns in prompts
- [Agent Memory Creation](./scripts/create_agent_memories_simple.py) - Create MCP memory entries for agents
- [Agent Validation](./scripts/validate_agent.py) - Validate agent file format and configuration

### Advanced Topics

- [Troubleshooting](#troubleshooting)
  - [Agent not appearing in autocomplete](#agent-not-appearing-in-autocomplete)
  - [Tool access denied](#tool-access-denied)
  - [Agent behavior incorrect](#agent-behavior-incorrect)
  - [Integration issues](#integration-issues)
- [Validation](#validation) - Validate agent files with script
- [Quality Checklist](#quality-checklist) - Pre-finalization checklist
- [Advanced: Agent Chaining](#advanced-agent-chaining) - Agent-to-agent delegation
- [Advanced: Dynamic Selection](#advanced-dynamic-selection) - Autonomous agent selection
- [Integration with This Project](#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:

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:
```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](./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](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](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](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:

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](./references/reference.md)
- **Utility Scripts**:
  - [Agent Detector](./scripts/agent_detector_example.py) - Detect agent mentions in prompts
  - [Memory Creation](./scripts/create_agent_memories_simple.py) - Create agent memory entries
  - [Validation](./scripts/validate_agent.py) - Validate agent files