agent-builder

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:

1. Creating a new agent from scratch
2. Major refactoring of an existing agent
3. Converting a concept/requirements into a functioning agent
4. Ensuring agent follows Anthropic best practices
5. 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:

1. Define agent's scope and boundaries
2. Identify integration points with other agents
3. Determine tools and permissions needed
4. Identify reusable patterns (→ Skills)
5. Identify explicit operations (→ Commands)
6. 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:

1. Define skill purpose and trigger conditions
2. Write SKILL.md with:
   • Clear description (what + when to use)
   • Step-by-step instructions
   • Examples
   • Progressive disclosure (reference additional files as needed)
3. Create scripts (if deterministic operations needed)
4. Create reference docs (if extensive documentation needed)
5. 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:

1. Define command purpose
2. Choose argument pattern ($ARGUMENTS or $1, $2, $3)
3. Write command file:
   • Frontmatter (description, argument-hint, allowed-tools)
   • Prompt with context (use ! for bash, @ for files)
4. 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):

#!/usr/bin/env python3
import json
import sys

try:
    input_data = json.load(sys.stdin)

    # Access hook data
    tool_name = input_data.get("tool_name", "")
    tool_input = input_data.get("tool_input", {})

    # Perform validation/processing
    # ...

    # Return result
    # Exit 0: Success
    # Exit 2: Block with stderr fed to Claude

    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 Opus
• haiku - 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  # Must be lowercase-with-hyphens

❌ Wrong: Reserved word

name: claude-reviewer  # Cannot contain "claude"

❌ Wrong: Missing description

---
name: code-reviewer
tools: Read, Bash
---

❌ Wrong: Extra forbidden fields

---
name: code-reviewer
description: Reviews code
domain: Development  # Forbidden field
version: 1.0         # Forbidden field
---

❌ Wrong: Tools without key

---
name: code-reviewer
description: Reviews code
Read, Bash, Grep  # Missing "tools:" key
---

Anthropic principles to follow:

1. Right altitude: Specific guidance without hardcoded logic
2. Clear sections: Use headers/XML tags for organization
3. Minimal to start: Add based on failure modes
4. Examples over rules: Show canonical examples
5. 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
  # Linear MCP tools
  - mcp__linear-server__list_issues
  - mcp__linear-server__update_issue
  - mcp__linear-server__create_issue
  # GitHub MCP tools
  - 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:

1. 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

2. 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

3. Documentation: Explain tool usage constraints in system prompt

   • When to use each tool
   • Common parameters and patterns
   • Error handling approaches

4. 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 steps
• decision-matrix.md - When to choose different approaches
• examples.md - Canonical examples
• troubleshooting.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:

1. 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]

2. Shared coordination guides:

• docs/agents/shared-ref-docs/agent-addressing-system.md
• docs/agents/shared-ref-docs/traycer-coordination-guide.md

3. 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:

1. Execute agent on evaluation tasks
2. Observe failures and confusion points
3. Read agent's reasoning (use extended thinking)
4. Analyze tool calls and responses
5. 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

• skill-name: [Purpose]

Commands Available

• /command-name: [Purpose]

Hooks Enforced

• PreToolUse: [What's validated]
• PostToolUse: [What feedback is provided]

Coordination

Delegates To

• Agent X: [When and why]

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 location (created in Phase 3.4)
SOURCE_FILE="docs/agents/<agent-name>/<agent-name>-agent.md"

# Target location
TARGET_FILE=".claude/agents/<agent-name>-agent.md"

# Verify source exists
if [[ ! -f "$SOURCE_FILE" ]]; then
  echo "❌ Source file not found: $SOURCE_FILE"
  exit 1
fi

# Create target directory if missing
mkdir -p ".claude/agents"

# Deploy with permission preservation
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)

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

# Run verification function from bootstrap script
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:

• Agent count increased by 1
• No warnings about missing files
• No errors in verification output
• New agent file appears in find .claude/agents -name "*-agent.md" output

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:

1. Read agent files from .claude/agents/
2. Run compliance checks (see 8.2)
3. Generate report (markdown or JSON)
4. Provide remediation guidance for failures
5. Exit with status code (0 = all pass, 1 = warnings, 2 = failures)

Example Usage:

# Audit all agents
/agent-builder --audit

