Creating Agents

This skill guides you through designing and writing effective agent specifications. Agents are specialized Claude Code agents that orchestrate skills to accomplish specific tasks.

What This Skill Covers

• Single agent authoring: Designing and writing one agent specification (frontmatter, classification, workflows, collaborations)
• Agent structure: Required sections, YAML frontmatter schema, markdown body organization
• Quality standards: Checklists, validation rules, testing approaches
• Integration patterns: Skill orchestration, tool execution, collaboration protocols

What this skill does NOT cover: Ecosystem-wide refactoring, agent overlap analysis, or multi-agent coordination strategies. For those capabilities, use capability discovery with "refactoring agents" or "agent ecosystem refactor".

Quick Start

When creating a new agent:

1. Read the authoring guide: See references/authoring-guide.md for complete doctrinal details
2. Use the template: Start from assets/agent-template.md
3. Follow the checklist: Validate against assets/agent-checklists.md
4. Run automated validation: Execute python3 scripts/validate_agent.py agents/agent-name.md or /agent/validate agent-name
5. Test roll-call: Verify agent loads correctly using /agent/roll-call agent-name
6. Test integration: Verify skill paths, Python tools, and workflows

Core Principles

Agents Orchestrate Skills

Key principle: Agents ORCHESTRATE skills, they don't replace them. Skills remain self-contained and portable.

• Agents reference skills via relative paths (../../skills/domain-team/skill-name/)
• Agents execute Python tools from skill packages
• Agents follow established workflows and templates
• Skills maintain independence and portability

Single Agent Focus

This skill focuses on designing and writing a single agent specification. For each agent:

• Define clear purpose and scope
• Classify agent type (strategic, implementation, quality, coordination)
• Document workflows and skill integration
• Specify collaborations and relationships
• Validate against quality standards

Progressive Disclosure

Keep SKILL.md concise. Detailed doctrinal content lives in reference files:

• Authoring guide: Complete standards, schemas, validation rules → references/authoring-guide.md
• Template: Starting point for new agents → assets/agent-template.md
• Checklists: Quality validation criteria → assets/agent-checklists.md

Agent File Structure

Every agent is a single markdown file with:

1. YAML frontmatter (required): Identity, classification, relationships, technical details
2. Markdown body (required): Purpose, skill integration, workflows, examples

Frontmatter Sections

See references/authoring-guide.md for complete schema. Required sections:

• Core Identity: name, title, description, domain, subdomain, skills
• Agent Classification: classification (type, color, field, expertise, execution)
• Relationships: related-agents, related-skills, related-commands
• Collaboration: collaborates-with (optional agent dependencies)
• Technical: tools, dependencies

Skill Relationship Fields

