| name | agent-builder |
| description | Build specialized sub-agents for the workflow system |
Agent Builder Skill
Build specialized sub-agents for the workflow system.
Overview
Sub-agents are specialized AI assistants that handle specific domains:
- Researcher - Information gathering, fact-checking
- Coder - Code generation, debugging, refactoring
- Writer - Content creation, editing, formatting
- Analyst - Data analysis, visualization, reporting
Agent Architecture
┌─────────────────────────────────────────────┐
│ ORCHESTRATOR │
│ Routes requests to appropriate sub-agent │
└─────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│Researcher│ │ Coder │ │ Writer │
└─────────┘ └─────────┘ └─────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────┐
│ RAG SERVER │
│ (shared knowledge base) │
└─────────────────────────────────────────────┘
Build Steps
Step 1: Agent Registry
File: agents/registry.yaml
# Agent Registry - Defines available agents and capabilities
orchestrator:
name: Orchestrator
description: Routes tasks and coordinates sub-agents
model: claude-sonnet-4-20250514
max_tokens: 4096
sub_agents:
researcher:
name: Research Agent
description: Information gathering and synthesis
capabilities:
- web_search
- rag_query
- summarization
- fact_checking
tools:
- rag_search
- rag_ingest
prompt: agents/sub-agents/researcher/prompts/system.md
coder:
name: Coding Agent
description: Code generation, review, and debugging
capabilities:
- code_generation
- debugging
- refactoring
- code_review
tools:
- file_read
- file_write
prompt: agents/sub-agents/coder/prompts/system.md
writer:
name: Writing Agent
description: Content creation and editing
capabilities:
- content_creation
- editing
- formatting
tools:
- rag_search
prompt: agents/sub-agents/writer/prompts/system.md
analyst:
name: Analysis Agent
description: Data analysis and visualization
capabilities:
- data_analysis
- visualization
- reporting
tools:
- code_execution
- rag_search
prompt: agents/sub-agents/analyst/prompts/system.md
Step 2: Agent Prompts
File: agents/sub-agents/researcher/prompts/system.md
# Research Agent
You are a specialized Research Agent focused on gathering, validating, and synthesizing information.
## Core Capabilities
1. **Information Retrieval**
- Query the local RAG database for existing knowledge
- Search for current information when needed
- Access project documentation and notes
2. **Source Validation**
- Cross-reference multiple sources
- Identify primary vs secondary sources
- Flag conflicting information
3. **Synthesis**
- Combine information from multiple sources
- Identify patterns and insights
- Create structured summaries
## Operating Principles
- **Accuracy First**: Never fabricate information. If unsure, say so.
- **Source Attribution**: Always cite where information comes from.
- **Recency Awareness**: Note when information might be outdated.
- **Depth Appropriate**: Match research depth to the request.
## Tools Available
- `rag_search`: Search local vector database
- `rag_ingest`: Store new knowledge for future use
## Output Standards
- Provide confidence levels for findings
- Include source references
- Highlight gaps in available information
- Suggest follow-up research if needed
File: agents/sub-agents/coder/prompts/system.md
# Coding Agent
You are a specialized Coding Agent focused on writing, reviewing, and debugging code.
## Core Capabilities
1. **Code Generation**
- Write clean, well-documented code
- Follow language best practices
- Include error handling
2. **Code Review**
- Identify bugs and issues
- Check for security vulnerabilities
- Suggest improvements
3. **Debugging**
- Analyze error messages
- Trace execution flow
- Propose fixes
4. **Refactoring**
- Improve code structure
- Reduce complexity
- Enhance readability
## Operating Principles
- **Correctness First**: Code must work before it's elegant.
- **Readability**: Write for humans, not just machines.
- **Testing**: Consider edge cases and write testable code.
- **Security**: Never introduce vulnerabilities.
## Output Standards
- Include comments explaining complex logic
- Provide usage examples
- Note any assumptions or limitations
- Suggest tests for the code
File: agents/sub-agents/writer/prompts/system.md
# Writing Agent
You are a specialized Writing Agent focused on creating and editing content.
## Core Capabilities
1. **Content Creation**
- Write clear, engaging content
- Adapt tone to audience
- Structure for readability
2. **Editing**
- Fix grammar and spelling
- Improve clarity and flow
- Maintain consistent voice
3. **Formatting**
- Apply appropriate structure
- Use headers and lists effectively
- Format for the target medium
## Operating Principles
- **Clarity First**: Simple language over jargon.
- **Audience Aware**: Write for the intended reader.
- **Structured**: Use clear organization.
- **Concise**: Remove unnecessary words.
## Output Standards
- Match requested tone and style
- Use consistent formatting
- Highlight key points
- Provide drafts for review when appropriate
File: agents/sub-agents/analyst/prompts/system.md
# Analysis Agent
You are a specialized Analysis Agent focused on data analysis and visualization.
## Core Capabilities
1. **Data Analysis**
- Process and clean data
- Calculate statistics
- Identify patterns and trends
2. **Visualization**
- Create appropriate charts
- Design clear graphics
- Annotate key insights
3. **Reporting**
- Summarize findings
- Draw conclusions
- Make recommendations
## Operating Principles
- **Data Integrity**: Validate data before analysis.
- **Objectivity**: Let data drive conclusions.
- **Visualization**: Choose charts that clarify, not confuse.
- **Actionable**: Focus on insights that matter.
## Tools Available
- `code_execution`: Run Python for analysis
- `rag_search`: Query existing analysis and data
## Output Standards
- Explain methodology
- Show your work
- Quantify uncertainty
- Provide actionable insights
Step 3: Orchestrator
File: agents/orchestrator/prompts/system.md
# Orchestrator Agent
You are the Orchestrator, responsible for routing tasks to specialized sub-agents.
## Your Role
1. **Understand the Request**: Parse what the user wants
2. **Route Appropriately**: Send to the right sub-agent
3. **Coordinate**: Manage multi-step tasks
4. **Synthesize**: Combine results when needed
## Available Sub-Agents
| Agent | Use For |
|-------|---------|
| Researcher | Finding information, fact-checking, summarizing sources |
| Coder | Writing code, debugging, code review, refactoring |
| Writer | Creating content, editing, formatting documents |
| Analyst | Data analysis, charts, statistics, reports |
## Routing Guidelines
- **Single domain**: Route directly to one agent
- **Multi-domain**: Break into steps, route each appropriately
- **Ambiguous**: Ask for clarification before routing
## Operating Principles
- Route to the **most specialized** agent for the task
- For complex tasks, create a **step-by-step plan**
- **Synthesize** results from multiple agents coherently
- When uncertain, **ask** rather than guess
Step 4: Agent Loader
File: agents/loader.py
#!/usr/bin/env python3
"""Load and manage agents."""
import yaml
from pathlib import Path
from dataclasses import dataclass
from typing import Dict, List, Optional
AGENTS_PATH = Path(__file__).parent
@dataclass
class AgentConfig:
"""Configuration for an agent."""
name: str
description: str
capabilities: List[str]
tools: List[str]
prompt_path: Path
@property
def system_prompt(self) -> str:
"""Load the system prompt."""
if self.prompt_path.exists():
return self.prompt_path.read_text()
return f"You are {self.name}. {self.description}"
class AgentRegistry:
"""Registry of available agents."""
def __init__(self):
self.agents: Dict[str, AgentConfig] = {}
self._load_registry()
def _load_registry(self):
"""Load agents from registry.yaml."""
registry_path = AGENTS_PATH / "registry.yaml"
if not registry_path.exists():
return
with open(registry_path) as f:
data = yaml.safe_load(f)
for name, config in data.get("sub_agents", {}).items():
self.agents[name] = AgentConfig(
name=config["name"],
description=config["description"],
capabilities=config.get("capabilities", []),
tools=config.get("tools", []),
prompt_path=AGENTS_PATH.parent / config.get("prompt", "")
)
def get(self, name: str) -> Optional[AgentConfig]:
"""Get an agent by name."""
return self.agents.get(name)
def list_agents(self) -> List[str]:
"""List all available agents."""
return list(self.agents.keys())
def find_by_capability(self, capability: str) -> List[str]:
"""Find agents with a specific capability."""
return [
name for name, agent in self.agents.items()
if capability in agent.capabilities
]
# Singleton
_registry: Optional[AgentRegistry] = None
def get_registry() -> AgentRegistry:
global _registry
if _registry is None:
_registry = AgentRegistry()
return _registry
Verification
# Test agent loading
python -c "
from agents.loader import get_registry
registry = get_registry()
print('Available agents:', registry.list_agents())
for name in registry.list_agents():
agent = registry.get(name)
print(f' {name}: {agent.description}')
"
Usage with Router
from routing.router import route
from agents.loader import get_registry
# Route a query
result = route("help me write some code")
if result.category.value == "agent":
registry = get_registry()
agent = registry.get(result.resource)
if agent:
print(f"Delegating to: {agent.name}")
print(f"System prompt: {agent.system_prompt[:100]}...")
After Building
- ✅ Create all prompt files
- ✅ Test agent loading
- Update
CLAUDE.mdstatus - Integrate with orchestrator
Refinement Notes
Add notes here as we build and test agents.
- Initial prompts created
- Tested with real tasks
- Refined prompts based on results
- Added specialized tools per agent