| name | agent-builder |
| description | Create complete Claude Code agents for the Traycer enforcement framework. This skill should be used when creating new agents or updating existing agents. Creates all agent components including system prompt, hooks, skills, commands, scripts, and reference docs. Also updates coordination documents that list available agents. Based on Anthropic's official agent development best practices. |
Agent Builder
This skill guides the creation of complete, production-ready Claude Code agents following Anthropic's official best practices for context engineering, tool design, skills architecture, and enforcement through hooks.
When to Use
Use agent-builder when:
- Creating a new agent from scratch
- Major refactoring of an existing agent
- Converting a concept/requirements into a functioning agent
- Ensuring agent follows Anthropic best practices
- Need to create all agent components (prompt, hooks, skills, commands, etc.)
Agent Anatomy
A complete agent consists of:
Core Files
.claude/agents/<agent-name>.md # Single file with YAML frontmatter + system prompt
docs/agents/<agent-name>/
└── ref-docs/ # Agent-specific reference documents (optional)
└── *.md
docs/agents/shared-ref-docs/ # Shared reference documents (multi-agent)
└── *.md
Commands (Slash Commands)
.claude/commands/
├── <agent-command-1>.md # Explicit invocation commands
└── <agent-command-2>.md
Skills (Complex Workflows)
docs/skills/<skill-name>/
├── SKILL.md # Skill definition with frontmatter
├── scripts/ # Executable automation
│ └── *.py
└── references/ # Documentation loaded as needed
└── *.md
Hooks (Enforcement)
.claude/settings.json # Project hooks
~/.claude/settings.json # User hooks
Configuration in settings files:
{
"hooks": {
"PreToolUse": [...],
"PostToolUse": [...],
"UserPromptSubmit": [...],
"SessionStart": [...]
}
}
Agent-Specific Scripts
docs/agents/<agent-name>/scripts/
└── *.py # Utility scripts (not part of skills)
Coordination Updates
When creating new agents, update:
- Other agent prompts: If they reference available agents for delegation
- Shared ref docs: Agent coordination guides, addressing systems
- Team documentation: Agent capabilities matrix, workflow diagrams
Agent Creation Workflow
Phase 1: Requirements Analysis
Input: Agent requirements (purpose, responsibilities, constraints)
Actions:
- Define agent's scope and boundaries
- Identify integration points with other agents
- Determine tools and permissions needed
- Identify reusable patterns (→ Skills)
- Identify explicit operations (→ Commands)
- Identify enforcement rules (→ Hooks)
Output: Requirements document
Phase 2: Architecture Design
System Prompt Design:
- Define agent role and expertise
- Set behavior at "right altitude" (Anthropic principle)
- Not too prescriptive (hardcoded if-else)
- Not too vague (assumes shared context)
- Specific enough to guide, flexible for heuristics
- Organize with clear sections
- Start minimal, iterate based on failures
Tool Selection:
- Choose minimal viable set
- Each tool has clear, distinct purpose
- Avoid overlapping functionality
- Consider token efficiency
Skills vs Commands Decision:
| Use Skills For | Use Commands For |
|---|
| Complex multi-step workflows | Quick, frequently-used prompts |
| Multiple files/scripts needed | Single file sufficient |
| Automatic discovery desired | Explicit invocation preferred |
| Team standardization | Personal productivity |
Hooks Planning:
- Identify rules that MUST be enforced (not just prompted)
- Validation requirements (PreToolUse)
- Feedback mechanisms (PostToolUse)
- Context loading (SessionStart)
- Monitoring needs (logging, notifications)
Phase 3: Component Creation
3.1 Create Skills (Complex Workflows)
Call: Skill Creator skill
For each skill:
- Define skill purpose and trigger conditions
- Write SKILL.md with:
- Clear
description (what + when to use)
- Step-by-step instructions
- Examples
- Progressive disclosure (reference additional files as needed)
- Create scripts (if deterministic operations needed)
- Create reference docs (if extensive documentation needed)
- Add
allowed-tools frontmatter (if restricting tool access)
Example skill structure:
docs/skills/validation-protocol/
├── SKILL.md
├── scripts/
│ └── validate.py # Deterministic validation
└── references/
└── patterns.md # Loaded as needed
3.2 Create Commands (Slash Commands)
Call: Command Creator skill
For each command:
- Define command purpose
- Choose argument pattern (
$ARGUMENTS or $1, $2, $3)
- Write command file:
- Frontmatter (description, argument-hint, allowed-tools)
- Prompt with context (use
! for bash, @ for files)
- Test command invocation
Example command:
---
argument-hint: [file-path]
description: Validate code quality in specific file
tools:
---
Validate code quality in @$ARGUMENTS:
1. Check for code smells
2. Verify naming conventions
3. Assess complexity
4. Provide specific feedback
3.3 Configure Hooks (Enforcement)
Hook types to consider:
PreToolUse (Validation/Blocking):
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-code.py"
}]
}
]
}
}
PostToolUse (Feedback):
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-code.sh"
}]
}
]
}
}
UserPromptSubmit (Context Injection):
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/inject-context.py"
}]
}
]
}
}
SessionStart (Setup):
{
"hooks": {
"SessionStart": [
{
"matcher": "startup",
"hooks": [{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/load-agent-context.py"
}]
}
]
}
}
Hook script template (Python):
import json
import sys
try:
input_data = json.load(sys.stdin)
tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
sys.exit(0)
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
sys.exit(1)
3.4 Write System Prompt
File: .claude/agents/<agent-name>.md
Structure:
---
model: sonnet
description: <One-line agent purpose>
tools: [Tool1, Tool2, Tool3]
recommended-skills: [skill-name-1, skill-name-2]
---
**Project Context**: Read `.project-context.md` in the project root for project-specific information including <agent-relevant-items>.
# <Agent Name>
## Available Resources
**Shared Reference Docs** (`docs/agents/shared-ref-docs/`):
- [doc-name.md](docs/agents/shared-ref-docs/doc-name.md) - Description
- [another-doc.md](docs/agents/shared-ref-docs/another-doc.md) - Description
**Agent-Specific Resources**:
- Ref-docs: None # Or list specific files in docs/agents/<agent-name>/ref-docs/
- Scripts: None # Or list specific files
## Mission
[Clear statement of agent's purpose]
## Responsibilities
### ✅ THIS AGENT DOES
- [Specific responsibility 1]
- [Specific responsibility 2]
### ❌ THIS AGENT DOES NOT
- [What agent should not do]
- [Delegation pattern]
## Workflow
### Standard Process
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Coordination
**Delegates to**:
- Agent X: For [purpose]
- Agent Y: For [purpose]
**Receives from**:
- Agent A: [What they provide]
## Critical Constraints
- [Constraint 1]
- [Constraint 2]
## Decision-Making Protocol
**Act decisively (no permission)** when:
- [Scenario 1]
- [Scenario 2]
**Ask for permission** when:
- [Scenario 1]
- [Scenario 2]
Agent Frontmatter Field Constraints
name (Required)
Constraints:
- Maximum 64 characters
- Must contain only lowercase letters, numbers, and hyphens
- Cannot contain XML tags
- Cannot contain reserved words: "anthropic", "claude"
Examples: code-reviewer, processing-pdfs, analyzing-spreadsheets, managing-databases
description (Required)
Constraints:
- Must be non-empty
- Maximum 1024 characters
- Cannot contain XML tags
- Should describe what the agent does and when to use it
Best practice: Always write in third person. Include both what the agent does and specific triggers/contexts for when to use it.
Good example:
description: Expert code reviewer. Use proactively after code changes to catch bugs, suggest improvements, and ensure code quality standards.
tools (Optional)
Behavior:
- If omitted: inherits all tools from the main thread (default)
- If specified: comma-separated list of specific tools
Format: tool1, tool2, tool3
Example:
tools: Read, Grep, Glob, Bash
Common tool patterns:
- Research:
Read, Glob, Grep, WebSearch, WebFetch, mcp__ref__*, mcp__exasearch__*
- Backend Implementation:
Read, Write, Edit, Bash, Glob, Grep
- Frontend Implementation:
Read, Write, Edit, Bash, Glob, Grep
- DevOps:
Read, Write, Edit, Bash, Glob, Grep
- QA/Testing:
Read, Bash, Glob, Grep
- Tracking:
Read, Write, Bash, mcp__linear-server__*, mcp__github__*
model (Optional)
Allowed values:
sonnet - Claude 3.5 Sonnet (default for sub-agents)opus - Claude 3 Opushaiku - Claude 3 Haiku'inherit' - Use the same model as the main conversation
Default: If omitted, uses sonnet
Example:
model: sonnet
Complete Valid Example
---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes to catch bugs, suggest improvements, and ensure code quality standards.
tools: Read, Grep, Glob, Bash
model: sonnet
---
Invalid Examples
❌ Wrong: Name with uppercase
name: Code-Reviewer
❌ Wrong: Reserved word
name: claude-reviewer
❌ Wrong: Missing description
---
name: code-reviewer
tools: Read, Bash
---
❌ Wrong: Extra forbidden fields
---
name: code-reviewer
description: Reviews code
domain: Development
version: 1.0
---
❌ Wrong: Tools without key
---
name: code-reviewer
description: Reviews code
Read, Bash, Grep
---
Anthropic principles to follow:
- Right altitude: Specific guidance without hardcoded logic
- Clear sections: Use headers/XML tags for organization
- Minimal to start: Add based on failure modes
- Examples over rules: Show canonical examples
- Avoid assumptions: Make implicit context explicit
3.5 Configure MCP Tools (if needed)
When to use MCPs:
- Agent needs external service integration (Linear, GitHub, Supabase)
- Third-party APIs required for agent function
- Specialized capabilities (web search, documentation lookup, code review)
Available MCPs:
Project Management & Development:
- Linear (
mcp__linear-server__*) - Issue tracking, project management
- GitHub (
mcp__github__*) - Repository operations, PRs, issues, workflows
- Code Reviewer (
mcp__claude-reviewer__*) - Automated code review sessions
Data & Infrastructure:
- Supabase (
mcp__supabase__*) - Database, auth, edge functions, migrations
Research & Search:
- Exa Search (
mcp__exasearch__*) - Web search, company research, deep researcher
- Ref (
mcp__ref__*) - Documentation search and retrieval
- Perplexity (
mcp__perplexity-ask__*) - AI-powered research and Q&A
Problem Solving:
- Sequential Thinking (
mcp__BetterST__*) - Complex multi-step reasoning
MCP Server Configuration (handled by Claude Code settings):
MCPs are configured in ~/.claude/settings.json or project .claude/settings.json. The Traycer framework assumes MCPs are already configured by the user. Agents don't configure MCP servers—they just declare which MCP tools they use.
In agent's YAML frontmatter, specify MCP tools needed:
---
model: sonnet
description: Agent that manages Linear issues and GitHub PRs
tools:
- Read
- Write
- Edit
- Bash
- mcp__linear-server__list_issues
- mcp__linear-server__update_issue
- mcp__linear-server__create_issue
- mcp__github__create_pull_request
- mcp__github__list_pull_requests
- mcp__github__get_file_contents
recommended-skills: [skill-name-1, skill-name-2]
---
In system prompt, document MCP tool usage:
Add a section explaining when and how to use each MCP tool:
## MCP Tools
### Linear Integration
**Issue Management**:
- `mcp__linear-server__list_issues` - Query issues with filters (team, assignee, state, labels)
- Always filter by team to avoid cross-contamination
- Example: `list_issues(team: "LAW", assignee: "me", state: "open")`
- `mcp__linear-server__update_issue` - Modify issue status, assignee, labels, description
- Use for tracking work progress
- Example: Mark issue as "In Progress" when starting work
- `mcp__linear-server__create_issue` - Create new issues for tracking work
- Include team, title, description, labels
- Link to parent issue if part of work block
**Critical constraints**:
- ALWAYS filter by team/project to prevent seeing wrong issues
- Read project-context.md for team/project IDs
- Never hardcode issue IDs in agent prompts
### GitHub Integration
**Repository Operations**:
- `mcp__github__get_file_contents` - Fetch file contents from repos
- `mcp__github__create_pull_request` - Create PRs programmatically
- `mcp__github__list_pull_requests` - Query PRs by state, filters
**Usage patterns**:
- Tracking agents use for PR creation after QA approval
- Action agents may read from repos for research
- Never push directly to main—always via PR
[Continue for other MCPs as needed...]
Security & Best Practices:
-
API Keys: Never reference API keys in agent prompts or scripts
- MCPs are configured by user with env vars
- Agents assume MCPs are available if listed in YAML frontmatter
-
Tool Discovery: List only tools agent actually needs
- Don't use
mcp__linear-server__* wildcard in production agent frontmatter (wildcards grant excessive permissions - use explicit tool listing for security and clarity)
- Explicitly list each tool for clarity
-
Documentation: Explain tool usage constraints in system prompt
- When to use each tool
- Common parameters and patterns
- Error handling approaches
-
Testing: Verify MCP tools work before deploying agent
- Test with real API calls during evaluation phase
- Handle MCP failures gracefully (tool may not be configured)
3.7 Create Agent-Specific Reference Docs
Location: docs/agents/<agent-name>/ref-docs/
Common ref docs:
workflow-guide.md - Detailed workflow stepsdecision-matrix.md - When to choose different approachesexamples.md - Canonical examplestroubleshooting.md - Common issues and solutions
Keep concise: If doc is for multiple agents, move to shared-ref-docs/
3.7 Create Agent-Specific Scripts
Location: docs/agents/<agent-name>/scripts/
For scripts that:
- Are agent-specific (not reusable across agents)
- Don't fit within a skill
- Provide utility functions for agent operations
Example: update-dashboard.py for tracking agent's operations
Phase 4: Integration & Updates
4.1 Update Coordination Documents
Files to update:
- Other agent prompts (if they delegate to this agent):
## Available Agents
- **New Agent Name** (@new-agent-name): [Purpose]
- Use for: [When to delegate]
- Capabilities: [What it can do]
- Shared coordination guides:
docs/agents/shared-ref-docs/agent-addressing-system.mddocs/agents/shared-ref-docs/traycer-coordination-guide.md
- Project context:
.project-context.md - Update "Active Agents" section
4.2 Register Agent Alias (if applicable)
If agent has an @mention alias, document in:
- Coordination guides
- Agent's own prompt (how to invoke)
- Other agents that might delegate to it
Phase 5: Testing & Iteration
5.1 Create Evaluation Tasks
Real-world tasks that test:
- Core responsibilities
- Tool usage
- Error handling
- Coordination with other agents
Good evaluation tasks:
- Require multiple steps
- Test decision-making
- Cover edge cases
- Reflect actual use cases
Example:
Task: Review PR #123 for security issues and code quality
Expected:
- Load PR diff
- Run security validation
- Check code standards
- Provide structured feedback
- Delegate fixes to Backend/Frontend/DevOps agents if needed
5.2 Run Evaluations
Process:
- Execute agent on evaluation tasks
- Observe failures and confusion points
- Read agent's reasoning (use extended thinking)
- Analyze tool calls and responses
- Identify areas for improvement
Metrics to track:
- Task completion rate
- Tool call efficiency
- Token consumption
- Error frequency
- Time to completion
5.3 Iterate with Claude
Collaborate with Claude to:
- Analyze evaluation results
- Identify prompt improvements
- Refine tool descriptions
- Optimize hook configurations
- Improve skill instructions
Use held-out test sets to prevent overfitting
Phase 6: Documentation & Handoff
6.1 Create Agent README
File: docs/agents/<agent-name>/README.md
# <Agent Name>
## Purpose
[What this agent does]
## When to Use
[Scenarios where you'd invoke this agent]
## Quick Start
### Prerequisites
- [Any setup required]
### Invocation
```text
@agent-name [task description]
Capabilities
- [Capability 1]
- [Capability 2]
Examples
Example 1: [Use Case]
User: [Request]
Agent: [Response pattern]
Configuration
Skills Used
Commands Available
Hooks Enforced
- PreToolUse: [What's validated]
- PostToolUse: [What feedback is provided]
Coordination
Delegates To
Receives From
- Agent Y: [What work items]
Troubleshooting
Issue: [Common problem]
Symptom: [What you see]
Solution: [How to fix]
#### 6.2 Update Team Documentation
**Agent capabilities matrix**:
```markdown
| Agent | Purpose | Skills | Commands | Coordinates With |
|-------|---------|--------|----------|------------------|
| New Agent | [Purpose] | skill-1, skill-2 | /cmd-1, /cmd-2 | Agent-X, Agent-Y |
Workflow diagrams: Update if agent changes workflows
Phase 7: Deployment
Goal: Deploy newly created agent to .claude/agents/ and verify availability.
7.1 Deploy Agent File
Action: Copy agent file to deployment location.
Implementation:
SOURCE_FILE="docs/agents/<agent-name>/<agent-name>-agent.md"
TARGET_FILE=".claude/agents/<agent-name>-agent.md"
if [[ ! -f "$SOURCE_FILE" ]]; then
echo "❌ Source file not found: $SOURCE_FILE"
exit 1
fi
mkdir -p ".claude/agents"
cp -p "$SOURCE_FILE" "$TARGET_FILE"
Verification:
- File exists at
.claude/agents/<agent-name>-agent.md
- File permissions preserved (should be readable)
- File content matches source (use
cmp -s to verify)
if cmp -s "$SOURCE_FILE" "$TARGET_FILE"; then
echo "✅ Agent file deployed successfully"
else
echo "❌ Content mismatch after deployment"
exit 1
fi
7.2 Update Documentation Registry
Action: Update docs/agents/README.md with new agent entry.
If README.md doesn't exist, create with template:
# Traycer Enforcement Framework - Agents
This directory contains agent system prompts and supporting resources for the Traycer Enforcement Framework.
## Deployed Agents
| Agent | File | Purpose | Status |
|-------|------|---------|--------|
| Frontend Agent | `frontend-agent.md` | Implements UI/UX components and client-side logic | ✅ Deployed |
| Backend Agent | `backend-agent.md` | Implements API endpoints and database operations | ✅ Deployed |
| DevOps Agent | `devops-agent.md` | Manages infrastructure and deployment operations | ✅ Deployed |
## Agent Directory Structure
Each agent has a directory at `docs/agents/<agent-name>/` containing:
- `<agent-name>-agent.md` - System prompt with YAML frontmatter
- `ref-docs/` - Agent-specific reference documents (optional)
- `scripts/` - Agent-specific utility scripts (optional)
- `README.md` - Agent documentation and usage guide
## Shared Resources
- `shared-ref-docs/` - Reference documents shared across multiple agents
- `documentation-validator/` - Agent for validating documentation quality
## Adding New Agents
New agents are created using the `agent-builder` skill, which handles:
1. Requirements analysis
2. Architecture design
3. Component creation (prompts, skills, commands, hooks)
4. Integration and testing
5. Documentation
6. Deployment to `.claude/agents/`
If README.md exists, append new row:
- Extract agent name from filename (e.g.,
researcher-agent.md → "Researcher Agent")
- Extract purpose from YAML frontmatter
description field
- Insert row in table, maintaining alphabetical order by agent name
Sort order: Alphabetical by agent name for maintainability.
Example:
| Research Agent | `researcher-agent.md` | Gathers information and provides technical research | ✅ Deployed |
7.3 Run Verification
Action: Invoke bootstrap script verification for the newly deployed agent.
Command:
cd "$PROJECT_ROOT"
bash scripts/tef_bootstrap.sh --dry-run --local 2>&1 | grep -A 5 "Component Count Verification"
Expected Output:
=== Component Count Verification ===
- Agents: 13 # Should increment by 1 from previous count
- Skills: <count>
- Commands: <count>
- Hooks: <count>
Verification Checklist:
7.4 Confirm Deployment
Action: Report deployment success with summary.
Output Format:
## Phase 7: Deployment - Complete ✅
**Agent Deployed**: <agent-name>-agent.md
**Deployment Location**: .claude/agents/<agent-name>-agent.md
**Documentation Updated**: docs/agents/README.md
**Verification Results**:
- ✅ Agent file copied successfully
- ✅ Permissions preserved (readable)
- ✅ Content matches source (cmp verified)
- ✅ Documentation registry updated
- ✅ Bootstrap verification passed
- ✅ Agent count: <new count>
**Next Steps**:
1. Restart Claude Code to load new agent
2. Test agent with: `@<agent-name> <test task>`
3. Review agent behavior and iterate if needed
7.5 Optional: Skip Deployment
Flag: --no-deploy
Behavior: If --no-deploy flag provided to agent-builder skill, skip Phase 7 entirely.
Use Cases:
- Creating agent for different project (not current repo)
- Testing agent architecture without deployment
- Manual deployment preferred
- Deployment to custom location (not
.claude/)
Implementation:
Add to skill frontmatter:
argument-hint: [agent-requirements] [--no-deploy]
Parse arguments for --no-deploy flag:
- If flag present: Execute Phases 1-6 normally, skip Phase 7 (show skip message)
- If flag absent: Execute all Phases 1-7
Skip Message (when --no-deploy provided):
## Phase 7: Deployment - Skipped ⏭️
**Reason**: --no-deploy flag provided
**Agent Created**: docs/agents/<agent-name>/<agent-name>-agent.md
**Manual Deployment**:
To deploy this agent manually:
1. Copy agent file: `cp docs/agents/<agent-name>/<agent-name>-agent.md .claude/agents/`
2. Update docs/agents/README.md with new agent entry
3. Verify: `bash scripts/tef_bootstrap.sh --dry-run --local`
4. Restart Claude Code to load agent
Phase 8: Audit Mode (Validation)
Purpose: Validate existing agents for compliance with TEF standards
When to Use: After agent creation/modification, before deployment, or in CI/CD pipelines
Command Pattern:
/agent-builder --audit [--agent <name>] [--format json|markdown] [--verbose]
Flags:
--audit: Enable audit mode (skips creation workflow)--agent <name>: Audit single agent (default: all agents in .claude/agents/)--format json|markdown: Report output format (default: markdown)--verbose: Show full compliance details for each check
8.1: Audit Workflow
Steps:
- Read agent files from
.claude/agents/
- Run compliance checks (see 8.2)
- Generate report (markdown or JSON)
- Provide remediation guidance for failures
- Exit with status code (0 = all pass, 1 = warnings, 2 = failures)
Example Usage:
/agent-builder --audit
/agent-builder --audit --agent backend-agent
/agent-builder --audit --format json > audit-report.json
8.2: Compliance Checks
Agent-builder audit mode validates 5 compliance criteria:
Check 1: No Duplicate YAML Frontmatter (CRITICAL)
Criteria: Agent file must have exactly ONE YAML frontmatter block
Implementation:
- Read agent file line-by-line
- Count occurrences of
--- (YAML delimiter) in first 20 lines
- PASS: Exactly 2 occurrences (opening line 1, closing line ~6)
- FAIL: More than 2 occurrences (duplicate blocks detected)
Example:
❌ FAIL: backend-agent.md - Duplicate YAML frontmatter detected (4 delimiters found, expected 2)
✅ PASS: frontend-agent.md - Single YAML frontmatter block (2 delimiters)
Remediation: Remove duplicate YAML blocks, merge fields into first block if needed
Check 2: YAML Frontmatter Completeness (REQUIRED)
Criteria: Agent YAML frontmatter must contain all required fields
Required Fields:
model: <model-id> (e.g., sonnet)description: <string> (one-line agent description)tools: [...] (array of tool names, can be empty)recommended-skills: [...] (array of skill names, can be empty)
Implementation:
- Parse YAML frontmatter (first block only, ignore duplicates)
- Verify presence of each required field
- PASS: All 4 fields present
- WARN: Optional fields found in duplicate block (e.g.,
friendly_name)
- FAIL: Missing any required field
Example:
✅ PASS: backend-agent.md - All required YAML fields present
❌ FAIL: example-agent.md - Missing required field: allowed-tools
⚠️ WARN: devops-agent.md - Optional field 'friendly_name' in duplicate block
Remediation: Add missing fields to YAML frontmatter
Check 3: Project Context Reference (REQUIRED)
Criteria: Agent prompt must reference .project-context.md
Implementation:
- Search agent file for pattern:
**Project Context**:.*\.project-context\.md
- PASS: Pattern found anywhere in file
- FAIL: Pattern not found
Example:
✅ PASS: researcher-agent.md - Project context reference found
❌ FAIL: example-agent.md - No project context reference found
Remediation: Add project context snippet to agent prompt (see agent-builder Phase 3.1 template)
Check 4: Valid Ref-Docs Path References (OPTIONAL)
Criteria: If agent references ref-docs, paths must exist
Implementation:
- Extract ref-doc references from agent file (pattern:
docs/agents/<agent>/ref-docs/*.md or docs/agents/<agent>-agent/ref-docs/*.md)
- For each reference, verify file exists on disk
- Check if agent has ref-docs directory (either
docs/agents/<agent>/ref-docs/ or docs/agents/<agent>-agent/ref-docs/)
- PASS: All referenced paths exist OR no ref-doc references found
- WARN: Agent has
ref-docs/ directory but no files in it
- FAIL: Agent references non-existent ref-doc file
Example:
✅ PASS: documentation-validator.md - All ref-docs exist
⚠️ WARN: action-agent.md - ref-docs directory empty (docs/agents/action-agent/ref-docs/)
❌ FAIL: example-agent.md - Referenced ref-doc not found: docs/agents/example/ref-docs/missing.md
Remediation: Create missing ref-docs or remove references from agent prompt
Check 5: Valid Scripts Path References (OPTIONAL)
Criteria: If agent references scripts, paths must exist and be executable
Implementation:
- Extract script references from agent file (pattern:
docs/agents/<agent>/scripts/*.sh or similar)
- For each reference, verify:
- File exists on disk
- File is executable (
-x permission)
- PASS: All referenced scripts exist and are executable OR no script references found
- WARN: Script exists but is not executable (missing
chmod +x)
- FAIL: Agent references non-existent script
Example:
✅ PASS: documentation-validator.md - All scripts exist and executable
⚠️ WARN: example-agent.md - Script not executable: docs/agents/example/scripts/validate.sh
❌ FAIL: example-agent.md - Referenced script not found: docs/agents/example/scripts/missing.sh
Remediation: Create missing scripts or fix permissions (chmod +x script.sh)
8.3: Report Format
Markdown Report (Default)
# Agent Audit Report
**Date**: 2025-11-03
**Audited Agents**: 12
**Overall Status**: ⚠️ WARNINGS (5 agents have issues)
---
## Summary
| Status | Count | Agents |
|--------|-------|--------|
| ✅ PASS | 8 | frontend-agent, backend-agent, devops-agent, qa-agent, researcher-agent, planning-agent, tracking-agent, browser-agent |
| ⚠️ WARN | 0 | (none) |
| ❌ FAIL | 4 | debug-agent, seo-agent, traycer-agent, software-architect |
---
## Detailed Results
### ❌ FAIL: backend-agent.md
**Issues**:
- ❌ Check 1: Duplicate YAML frontmatter (4 delimiters, expected 2)
**Remediation**:
Remove duplicate YAML block (lines 8-11). Merge `delegated_by` and `friendly_name` into first block if needed.
---
### ✅ PASS: backend-agent.md
**Status**: All checks passed
- ✅ Check 1: Single YAML frontmatter block
- ✅ Check 2: All required fields present (model, description, allowed-tools, recommended-skills)
- ✅ Check 3: Project context reference found
- ✅ Check 4: All ref-docs valid
- ✅ Check 5: No script references
---
[... repeat for all agents ...]
JSON Report (For CI/CD)
{
"audit_date": "2025-11-03",
"total_agents": 12,
"overall_status": "WARNINGS",
"summary": {
"pass": 7,
"warn": 0,
"fail": 5
},
"agents": [
{
"filename": "backend-agent.md",
"status": "FAIL",
"checks": {
"no_duplicate_yaml": {
"status": "FAIL",
"message": "Duplicate YAML frontmatter (4 delimiters, expected 2)",
"severity": "CRITICAL",
"line_numbers": [1, 6, 8, 11]
},
"yaml_completeness": {
"status": "PASS",
"message": "All required fields present"
},
"project_context": {
"status": "PASS",
"message": "Project context reference found"
},
"ref_docs_valid": {
"status": "WARN",
"message": "ref-docs directory exists but is empty",
"path": "docs/agents/backend-agent/ref-docs/"
},
"scripts_valid": {
"status": "PASS",
"message": "No script references found"
}
},
"remediation": "Remove duplicate YAML block (lines 8-11)"
}
]
}
8.4: Pass/Fail/Warning Criteria
FAIL Criteria (blocks agent deployment, exit code 2):
- Duplicate YAML frontmatter detected (Check 1)
- Missing required YAML field (Check 2)
- No project context reference found (Check 3)
- Agent references non-existent ref-doc or script file (Checks 4-5)
WARN Criteria (informational, exit code 1):
- Agent has ref-docs directory but it's empty (Check 4)
- Script exists but is not executable (Check 5)
- Optional YAML fields in duplicate block (Check 2)
PASS Criteria (exit code 0):
- Single YAML frontmatter block (Check 1)
- All required fields present (Check 2)
- Project context reference exists (Check 3)
- All referenced paths exist and are valid (Checks 4-5) OR no references made
8.5: CI/CD Integration
GitHub Actions Example:
name: Agent Compliance Audit
on:
pull_request:
paths:
- '.claude/agents/**'
- 'docs/agents/**'
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run agent audit
run: |
claude-code run "/agent-builder --audit --format json" > audit-report.json
- name: Check audit status
run: |
status=$(jq -r '.overall_status' audit-report.json)
if [ "$status" == "FAIL" ]; then
echo "❌ Agent audit failed"
exit 1
elif [ "$status" == "WARNINGS" ]; then
echo "⚠️ Agent audit has warnings"
exit 0
else
echo "✅ Agent audit passed"
exit 0
fi
- name: Post audit report as comment
uses: actions/github-script@v6
with:
script: |
const fs = require('fs');
const report = JSON.parse(fs.readFileSync('audit-report.json', 'utf8'));
// Format and post as PR comment
8.6: Known Limitations
Deferred Check:
- Check 6 (Filename-Directory Matching): Not implemented due to mixed naming patterns
- Legacy agents use old directories (e.g.,
backend/, frontend/)
- Canonical agents use
*-agent/ directories (e.g., backend-agent/, frontend-agent/)
- Will be enabled once legacy migration is complete
Future Enhancements:
- Auto-remediation (
--fix flag to auto-repair common issues)
- Ref-docs linting (validate Markdown syntax, check internal links)
- Code example validation (verify bash/Python snippets are syntactically valid)
Best Practices (Anthropic Guidance)
1. Context Engineering
Treat context as finite resource:
- Every token depletes "attention budget"
- Good context = smallest set of high-signal tokens
- Progressive disclosure for skills
System prompt altitude:
- Not too prescriptive (hardcoded logic)
- Not too vague (assumes context)
- Specific guidance + flexible heuristics
Just-in-time retrieval:
- Load data dynamically using tools
- Maintain lightweight identifiers (paths, IDs)
- Leverage metadata (folders, timestamps)
2. Tool Design
Choose tools intentionally:
- More tools ≠ better outcomes
- Each tool: clear, distinct purpose
- Consolidate related operations
- If human can't pick tool, agent can't either
Return meaningful context:
- Prioritize relevance over flexibility
- Natural language > cryptic IDs
- Token-efficient responses
- Consider
response_format enum
Excellent descriptions:
- Explain like to new hire
- Make implicit context explicit
- Unambiguous parameters
- Small refinements = big improvements
3. Skills Architecture
Keep skills focused:
- One capability per skill
- "PDF form filling" not "Document processing"
Clear descriptions:
- What skill does + when to use it
- Include specific triggers
- Example: "Use when working with Excel files, .xlsx format"
Progressive disclosure:
- Metadata (always loaded)
- SKILL.md body (when triggered)
- Resources (as needed)
4. Hooks for Enforcement
Use hooks for deterministic control:
- Don't rely on prompting for critical rules
- Hooks always execute vs agent choice
Hook event selection:
- PreToolUse: Validation, blocking
- PostToolUse: Feedback, formatting
- UserPromptSubmit: Context injection, validation
- SessionStart: Setup, environment loading
Security:
- Hooks run with your credentials
- Review scripts before registering
- Quote shell variables:
"$VAR"
- Block path traversal
- Use absolute paths
5. Production Checklist
Before deploying agent:
Phase 1-6 Verification:
Phase 7 Deployment Verification:
Phase 8: Audit - Run compliance audit
Integration with Other Skills
Agent Builder orchestrates:
Agent Requirements
↓
Agent Builder Skill
├→ [Reusable patterns identified]
│ └→ Calls: Skill Creator Skill
│ └→ Creates: docs/skills/<skill>/
│
├→ [Explicit operations identified]
│ └→ Calls: Command Creator Skill
│ └→ Creates: .claude/commands/<cmd>.md
│
└→ [Assembles complete agent]
├→ Creates: .claude/agents/<name>.md (single file with YAML frontmatter)
├→ Creates: docs/agents/<name>/ref-docs/ (if needed)
├→ Configures: .claude/settings.json (hooks)
└→ Updates: Coordination docs
What Agent Builder decides:
- System prompt (agent-specific logic)
- Skills (reusable workflows)
- Commands (explicit prompts)
- Hooks (enforcement rules)
- Tools (capabilities needed)
- Ref docs (supporting documentation)
Common Patterns
Pattern 1: Validation Agent
Components:
- System prompt: Define validation rules and process
- Skills:
validation-protocol (multi-step validation)
- Commands:
/validate-file, /validate-pr
- Hooks:
- PreToolUse: Block invalid operations
- PostToolUse: Auto-format after edits
- Tools: Read, Grep, Glob (read-only)
Example: QA Agent
Pattern 2: Implementation Agent
Components:
- System prompt: Execute implementation work for specific domain (frontend/backend/devops)
- Skills: Domain-specific implementation patterns
- Commands: Domain-specific commands (e.g.,
/deploy, /build, /api-test)
- Hooks:
- PreToolUse: Validate domain boundaries (backend can't touch frontend/*)
- SessionStart: Load project context
- Tools: Read, Write, Edit, Bash, Glob, Grep (domain-scoped)
Examples: Backend Agent, Frontend Agent, DevOps Agent
Pattern 3: Execution Agent
Components:
- System prompt: Execute instructions verbatim
- Skills: Minimal (focused execution)
- Commands:
/git-commit, /linear-update
- Hooks:
- SessionStart: Load environment
- PreToolUse: Validate parameters
- Tools: Full access (Write, Edit, Bash, Linear MCP)
Example: Tracking Agent
Pattern 4: Coordination Agent
Components:
- System prompt: Delegate to specialists, never execute
- Skills:
delegation-protocol, work-breakdown
- Commands:
/delegate, /status
- Hooks:
- UserPromptSubmit: Parse work requests
- Stop: Update progress tracking
- Tools: Task (subagents), Linear (read-only)
Example: Traycer
Pattern 5: Research Agent
Components:
- System prompt: Gather evidence, analyze options
- Skills:
research-methodology, citation-standards
- Commands:
/deep-research, /compare-options
- Hooks:
- SessionStart: Load research context
- PostToolUse: Log sources consulted
- Tools: WebSearch, WebFetch, Read, MCP tools
Pattern 6: Integration Agent (with MCPs)
Components:
- System prompt: Document MCP tool usage, constraints, error handling
- Skills:
api-integration-protocol, error-recovery
- Commands:
/sync-linear, /create-pr, /search-docs
- Hooks:
- PreToolUse: Validate MCP parameters (team filters, required fields)
- PostToolUse: Log API calls for debugging
- SessionStart: Verify MCP availability
- Tools: MCP tools (Linear, GitHub, Supabase, etc.) + Read, Grep
- Config: Explicitly list MCP tools needed
Example Agents:
- Tracking Agent: Uses Linear MCP for issue updates, GitHub MCP for PRs
- Research Agent: Uses Exa Search MCP for web research, Ref MCP for docs
- Database Agent: Uses Supabase MCP for migrations and queries
Critical patterns:
- Always filter Linear queries by team/project
- Handle MCP unavailability gracefully
- Document required MCP configuration in agent README
- Test with real APIs during evaluation phase
Troubleshooting Agent Creation
Issue: Agent ignores instructions
Symptom: Agent doesn't follow system prompt
Causes:
- Prompt too vague (lacks concrete signals)
- Prompt too prescriptive (hardcoded logic)
- Missing examples
Solutions:
- Add canonical examples
- Increase specificity without hardcoding
- Use clear section headers
- Test with edge cases
Issue: Agent calls wrong tools
Symptom: Agent uses inappropriate tools
Causes:
- Overlapping tool functionality
- Unclear tool descriptions
- Tool names ambiguous
Solutions:
- Consolidate overlapping tools
- Improve tool descriptions (explain to new hire)
- Use namespacing (prefixes/suffixes)
- Show examples in descriptions
Issue: Agent runs out of context
Symptom: Context window fills up
Causes:
- Verbose tool responses
- Loading unnecessary skills
- No progressive disclosure
Solutions:
- Implement token-efficient tools
- Use progressive disclosure in skills
- Add pagination/filtering to tools
- Configure auto-compaction
- Use structured note-taking
Issue: Hooks not enforcing rules
Symptom: Agent bypasses validation
Causes:
- Hooks not registered correctly
- Matcher pattern wrong
- Hook script errors
Solutions:
- Check hooks in settings.json
- Test matcher patterns
- Run
claude --debug to see hook execution
- Verify script permissions (
chmod +x)
- Test hook script independently
Issue: Skills not triggering
Symptom: Agent doesn't use skill
Causes:
- Description too generic
- YAML syntax errors
- Skill in wrong location
Solutions:
- Make description specific (what + when)
- Validate YAML frontmatter
- Check file location (.claude/skills/ or ~/.claude/skills/)
- Test with explicit mention of skill purpose
Quick Reference
Creating agents:
- Analyze requirements
- Design architecture (prompt, tools, skills, commands, hooks)
- Create components (call sub-skills as needed)
- Write system prompt with YAML frontmatter
- Set up hooks
- Create documentation
- Run evaluations
- Iterate
- Update coordination docs
File locations:
- Agent file:
.claude/agents/<name>.md (single file with frontmatter)
- Agent ref docs:
docs/agents/<name>/ref-docs/ (if agent-specific)
- Shared ref docs:
docs/agents/shared-ref-docs/ (for multi-agent resources)
- Skills:
docs/skills/<skill-name>/
- Commands:
.claude/commands/<cmd>.md
- Hooks:
.claude/settings.json
Anthropic principles:
- Context is finite - use wisely
- Right altitude in prompts
- Tools: clear, distinct, consolidated
- Skills: focused, clear descriptions, progressive disclosure
- Hooks: deterministic enforcement
- Evaluate with real-world tasks
Resources
For detailed best practices, see references/agent-development-guide.md:
- Complete agent architecture examples
- Evaluation methodology
- Hook patterns and examples
- Skill vs command decision trees
- Common anti-patterns to avoid
