Skill Builder - Claude Code Skill Template Generator

Overview

Creates new Claude Code Skills with proper structure, YAML frontmatter, progressive disclosure, and complete documentation. Ensures skills follow best practices and specification requirements.

MCP Requirements

This skill operates using Claude Code's built-in tools only. No additional MCP servers required.

Skill creation uses file operations (Read, Write, Edit, Glob) and directory creation which are core Claude Code capabilities.

When to Use

• Creating new reusable skills
• Need skill template/boilerplate
• Building skill library
• Standardizing skill format

Phase 1: Design Skill Structure (5 min)

Objective

Define skill components and metadata

Agent: Base-Template-Generator

Step 1.1: Gather Requirements

const skillRequirements = {
  name: 'when-[condition]-use-[skill-name]',
  category: 'utilities|development|testing|machine-learning',
  description: 'Clear one-sentence purpose',
  agents: ['agent1', 'agent2'],
  phases: [
    { name: 'Phase 1', duration: '5min', objective: '...' },
    // ...
  ],
  triggers: ['When X happens', 'When Y is needed'],
  outputs: ['file1.json', 'report.md']
};

await memory.store('skill-builder/requirements', skillRequirements);

Step 1.2: Define YAML Frontmatter

---
name: when-[trigger]-use-[skill-name]
version: 1.0.0
description: Single sentence describing purpose
category: utilities
tags: [tag1, tag2, tag3]
agents: [agent1, agent2]
difficulty: beginner|intermediate|advanced
estimated_duration: 15-30min
success_criteria:
  - Criterion 1
  - Criterion 2
validation_method: test_type
dependencies:
  - claude-flow@alpha
  - other-dependency
prerequisites:
  - Required condition 1
outputs:
  - output-file-1
  - output-file-2
triggers:
  - Trigger condition 1
  - Trigger condition 2
---

Step 1.3: Plan Phase Structure

const phaseStructure = skillRequirements.phases.map((phase, i) => ({
  number: i + 1,
  title: phase.name,
  objective: phase.objective,
  duration: phase.duration,
  agent: phase.agent,
  steps: phase.steps,
  validation: phase.validation,
  memoryPattern: phase.memoryPattern,
  scriptTemplate: phase.scriptTemplate
}));

await memory.store('skill-builder/phase-structure', phaseStructure);

Validation Criteria

• Name follows convention
• All metadata defined
• Phases planned
• Agents identified

Phase 2: Generate Template (5 min)

Objective

Create skill file structure and boilerplate

Agent: Base-Template-Generator

Step 2.1: Create SKILL.md

---
[YAML frontmatter from Phase 1]
---

# ${skillName} - ${shortDescription}

## Overview
${detailedDescription}

## When to Use
${triggers.map(t => `- ${t}`).join('\n')}

## Phase 1: ${phase1.title}

### Objective
${phase1.objective}

### Agent: ${phase1.agent}

**Step 1.1: ${step1.title}**
\`\`\`javascript
${step1.code}
\`\`\`

**Step 1.2: ${step2.title}**
[Implementation details]

### Validation Criteria
${validation.map(v => `- [ ] ${v}`).join('\n')}

### Hooks Integration
\`\`\`bash
npx claude-flow@alpha hooks pre-task --description "${phase1.description}"
\`\`\`

## [Repeat for all phases]

## Success Metrics
${successCriteria}

## Memory Schema
\`\`\`javascript
${memorySchema}
\`\`\`

## Skill Completion
${completionCriteria}

Step 2.2: Create README.md

# ${skillName} - Quick Start Guide

## Purpose
${purpose}

## When to Use
${triggers}

## Quick Start
\`\`\`bash
npx claude-flow@alpha skill-run ${skillName}
\`\`\`

## ${phases.length}-Phase Process
${phases.map((p, i) => `${i+1}. **${p.title}** (${p.duration}) - ${p.objective}`).join('\n')}

## Expected Output
${outputExample}

## Success Criteria
${successCriteria}

For detailed documentation, see SKILL.md

Step 2.3: Create PROCESS.md

# ${skillName} - Detailed Workflow

## Process Overview
${processOverview}

## Phase Breakdown
${phases.map(phase => `
### Phase ${phase.number}: ${phase.title}

**Objective**: ${phase.objective}
**Agent**: ${phase.agent}
**Duration**: ${phase.duration}

**Steps**:
${phase.steps.map((step, i) => `${i+1}. ${step}`).join('\n')}