# Audit single agent
/agent-builder --audit --agent backend-agent

# Audit with JSON output for CI/CD
/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:

1. Read agent file line-by-line
2. Count occurrences of --- (YAML delimiter) in first 20 lines
3. PASS: Exactly 2 occurrences (opening line 1, closing line ~6)
4. 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:

1. Parse YAML frontmatter (first block only, ignore duplicates)
2. Verify presence of each required field
3. PASS: All 4 fields present
4. WARN: Optional fields found in duplicate block (e.g., friendly_name)
5. 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:

1. Search agent file for pattern: **Project Context**:.*\.project-context\.md
2. PASS: Pattern found anywhere in file
3. 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:

1. Extract ref-doc references from agent file (pattern: docs/agents/<agent>/ref-docs/*.md or docs/agents/<agent>-agent/ref-docs/*.md)
2. For each reference, verify file exists on disk
3. Check if agent has ref-docs directory (either docs/agents/<agent>/ref-docs/ or docs/agents/<agent>-agent/ref-docs/)
4. PASS: All referenced paths exist OR no ref-doc references found
5. WARN: Agent has ref-docs/ directory but no files in it
6. 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:

1. Extract script references from agent file (pattern: docs/agents/<agent>/scripts/*.sh or similar)
2. For each reference, verify:
   • File exists on disk
   • File is executable (-x permission)
3. PASS: All referenced scripts exist and are executable OR no script references found
4. WARN: Script exists but is not executable (missing chmod +x)
5. 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:

1. Metadata (always loaded)
2. SKILL.md body (when triggered)
3. 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:

• Agent file created at docs/agents/<name>/<name>-agent.md
• YAML frontmatter contains all required fields (model, description, allowed-tools, recommended-skills)
• YAML frontmatter validates successfully (valid syntax)
• Project context snippet present immediately after frontmatter
• Available Resources section populated (Shared + Agent-Specific)
• System prompt at right altitude
• Tools have clear names and descriptions
• Skills use progressive disclosure
• Commands tested with arguments
• Hooks enforce critical rules
• Evaluation covers real-world tasks
• Security review complete
• No hardcoded secrets
• Paths are repo-relative
• Coordination documented
• Team documentation updated
• MCP tools listed in frontmatter (explicit, not wildcards)
• MCP tool usage documented in system prompt
• MCP tool constraints explained (filters, parameters)
• MCP error handling defined
• MCP tools tested with real API calls

Phase 7 Deployment Verification:

• Agent file deployed to .claude/agents/<name>-agent.md
• File permissions preserved (readable)
• Content matches source (cmp -s verification passed)
• docs/agents/README.md updated with new agent entry
• Agent appears in alphabetical order in README.md table
• Agent description extracted from YAML frontmatter
• Bootstrap verification passed (no errors or warnings)
• Agent count incremented by 1 in verification output
• New agent file appears in find .claude/agents -name "*-agent.md" output
• If --no-deploy flag used: Manual deployment instructions provided

Phase 8: Audit - Run compliance audit

• Run: /agent-builder --audit --agent <agent-name>
• All checks PASS (no FAIL status)
• Warnings reviewed and acceptable
• JSON report generated: /agent-builder --audit --agent <agent-name> --format json

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:

1. Add canonical examples
2. Increase specificity without hardcoding
3. Use clear section headers
4. 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:

1. Consolidate overlapping tools
2. Improve tool descriptions (explain to new hire)
3. Use namespacing (prefixes/suffixes)
4. 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:

1. Implement token-efficient tools
2. Use progressive disclosure in skills
3. Add pagination/filtering to tools
4. Configure auto-compaction
5. 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:

1. Check hooks in settings.json
2. Test matcher patterns
3. Run claude --debug to see hook execution
4. Verify script permissions (chmod +x)
5. 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:

1. Make description specific (what + when)
2. Validate YAML frontmatter
3. Check file location (.claude/skills/ or ~/.claude/skills/)
4. Test with explicit mention of skill purpose

Quick Reference

Creating agents:

1. Analyze requirements
2. Design architecture (prompt, tools, skills, commands, hooks)
3. Create components (call sub-skills as needed)
4. Write system prompt with YAML frontmatter
5. Set up hooks
6. Create documentation
7. Run evaluations
8. Iterate
9. 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