Skill Builder

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

---
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] |

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

metadata:

metadata:

metadata:
  maturity_score: 15

## Integration Graph

### Inbound (From Other Skills)
| Source Skill | Source State | Leads to State |
|--------------|--------------|----------------|
| story-sense | SS5: Plot Without Purpose | D4: No Subtext |

### Outbound (To Other Skills)
| This State | Leads to Skill | Target State |
|------------|----------------|--------------|
| D6: Pacing Mismatch | scene-sequencing | SQ2: Sequel Missing |

### Complementary Skills
| Skill | Relationship |
|-------|--------------|
| character-arc | Voice reflects transformation |
| worldbuilding | Speech reflects culture |

## 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"

## 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
| Task | Agent Type | When to Spawn |
|------|------------|---------------|
| Codebase exploration | Explore | When skill needs project context |
| Framework research | general-purpose | When synthesizing across 3+ frameworks |

## 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

### 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

#!/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();

// 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;
  }
}

// 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`;

// 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));
}

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

{
  "_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"]
    }
  }
}

{
  "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 } }
  }
}

# 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 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