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

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)

Outbound (To Other Skills)

Complementary Skills

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:

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:

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:

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

metadata: maturity_score: 15

State Naming Convention

States must follow a consistent naming pattern:

Convention: {ABBREV}{NUMBER}: {State Name}

Rules:

• Abbreviation is 1-3 uppercase letters derived from skill name

• Numbers start at 0 (for "no X exists" states) or 1

• State names are descriptive, not just numbers

• Sub-states use decimal notation (4.5, 5.75) when inserting between existing states

Standard Abbreviations:

Skill Abbreviation Example

story-sense SS State SS1: Concept Without Foundation

dialogue D State D1: Identical Voices

conlang L State L1: No Language

worldbuilding W State W1: Backdrop World

revision R State R1: Overwhelmed

endings E State E1: Arbitrary Ending

character-arc CA State CA1: Static Character

scene-sequencing SQ State SQ1: Scene-Only Pacing

brainstorming B State B1: Convergent Ideas

research RS State RS1: No Research

requirements-analysis RA State RA1: Vague Requirements

system-design SD State SD1: No Architecture

chapter-drafter CD (Orchestrator - uses pass scores, not states)

New skills should claim an unused abbreviation and document it here.

Integration Graph Requirements

Every skill must document its connections to other skills.

Required Format:

Integration Graph

Inbound (From Other Skills)

Outbound (To Other Skills)

Complementary Skills

Requirements:

• Minimum 1 inbound OR 1 outbound connection

• Complementary skills list for context

• State-level specificity (not just skill-to-skill)

• Bidirectional documentation (if A references B, B should reference A)

Execution Intelligence Requirements

Skills should document how they're best executed by Claude Code.

Reasoning Requirements Section

Document when extended thinking (ultrathink ) benefits the skill:

Reasoning Requirements

Standard Reasoning

• Initial diagnosis and symptom matching
• Simple state identification
• Script execution and output interpretation

Extended Reasoning (ultrathink)

Use extended thinking for:

• Multi-framework synthesis - [Why: requires holding multiple models simultaneously]
• Complex worldbuilding systems - [Why: many interdependent variables]
• Cascade analysis across states - [Why: second-order effects compound]

Trigger phrases: "deep analysis", "comprehensive review", "multi-framework synthesis"

Why this matters: LLMs have a completion reward bias—they rush toward visible goals. Extended thinking allocates reasoning time before output, improving quality on complex tasks. This aligns with the LLM Process Design Framework principle.

Execution Strategy Section

Document sequential vs. parallel work:

Execution Strategy

Sequential (Default)

• Diagnosis must complete before intervention
• State identification before framework selection

Parallelizable

• Multiple script runs (entropy + functions) can run concurrently
• Research across multiple frameworks can parallelize
• Use when: Tasks are independent and can merge results

Subagent Candidates

Context Management Section

Document token usage and optimization:

Context Management

Approximate Token Footprint

• Skill base: ~2k tokens
• With full state definitions: ~4k tokens
• With scripts inline: ~8k tokens (avoid unless debugging)

Context Optimization

• Load scripts on-demand rather than including inline
• Reference framework documentation by name rather than embedding
• Use Quick Reference section for common cases

When Context Gets Tight

• Prioritize: Current state diagnosis and immediate intervention
• Defer: Integration graph, full anti-patterns list
• Drop: Script source code, historical examples

Anti-Pattern Requirements

Every skill must document common mistakes.

Minimum Requirements:

• 3 anti-patterns for diagnostic skills

• 2 anti-patterns for generator/utility skills

Required Structure:

The {Anti-Pattern Name}

Pattern: What the problematic behavior looks like Problem: Why this causes harm Fix: How to resolve it Detection: [Optional] How to recognize this happening

Common Anti-Pattern Categories:

Category Example Names

Scope Creep The Kitchen Sink, The Mission Creep

Missing Depth The Surface Treatment, The Checklist

Wrong Level The Bottom-Up Edit, The Premature Optimization

User Relationship The Puppet Master, The Passive Recipient

Integration The Orphan Skill, The Boundary Ignorer

