skill-builder

What this skill does

# Skill-Builder: Meta-Skill for Creating Skills

You help create new agent skills that follow established patterns. Your role is to guide skill design, generate scaffolding, and validate completeness.

## Core Principle

**Skills are diagnostic frameworks with tools, not feature checklists.**

A skill diagnoses a problem space, identifies states, and provides interventions. Scripts provide randomization and structure; the LLM provides judgment. Each does what it's best at.

## Skill Anatomy

Every skill has these components:

```
skill-name/
├── SKILL.md           # Diagnostic framework + documentation
├── scripts/           # Deno TypeScript tools
│   └── *.ts
├── data/              # JSON datasets (if needed)
│   └── *.json
└── references/        # Supporting documentation (optional)
    └── *.md
```

### SKILL.md Structure

```markdown
---
name: skill-name
description: One sentence starting with action verb
license: MIT
metadata:
  author: your-name
  version: "1.0"
  maturity_score: [0-20]                          # Optional
---

# Skill Name: Subtitle

You [role description]. Your role is to [specific function].

## Core Principle
**Bold statement capturing diagnostic essence.**

## The States
### State X1: Name
**Symptoms:** What the user notices
**Key Questions:** What to ask
**Interventions:** What framework/tool to apply

[Repeat for each state]

## Diagnostic Process
1. Step one
2. Step two
...

## Key Questions
### For Category A
- Question?
- Question?

## Anti-Patterns
### The [Problem Name]
**Problem:** Description
**Fix:** Solution

## Available Tools
### script.ts
Description of what it does.
\`\`\`bash
deno run --allow-read scripts/script.ts [args]
\`\`\`

## Example Interaction
**User:** "Problem description"
**Your approach:**
1. Action
2. Action

## What You Do NOT Do
- List of boundaries
- Things the skill never does

## Integration Graph

### Inbound (From Other Skills)
| Source Skill | Source State | Leads to State |
|--------------|--------------|----------------|
| [skill] | [state] | [state] |

### Outbound (To Other Skills)
| This State | Leads to Skill | Target State |
|------------|----------------|--------------|
| [state] | [skill] | [state] |

### Complementary Skills
| Skill | Relationship |
|-------|--------------|
| [skill] | [how they relate] |
```

## Skill Types

### Type D: Diagnostic Skills
**Purpose:** Identify problems, recommend interventions
**Pattern:** States → Questions → Interventions
**Examples:** story-sense, worldbuilding, conlang

Key characteristics:
- Problem states with symptoms/questions
- Cross-references to intervention tools
- "What you do NOT do" section enforces boundaries
- Integration tables mapping to other skills

### Type G: Generator Skills
**Purpose:** Produce structured output from parameters
**Pattern:** Parameters → Generation → Output
**Examples:** Functions in story-sense, phonology in conlang

Key characteristics:
- Input parameters with defaults
- Randomization with optional seeding
- Multiple output formats (human, JSON, brief)
- Quality levels (starter → comprehensive)

### Type U: Utility Skills
**Purpose:** Support other skills, build infrastructure
**Pattern:** Input → Analysis/Transformation → Report
**Examples:** list-builder, skill-builder

Key characteristics:
- Meta-level operation
- Quality metrics and validation
- Templates and scaffolding
- Cross-skill applicability

### Type O: Orchestrator Skills
**Purpose:** Coordinate multiple skills into autonomous workflows
**Pattern:** Input → Multi-Pass Evaluation Loop → Polished Output
**Examples:** chapter-drafter

Key characteristics:
- Invokes multiple sub-skills sequentially
- Iterates until quality thresholds met
- Accumulates context across work units
- Operates autonomously without human checkpoints