**Outputs**: ${phase.outputs.join(', ')}
**Validation**: ${phase.validation}
`).join('\n---\n')}

## Workflow Diagram
[See process-diagram.gv]

## Integration Patterns
${integrationExamples}

Step 2.4: Create process-diagram.gv

digraph ${SkillName} {
    rankdir=TB;
    node [shape=box, style=filled, fillcolor=lightblue];

    start [label="Input", shape=ellipse, fillcolor=lightgreen];
    ${phases.map((p, i) => `
    phase${i+1} [label="Phase ${i+1}: ${p.title}\\n(${p.duration})\\nAgent: ${p.agent}", fillcolor=lightcoral];
    output${i+1} [label="${p.outputs.join('\\n')}", shape=parallelogram];
    `).join('\n')}
    end [label="Output", shape=ellipse, fillcolor=lightgreen];

    start -> phase1;
    ${phases.map((p, i) => `
    phase${i+1} -> output${i+1};
    output${i+1} -> phase${i+2 <= phases.length ? i+2 : 'end'};
    `).join('\n')}
}

Validation Criteria

• All 4 files created
• YAML valid
• Content complete
• Diagram syntax correct

Phase 3: Implement Functionality (8 min)

Objective

Add implementation details and code examples

Agent: Coder

Step 3.1: Add Code Examples

// For each phase, add:
// - Implementation code snippets
// - Memory operations
// - Hook integrations
// - Script templates

const phaseImplementation = {
  codeExample: `
async function execute${phase.title}() {
  // Implementation
  await memory.store('${skillName}/${phase.key}', data);
  return result;
}
  `,
  hooks: `
npx claude-flow@alpha hooks pre-task --description "${phase.description}"
npx claude-flow@alpha hooks post-task --task-id "${phase.key}"
  `,
  scriptTemplate: `
