Skill Builder — Scaffold & Generate

Process

Step 1: Gather Inputs

Determine what we're building from:

• Plan document: Output from /skill-forge plan (preferred)
• Description: Natural language description of the skill
• Existing skill: Path to a skill to use as foundation

If no plan exists, run a quick planning pass (ask 3 key questions):

1. What does the skill do? (1-2 sentences)
2. What commands should it have? (list)
3. Does it need scripts or external tools? (yes/no)

Step 2: Generate Frontmatter

The most critical step. The description field determines activation.

Framework for writing descriptions:

[Capability statement] + [Detailed capabilities] + [Trigger phrases]

Rules:

• Under 1024 characters total
• No XML angle brackets (< >)
• Include 5-10 trigger phrases users would say
• Mention file types if relevant
• Add negative triggers if risk of over-triggering

Use references/description-guide.md for the full framework.

Step 3: Write Main SKILL.md

Structure the body following this template:

# [Skill Name] -- [Tagline]

[1-2 sentence overview]

## Quick Reference

| Command | What it does |
|---------|-------------|
| /name cmd1 | Description |
| /name cmd2 | Description |

## Orchestration Logic

[How commands route to sub-skills]
[Decision trees for conditional routing]

## [Domain-Specific Section]

[Core rules, thresholds, quality gates]

## Reference Files

[List of on-demand reference files]

## Sub-Skills

[List of sub-skills with one-line descriptions]

Critical SKILL.md rules:

• Under 500 lines
• Under 5000 tokens
• Actionable instructions (not vague)
• Include error handling
• Link references, don't inline them

Step 4: Generate Sub-Skills (Tier 3-4)

For each sub-skill, generate a SKILL.md with:

---
name: parent-child
description: >
  [What it does]. Use when user says "[trigger 1]", "[trigger 2]",
  "[trigger 3]", or "[trigger 4]".
---

Sub-skill body guidelines:

• Self-contained instructions for ONE workflow
• Cross-reference other sub-skills by name (not inline their content)
• Reference shared files in the parent skill's references/ directory
• Include explicit input/output definitions

Step 5: Generate Scripts (Tier 2-4)

For each script:

#!/usr/bin/env python3
"""
Purpose: [What this script does]
Input: [Expected input format]
Output: [Expected output format]
Usage: python scripts/script_name.py [args]
"""

import argparse
import json
import sys
from typing import Any


def main(args: argparse.Namespace) -> dict[str, Any]:
    """Main execution function."""
    # Validate inputs
    # Do the work
    # Return structured output
    pass


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="[Script description]")
    parser.add_argument("input", help="[Input description]")
    parser.add_argument("--output", "-o", help="Output file path")
    args = parser.parse_args()

    try:
        result = main(args)
        print(json.dumps(result, indent=2))
    except Exception as e:
        print(json.dumps({"error": str(e)}), file=sys.stderr)
        sys.exit(1)

Script rules:

• One script, one responsibility
• CLI interface with argparse
• Structured JSON output
• Clear error messages
• No dependencies beyond stdlib when possible

Step 6: Generate Reference Files

For each reference file:

• Focus on ONE topic
• Under 200 lines
• Include concrete examples
• Use tables for thresholds and specifications
• Mark with "Load on-demand" in parent SKILL.md

Step 7: Generate Agent Definitions (Tier 4)

Agent files use YAML frontmatter (different from skills):

---
name: [skill-name]-[role]
description: >
  [What this agent analyzes].
  <example>User says: "[trigger]"</example>
model: inherit
color: blue
tools:
  - Read
  - Grep
  - Glob
---

You are a [role] specialist.

## Your Role
[What this agent does]

## Process
1. [Steps...]

## Output Format
Return structured markdown with findings and recommendations.

Key differences from skills: Agent name is 3-50 chars, descriptions CAN use <example> blocks, agent-only fields include tools, color, permissionMode, maxTurns, memory. Body becomes the system prompt (second person).

Step 8: Generate Install Script

Create install.sh that copies files to ~/.claude/skills/ and ~/.claude/agents/.

Step 9: Validate

Run python scripts/validate_skill.py <path> on the generated skill. Check all quality gates from the main SKILL.md.

Step 10: Output Summary

Present the user with:

1. Generated file tree
2. Key files and their purposes
3. Installation instructions
4. Suggested test queries (3 that should trigger, 3 that should NOT)
5. Next steps (test, iterate, publish)

Scaffolding Command

For quick scaffolding, use:

python scripts/init_skill.py <skill-name> --tier <1-4> --path <output-path>

This creates the full directory structure with placeholder content.