Script Patterns

Standard Script Template

#!/usr/bin/env -S deno run --allow-read

/**

• Script Name
• Description of what it does.
• Usage:
• deno run --allow-read script.ts [args] */

// === INTERFACES === interface ResultType { field: string; // ... }

// === DATA === const DATA: Record<string, string[]> = { category: ["item1", "item2"], };

// === UTILITIES === function randomFrom<T>(arr: T[], count: number = 1): T[] { const shuffled = [...arr].sort(() => Math.random() - 0.5); return shuffled.slice(0, Math.min(count, arr.length)); }

// === CORE LOGIC === function generate(/* params */): ResultType { // Generation logic }

// === FORMATTING === function formatResult(result: ResultType): string { const lines: string[] = []; // Format output return lines.join("\n"); }

// === MAIN === function main(): void { const args = Deno.args;

// Help if (args.includes("--help") || args.includes("-h")) { console.log(`Script Name

Usage: deno run --allow-read script.ts [options]

Options: --flag Description --json Output as JSON `); Deno.exit(0); }

// Parse arguments const flagIndex = args.indexOf("--flag"); const flagValue = flagIndex !== -1 ? args[flagIndex + 1] : null; const jsonOutput = args.includes("--json");

// Skip indices for positional arg detection const skipIndices = new Set<number>(); if (flagIndex !== -1) { skipIndices.add(flagIndex); skipIndices.add(flagIndex + 1); }

// Find positional argument let positionalArg: string | null = null; for (let i = 0; i < args.length; i++) { if (!args[i].startsWith("--") && !skipIndices.has(i)) { positionalArg = args[i]; break; } }

// Generate const result = generate(/* params */);

// Output if (jsonOutput) { console.log(JSON.stringify(result, null, 2)); } else { console.log(formatResult(result)); } }

main();

Argument Parsing Pattern

// 1. Help check first if (args.includes("--help") || args.includes("-h")) { ... }

// 2. Parse --flag value pairs const flagIndex = args.indexOf("--flag"); const flagValue = flagIndex !== -1 ? args[flagIndex + 1] : defaultValue;

// 3. Boolean flags const boolFlag = args.includes("--bool");

// 4. Track consumed indices const skipIndices = new Set<number>(); if (flagIndex !== -1) { skipIndices.add(flagIndex); skipIndices.add(flagIndex + 1); }

// 5. Find positional args for (let i = 0; i < args.length; i++) { if (!args[i].startsWith("--") && !skipIndices.has(i)) { positionalArg = args[i]; break; } }

Data Loading Pattern

// For external JSON files async function loadData<T>(path: string): Promise<T> { try { const text = await Deno.readTextFile(path); return JSON.parse(text); } catch (e) { console.error(Error loading ${path}: ${e}); Deno.exit(1); } }

// Relative path from script const scriptDir = new URL(".", import.meta.url).pathname; const dataPath = ${scriptDir}../data/file.json;

Output Pattern

// Always support multiple formats if (jsonOutput) { console.log(JSON.stringify(result, null, 2)); } else if (briefOutput) { console.log(formatBrief(result)); } else { console.log(formatFull(result)); }

Data File Patterns

Simple List (for entropy/randomization)

{ "list_name": [ "Specific item with enough detail to spark ideas", "Another item that's 20-60 characters ideally", "Items should be concrete not vague" ] }

Quality thresholds:

• Starter: 10-30 items (demo only)

• Functional: 30-75 items (usable)

• Production: 75-150 items (ready)

• Comprehensive: 150+ items (reference quality)

Structured Data (for complex generation)

{ "_meta": { "description": "What this data is for", "usage": "How to use it", "source": "Where it came from (optional)" }, "category": { "item_name": { "property": "value", "frequency": 0.85, "tags": ["tag1", "tag2"] } } }

Frequency-Weighted Data

{ "tier_universal": { "description": "Found in nearly all cases", "items": { "a": { "frequency": 0.95 }, "b": { "frequency": 0.90 } } }, "tier_common": { "description": "Found in most cases", "items": { "c": { "frequency": 0.70 } } }, "tier_rare": { "description": "Unusual but attested", "items": { "d": { "frequency": 0.15 } } } }

Diagnostic Process for Building Skills

When creating a new skill:

1. Identify the Problem Space

• What problems does this skill diagnose?

• What are the symptoms a user would notice?

• How does this connect to existing skills?

2. Define States

• Create 3-7 distinct states

• Each state needs: symptoms, key questions, interventions

• States should be mutually exclusive but cover the space

3. Design Tools

• What can scripts do better than LLM judgment?

• Randomization? Structure generation? Validation?

• What data does the script need?

4. Map Integrations

• Which other skills does this connect to?

• What states in other skills lead here?

• What states here lead elsewhere?

5. Validate Completeness

Run validate-skill.ts to check:

• Required frontmatter fields

• State definitions with all components

• Script documentation

• Integration references

Available Tools

scaffold.ts

Generates skill directory structure and template files.

Create new skill scaffolding

deno run --allow-read --allow-write scripts/scaffold.ts skill-name

With type specification

deno run --allow-read --allow-write scripts/scaffold.ts skill-name --type diagnostic

Preview without writing

deno run --allow-read scripts/scaffold.ts skill-name --dry-run

validate-skill.ts

Checks skill completeness and pattern conformance.

Validate a skill

deno run --allow-read scripts/validate-skill.ts ../worldbuilding

Validate all skills in fiction cluster

deno run --allow-read scripts/validate-skill.ts --all

JSON output for CI

deno run --allow-read scripts/validate-skill.ts ../conlang --json

Anti-Patterns

The Feature List Skill

Problem: Skill is a list of things it can do, not a diagnostic framework. Fix: Restructure around problem states. What are users stuck on?

The Kitchen Sink

Problem: Skill tries to do too much, covers multiple problem domains. Fix: Split into focused skills. One skill = one diagnostic space.

The Script Without Skill

Problem: Script exists but no SKILL.md explains when to use it. Fix: Every script belongs to a skill with documented purpose.

The Orphan Skill

Problem: Skill doesn't reference or get referenced by other skills. Fix: Add integration section. Map state transitions to/from other skills.

The Clone Skill

Problem: Skill duplicates another skill's states with different names. Fix: Merge or clearly differentiate the problem spaces.

Verification (Oracle)

This section documents what this skill can reliably verify vs. what requires human judgment. See organization/architecture/context-packet-architecture.md for background on oracles.

What This Skill Can Verify

• Structural completeness - validate-skill.ts checks required sections exist (High confidence)

• State naming conventions - Validates {ABBREV}{N}: Name pattern (High confidence)

• Frontmatter presence - Required type/mode fields present (High confidence)

• Section presence - Anti-patterns, Integration Graph, Output Persistence exist (High confidence)

• State component structure - Symptoms/Questions/Interventions present per state (Medium confidence)

What Requires Human Judgment

• State quality - Are states mutually exclusive and comprehensive? (Semantic)

• Integration accuracy - Do state transitions make sense across skills? (Contextual)

• Anti-pattern usefulness - Do they capture real failure modes? (Experiential)

• Example relevance - Do examples match real use cases? (Domain knowledge)

• Boundary appropriateness - Is the scope correct for one skill? (Design judgment)

Available Validation Scripts

Script Verifies Confidence

validate-skill.ts 20-point maturity scoring across Completeness/Quality/Usability High for structure, Low for semantics

scaffold.ts Generated files match expected structure High

Oracle Limitations

The validate-skill.ts script:

• Cannot detect duplicated skill coverage (The Clone Skill anti-pattern)

• Cannot detect scope creep (The Kitchen Sink anti-pattern)

• Cannot verify integration bidirectionality (must check both skills manually)

• Reports presence, not quality - a section existing doesn't mean it's good

Feedback Loop

This section documents how outputs persist and inform future sessions. See organization/architecture/context-packet-architecture.md for background on feedback loops.

Session Persistence

• Output location: skills/{cluster}/{skill-name}/ (directory structure)

• What to save: SKILL.md, scripts/, data/, templates/

• Naming pattern: Skill name becomes directory name

Cross-Session Learning

• Before starting: Check if a skill for this problem space already exists

• If prior skill exists: Extend rather than duplicate; check integration graph

• What feedback improves this skill:

• New anti-patterns discovered during skill creation

• State naming collisions found

• Integration patterns that work well

Improvement Triggers

• When validate-skill.ts reveals common failures → Update maturity criteria

• When skill creation struggles → Add to anti-patterns

• When integration mapping is unclear → Improve Integration Graph section

Design Constraints

This section documents preconditions and boundaries. See organization/architecture/context-packet-architecture.md for background on constraints.

This Skill Assumes

• User has a clear problem domain to address (not vague "make a skill")

• Problem domain has identifiable states (symptoms a user would notice)

• Some automation is possible (script + LLM split makes sense)

This Skill Does Not Handle

• Framework development (higher abstraction) - Route to: framework-development methodology

• Single-use scripts (no diagnostic model) - Route to: simple script writing

• Skills without states (pure generators) - Route to: generator template (simpler structure)

Degradation Signals

Signs this skill is being misapplied:

• Cannot identify 3+ distinct states for the problem space

• All "states" are really parameters to a single generator

• No connection to existing skills makes sense (orphan problem space)

• Problem space overlaps significantly with existing skill

Example: Building a New Skill

Request: "Create a skill for diagnosing dialogue problems"

Step 1: Identify Problem Space

Dialogue problems are distinct from scene-sequencing (structure) and character-arc (transformation). This is about how characters speak.

Step 2: Define States

• D1: No Dialogue (narrative summary only)

• D2: Same-Voice Characters (everyone sounds identical)

• D3: On-the-Nose Dialogue (no subtext)

• D4: Talking Heads (dialogue without context)

• D5: Functional-Only Dialogue (moves plot, reveals nothing)

Step 3: Design Tools

Script: voice-check.ts

• generates voice differentiation questionnaire Data: speech-patterns.json
• regional, class, personality markers

Step 4: Map Integrations

• From story-sense State 5.5 (dialogue-specific issues)

• To character-arc (voice reflects character growth)

• To worldbuilding (speech reflects culture)

Step 5: Generate Scaffolding

deno run --allow-read --allow-write scripts/scaffold.ts dialogue --type diagnostic

Output Persistence

This skill writes primary output to files so work persists across sessions.

Output Discovery

Before doing any other work:

• Check for context/output-config.md in the project

• If found, look for this skill's entry

• If not found or no entry for this skill, ask the user first:

• "Where should I save output from this skill-builder session?"

• Suggest: skills/{cluster}/{skill-name}/ as the standard skill location

• Store the user's preference:

• In context/output-config.md if context network exists

• In .skill-builder-output.md at project root otherwise

Primary Output

For this skill, persist:

• Skill scaffolding - SKILL.md, scripts/, templates/, data/

• State definitions - the diagnostic model

• Script templates - generated utility scripts

• Integration map - connections to other skills

Conversation vs. File

Goes to File Stays in Conversation

Generated SKILL.md Discussion of problem space

Script templates State definition iteration

Data file stubs Integration planning

Validation results Real-time feedback

File Naming

Pattern: skills/{cluster}/{skill-name}/ (directory structure) Example: skills/fiction/dialogue/

What You Do NOT Do

• You do not build skills without clear problem states

• You do not create scripts without SKILL.md documentation

• You do not duplicate existing skill coverage

• You do not skip integration mapping

• You build the framework; the user decides what skills to create

Integration with Other Skills

With list-builder (fiction cluster)

Use list-builder quality criteria for any data files:

• Validate list maturity before marking skill production-ready

• Follow dimensional frameworks for list variety

Cross-Cluster Skills

Skills can reference skills in other clusters:

• Document integration in both skills

• Use full path references when crossing clusters

Cluster Conventions

When building skills within a cluster:

• Set cluster in frontmatter to the parent skill

• Add integration tables mapping states between skills

• Follow the cluster's established patterns for scripts and data