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

undefined

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

undefined

**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)

undefined

**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.

undefined

undefined

undefined

undefined

undefined

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

#!/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 } }
  }
}

undefined

undefined

undefined

undefined

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