#!/bin/bash
# ${phase.title}.sh
${phase.script}
  `
};

Step 3.2: Add Memory Patterns

const memorySchema = {
  [`${skillName}/`]: {
    [`session-\${id}/`]: {
      ...phases.reduce((acc, phase) => ({
        ...acc,
        [phase.key]: { /* phase data */ }
      }), {})
    }
  }
};

Step 3.3: Add Integration Examples

// How to use with other skills
const integrationExamples = {
  withSPARC: `${skillName} → SPARC workflow`,
  withCascade: `cascade: [${skillName}, next-skill]`,
  standalone: `npx claude-flow@alpha skill-run ${skillName}`
};

Validation Criteria

• Code examples complete
• Memory schema defined
• Hooks integrated
• Script templates added

Phase 4: Test Skill (5 min)

Objective

Validate skill executes correctly

Agent: Coder

Step 4.1: Syntax Validation

# Validate YAML
npx js-yaml SKILL.md

# Validate GraphViz
dot -Tsvg process-diagram.gv -o /dev/null

# Check file completeness
test -f SKILL.md && test -f README.md && test -f PROCESS.md && test -f process-diagram.gv

Step 4.2: Execution Test

# Try to run the skill
npx claude-flow@alpha skill-run ${skillName} --dry-run

# Check for errors
if [ $? -eq 0 ]; then
  echo "✅ Skill validation passed"
else
  echo "❌ Skill validation failed"
fi

Step 4.3: Documentation Review

const documentationChecklist = {
  hasYAMLFrontmatter: true,
  hasOverview: true,
  hasPhases: phases.length > 0,
  hasValidation: true,
  hasMemorySchema: true,
  hasSuccessMetrics: true,
  hasIntegrationExamples: true
};

const allChecksPassed = Object.values(documentationChecklist).every(v => v === true);

Validation Criteria

• YAML valid
• GraphViz valid
• All files present
• Dry-run successful

Phase 5: Document Usage (2 min)

Objective

Create usage guide and examples

Agent: Base-Template-Generator

Step 5.1: Add Usage Examples

## Usage Examples

### Basic Usage
\`\`\`bash
npx claude-flow@alpha skill-run ${skillName} \\
  --input "input.json" \\
  --output "output.json"
\`\`\`

### With Parameters
\`\`\`bash
npx claude-flow@alpha skill-run ${skillName} \\
  --param1 "value1" \\
  --param2 "value2"
\`\`\`

### Programmatic Usage
\`\`\`javascript
const result = await runSkill('${skillName}', {
  input: data,
  options: { ... }
});
\`\`\`

Step 5.2: Add Troubleshooting

## Troubleshooting

### Issue: ${commonIssue1}
**Solution**: ${solution1}

### Issue: ${commonIssue2}
**Solution**: ${solution2}

Step 5.3: Generate Completion Report

const completionReport = {
  skillName: skillRequirements.name,
  filesCreated: [
    'SKILL.md',
    'README.md',
    'PROCESS.md',
    'process-diagram.gv'
  ],
  linesOfCode: calculateLOC(),
  estimatedDuration: skillRequirements.estimatedDuration,
  agentsRequired: skillRequirements.agents.length,
  phasesImplemented: phases.length,
  validationStatus: 'PASSED',
  readyForUse: true
};

await memory.store('skill-builder/completion', completionReport);

Validation Criteria

• Usage examples added
• Troubleshooting guide complete
• Completion report generated
• Ready for use

Success Metrics

• All 4 files created
• YAML validation passes
• Skill executes without errors
• Documentation complete
• Ready for integration

Memory Schema

{
  "skill-builder/": {
    "session-${id}/": {
      "requirements": {},
      "phase-structure": [],
      "generated-files": [],
      "validation-results": {},
      "completion": {}
    }
  }
}

Common Patterns

Quick Skill Template

npx claude-flow@alpha skill-run skill-builder \
  --name "my-new-skill" \
  --category "utilities" \
  --agents "coder,tester" \
  --phases "3"

From Existing Workflow

# Convert workflow to skill
npx claude-flow@alpha skill-builder \
  --from-workflow "workflow.json" \
  --output-dir ".claude/skills/utilities/"

Skill Completion

Outputs:

1. SKILL.md: Complete skill specification
2. README.md: Quick start guide
3. PROCESS.md: Detailed workflow
4. process-diagram.gv: Visual process diagram

Skill complete when all files created and validation passes.

---

Core Principles

Skill Builder operates on 3 fundamental principles for creating production-ready Claude Code Skills:

Principle 1: Progressive Disclosure Structure

Skills reveal complexity incrementally - start with high-level overview, then drill into phases, then detailed steps, ensuring readers aren't overwhelmed.

In practice:

• Structure SKILL.md with YAML frontmatter (metadata), overview (purpose), phase breakdown (objectives), and detailed steps (implementation)
• Each phase contains objective, duration estimate, responsible agent, step-by-step instructions, validation criteria, and hooks integration
• README.md provides quick start guide with condensed workflow, while PROCESS.md offers detailed phase-by-phase breakdown for deep dives
• process-diagram.gv visualizes workflow with boxes for phases, parallelograms for outputs, and directed edges showing dependencies

Principle 2: YAML-Driven Metadata

All skill metadata lives in valid YAML frontmatter, enabling programmatic skill discovery, validation, and execution by tools.

In practice:

• Define required fields (name, version, description, category, tags, agents, difficulty, estimated_duration, success_criteria, validation_method)
• Use consistent naming convention (when-[trigger]-use-[skill-name]) for skills with automatic triggering based on keywords
• Document dependencies (claude-flow@alpha, other skills), prerequisites (required conditions), and outputs (generated files/artifacts)
• Include triggers array listing keyword patterns that should activate the skill automatically from user requests

Principle 3: Validation-First Development

Skills must pass syntax validation, execution tests, and documentation completeness checks before being marked production-ready.

In practice:

• Validate YAML frontmatter with js-yaml parser to catch syntax errors before runtime
• Test GraphViz diagram syntax with dot command to ensure process-diagram.gv renders correctly
• Execute skill in dry-run mode to verify all phases, agents, and hooks work without errors
• Run documentation checklist (Phase 4.3) to ensure YAML, overview, phases, validation, memory schema, success metrics, and integration examples all present

---

Common Anti-Patterns

Anti-Pattern	Problem	Solution
Incomplete YAML Frontmatter	Missing required metadata fields (name, version, success_criteria, etc.) breaks skill discovery tools and prevents automated validation	Use complete frontmatter template (Step 1.2) with all required fields validated by js-yaml before committing skill
Undocumented Memory Patterns	Skills that use memory-mcp without documenting schema create integration issues where agents don't know what data structures to expect	Define explicit memory schema (Section "Memory Schema") showing namespace structure, key paths, and data shapes for all memory operations
Missing Validation Criteria	Phases without explicit validation criteria create ambiguity about when the phase is complete and what success looks like	Add validation criteria section to every phase with checkboxes for specific, measurable completion requirements (e.g., "YAML validation passes", "All files present")

---

Conclusion

Skill Builder provides a systematic 5-phase approach to creating well-structured, production-ready Claude Code Skills with proper YAML metadata, progressive disclosure documentation, and comprehensive validation. By enforcing structure through templates and automated checks, it ensures skills are discoverable, executable, and maintainable.

This skill excels at standardizing skill creation across teams, building reusable skill libraries, and ensuring new skills follow best practices from the start. Use this when you need to create new skills that will be used repeatedly, shared with others, or integrated into automation workflows where proper structure and metadata are essential.

The key innovation is treating skills as first-class artifacts with structured metadata (YAML), multiple documentation layers (SKILL.md, README.md, PROCESS.md), visual representations (GraphViz diagrams), and automated validation (syntax checks, execution tests, completeness checks). This transforms skill creation from ad-hoc documentation to systematic engineering with quality gates.