Two fields describe how an agent relates to skills (see authoring-guide.md#skill-relationship-semantics for full details):

Field	Meaning	Documentation Obligation
skills	Core skills that define the agent	Index (path + brief description)
related-skills	Supplementary skills to pull in as-needed	None (consult skill docs)

Key rule: Index, don't duplicate. For skills, provide exact paths and brief descriptions pointing to skill docs. Agents perform better with retrieval-led reasoning (knowing WHERE to find info) than with duplicated content.

Deprecated: The orchestrates field has been removed.

Body Sections

Required markdown sections after frontmatter:

1. Purpose (2-3 paragraphs): What the agent does, why it exists, who it serves
2. Skill Integration: Location, Python tools, knowledge bases, templates
3. Workflows (minimum 3): Step-by-step procedures with examples
4. Integration Examples: Concrete commands and expected outputs
5. Success Metrics: How to measure effectiveness
6. Related Agents: Cross-references to complementary agents
7. References: Links to skill documentation and related resources

Agent Classification

Agents are classified into four types based on operational characteristics:

Type	Color	Tools	Execution	Model	Examples
Strategic	Blue	Read, Write, Grep	Parallel (4-5)	opus/sonnet	product-director, cto-advisor
Implementation	Green	Full tools	Coordinated (2-3)	sonnet	fullstack-engineer, backend-engineer
Quality	Red	Full + Heavy Bash	Sequential (1)	sonnet	code-reviewer, qa-engineer
Coordination	Purple	Read, Write, Grep	Lightweight	opus	architect, progress-assessor

Classification rules: See references/authoring-guide.md for detailed criteria and execution safety rules.

Skill Integration Pattern

All agents reference skills using relative paths:

**Skill Location:** `../../skills/domain-team/skill-name/`

### Python Tools

1. **Tool Name**
   - **Path:** `../../skills/domain-team/skill-name/scripts/tool.py`
   - **Usage:** `python ../../skills/domain-team/skill-name/scripts/tool.py [args]`

Path resolution: From agents/agent-name.md to skills/domain-team/skill-name/ uses ../../ pattern.

Always test paths resolve correctly before committing.

Skill Deploy-Readiness Rules

When agents reference skills, those skills must be deploy-compatible (name format, name-folder match, YAML-safe description, required fields). See references/deploy-readiness-rules.md for the full rules and enforcement details.

Workflow Documentation

Each agent must document at least 3 workflows:

1. Primary use case: Most common scenario
2. Advanced use case: Complex scenario requiring multiple tools
3. Integration use case: Combining with other agents or skills

Workflow Structure

### Workflow 1: [Clear Descriptive Name]

**Goal:** One-sentence description

**Steps:**
1. **[Action]** - Description with specific commands/tools
2. **[Action]** - Description with specific commands/tools
3. **[Action]** - Description with specific commands/tools

**Expected Output:** What success looks like

**Time Estimate:** How long this workflow takes

**Example:**
\`\`\`bash
python ../../skills/domain-team/skill-name/scripts/tool.py input.txt
\`\`\`

Collaboration Pattern

Use collaborates-with section to define optional agent dependencies:

collaborates-with:
  - agent: technical-writer
    purpose: API documentation generation with sequence diagrams
    required: optional
    without-collaborator: "API documentation will be text-only without visual diagrams"

Collaboration rules: See references/authoring-guide.md for schema and best practices.

Quality Standards

Before committing an agent, validate against:

• Automated validation passed: Run python3 scripts/validate_agent.py agents/agent-name.md or /agent/validate agent-name
• YAML frontmatter valid (no parsing errors)
• All required fields present
• Agent naming consistent (no ap- prefix)
• Relative paths resolve correctly
• Skill location documented and accessible
• Python tools referenced with correct paths
• At least 3 workflows documented
• Integration examples provided and tested
• Success metrics defined
• Related agents cross-referenced
• Quality agent examples: If type: quality, at least 2 examples (1 pass + 1 fail) present
• Roll-call test passed: Verify agent loads correctly in Cursor using /agent/roll-call agent-name
• Referenced skills deploy-ready: Skills referenced by this agent pass deploy-readiness rules (name format, name-folder match, YAML-safe description, required fields)

Complete checklist: See assets/agent-checklists.md for detailed validation criteria.

Testing Agent Integration

Automated Validation (Recommended First Step)

Run the validation script before manual testing:

# Validate agent structure, paths, and frontmatter
python3 scripts/validate_agent.py agents/agent-name.md

# Or use the command
/agent/validate agent-name

Roll-Call Test (Dynamic Validation)

Test that the agent loads correctly in Cursor:

# Test agent loading and skill access
/agent/roll-call agent-name

Or manually in Cursor Chat:

@agents/agent-name.md
What skills are you using?

Manual Testing

Test these aspects before committing:

1. Path Resolution

# From agent directory
cd agents/domain/
ls ../../skills/domain-team/skill-name/  # Should list contents

2. Python Tool Execution

# Create test input
echo "Test content" > test-input.txt

# Execute tool
python ../../skills/domain-team/skill-name/scripts/tool.py test-input.txt

# Verify output

3. Knowledge Base Access

# Verify reference files exist
cat ../../skills/domain-team/skill-name/references/guide.md

Common Patterns

Guardian Pattern

Guardian agents assess, guide, and validate but never implement:

• Proactive: Provide guidance before implementation
• Reactive: Validate and review after implementation
• Output: Prioritized findings (Critical → High Priority → Nice to Have)

Examples: tdd-reviewer, docs-reviewer, refactor-assessor

Quality Agent Example Requirements

Agents classified as type: quality assess code, artifacts, or configurations. Consistent assessment behavior requires concrete examples showing what "pass" and "fail" look like.

Rule: Every type: quality agent must include at least 2 examples in its body or frontmatter examples field:

1. One PASS example -- an input that meets quality standards, showing the expected positive assessment output
2. One FAIL example -- an input that violates quality standards, showing the expected negative assessment output with specific findings

Rationale: Without pass/fail examples, quality agents produce inconsistent assessments. The examples serve as calibration anchors -- they define the agent's judgment baseline so different sessions produce comparable results.

Where to place examples:

• Frontmatter examples field -- structured input/output pairs (preferred for discovery)
• Body ## Integration Examples section -- longer narrative examples with context
• Both locations count toward the minimum; at least one pass and one fail must be clearly identifiable

Delegation Pattern

Agents should delegate to specialized agents rather than duplicating capabilities:

• Research: Delegate to researcher for external research
• Planning: Delegate to implementation-planner for tactical planning
• Validation: Delegate to guardian agents for quality checks

Delegation rules: See references/authoring-guide.md for detailed guidance.

Anti-Patterns to Avoid

• Hardcoding absolute paths - Always use relative paths (../../)
• Skipping YAML validation - Test frontmatter parsing before committing
• Forgetting path testing - Verify all relative paths resolve correctly
• Workflows without examples - Every workflow needs concrete command examples
• Creating agent dependencies - Keep agents independent; use collaborations instead
• Duplicating skill content - Reference skills, don't copy their content
• Using LLM calls instead of Python tools - Agents orchestrate tools, don't replace them

Domain-Specific Patterns & Examples

Note: This section shows patterns and examples for creating agents in each domain. It is NOT a complete listing of all agents. For the complete agent catalog, see agents/README.md.

These patterns help you understand the conventions for each domain when creating new agents:

Marketing Agents (root agents/)

• Location: Root agents/ directory (no subfolder)
• Reference: ../skills/marketing-team/
• Focus: Content creation, SEO, demand generation
• Common tools: brand_voice_analyzer.py, seo_optimizer.py
• Example agents: content-creator, seo-strategist, product-marketer

Product Agents (root agents/)

• Location: Root agents/ directory (no subfolder)
• Reference: ../skills/product-team/
• Focus: Prioritization, user research, agile workflows
• Common tools: rice_prioritizer.py, user_story_generator.py
• Example agents: product-manager, product-director, ux-researcher

Engineering Agents (root agents/)

• Location: Root agents/ directory (no subfolder)
• Reference: ../skills/engineering-team/
• Focus: Code development, quality, architecture
• Common tools: project_scaffolder.py, code_quality_analyzer.py
• Example agents: backend-engineer, frontend-engineer, architect

Delivery Agents (root agents/)

• Location: Root agents/ directory (no subfolder)
• Reference: ../skills/delivery-team/
• Focus: Project management, agile coaching, progress tracking
• Common tools: Project planning and tracking tools
• Example agents: agile-coach, senior-project-manager, progress-assessor

When to Use This Skill

Use this skill when:

• Creating a new agent from scratch
• Updating an existing agent's structure or workflows
• Adding collaboration relationships to an agent
• Validating agent quality before committing
• Understanding agent classification and execution patterns

Do NOT use this skill for:

• Refactoring multiple agents or analyzing ecosystem overlap
• Creating or modifying skills (use capability discovery with "creating skills" or "skill authoring" to load the matching skill)
• Understanding when to invoke agents (see agents/README.md)

Next Steps

After creating an agent:

1. Validate: Run through assets/agent-checklists.md
2. Test: Verify all paths, tools, and workflows
3. Update README: REQUIRED - Add the new agent to agents/README.md in the "Complete Agent Catalog" section
4. Commit: Use conventional commit: feat(agents): implement agent-name

Maintenance Requirement: You MUST update agents/README.md whenever you add, delete, move, or rename an agent. The README serves as the complete catalog and operator's guide. See the maintenance note at the top of agents/README.md for details.

Reference Files

• references/authoring-guide.md: Complete authoring standards, schemas, classification matrix, execution safety rules, MCP patterns, templates
• assets/agent-template.md: Starting template for new agents
• assets/agent-checklists.md: Quality validation checklists

Always consult the authoring guide for detailed doctrinal content not covered in this SKILL.md.