Required frontmatter:
```yaml
metadata:
  orchestrates:           # Sub-skills to coordinate
    - skill-one
    - skill-two
  pass_order:             # Evaluation sequence
    - skill-one
    - skill-two
  pass_weights:           # Weight per skill (sum to 100)
    skill-one: 50
    skill-two: 50
  max_iterations: 3       # Per-pass iteration limit
  global_max_iterations: 50  # Total cap
```

See `skills/fiction/orchestrators/README.md` for architectural details.

## Skill Maturity Scoring (24 points)

Skills are evaluated on a 24-point scale parallel to the framework 24-point system.

### Completeness (11 points)

| Check | Points | Criteria |
|-------|--------|----------|
| Core Principle | 1 | Bold statement capturing diagnostic essence |
| States | 2 | 3-7 states for diagnostic skills (N/A for generator/utility) |
| State Components | 2 | Symptoms, Key Questions, Interventions for each state |
| Diagnostic Process | 1 | Step-by-step process documented |
| Anti-Patterns | 2 | 3+ anti-patterns with Problem/Fix structure |
| Examples | 2 | 2+ worked examples showing skill application |
| Boundaries | 1 | "What You Do NOT Do" section |

### Quality (5 points)

| Check | Points | Criteria |
|-------|--------|----------|
| Self-Contained | 1 | Can be used without reading other skills |
| Type+Mode Declared | 1 | Required frontmatter fields present |
| State Naming | 1 | Consistent state prefix matching skill abbreviation |
| Integration Map | 1 | Documents connections to other skills |
| Tools Documented | 1 | All scripts have usage documentation |

### Usability (4 points)

| Check | Points | Criteria |
|-------|--------|----------|
| Output Persistence | 1 | Customized (not boilerplate) persistence section |
| Progressive Disclosure | 1 | Quick reference section for at-a-glance use |
| Decision Tree | 1 | Routing logic for common scenarios |
| Actionability | 1 | Clear next steps for each diagnosis |

### Execution Intelligence (4 points) — NEW

| Check | Points | Criteria |
|-------|--------|----------|
| Reasoning Requirements | 1 | Specifies when extended thinking benefits the task |
| Execution Strategy | 1 | Documents sequential vs. parallelizable work |
| Subagent Guidance | 1 | Identifies when to spawn specialized subagents |
| Context Management | 1 | Documents token footprint and optimization strategies |

### Maturity Levels

| Level | Score | Description |
|-------|-------|-------------|
| Draft | 0-8 | Missing core elements |
| Developing | 9-14 | Functional but incomplete |
| Stable | 15-20 | Production-ready |
| Battle-Tested | 21-24 | Has case studies + full execution intelligence |

## Required Metadata

### Type (Required)

Every skill must declare its type in frontmatter:

```yaml
metadata:
```

| Type | Definition | Required Sections |
|------|------------|-------------------|
| **diagnostic** | Identifies problems, recommends interventions | States, Diagnostic Process, Anti-Patterns |
| **generator** | Produces structured output from parameters | Parameters, Generation Logic, Output Formats |
| **utility** | Supports other skills, builds infrastructure | Process, Templates, Validation |
| **orchestrator** | Coordinates multiple skills into autonomous workflows | Orchestration Loop, Pass Criteria, Iteration Limits |

### Mode (Required)

Every skill must declare its mode in frontmatter:

```yaml
metadata:
```

| Mode | Definition | User Relationship |
|------|------------|-------------------|
| **diagnostic** | Identifies problem states and recommends | Agent diagnoses, user decides |
| **assistive** | Guides without producing content | Agent asks questions, user creates |
| **collaborative** | Works alongside user | Agent produces, user guides |
| **evaluative** | Assesses existing work | Agent reviews, user responds |
| **application** | Operates in real-time context | Agent runs, user participates |
| **generative** | Creates output from parameters | Agent produces, user selects |

**Compound modes** (e.g., `diagnostic+generative`) are allowed when skills perform multiple functions.

### Optional Metadata

```yaml
metadata:
  maturity_score: 15
```

## State Naming Convention

States must fol