skill-builder

Original source / Raw SKILL.md

---
name: skill-builder
type: standard
depth: full
description: Creates and edits Claude Code skills with YAML frontmatter, folder structure, and depth-scaled content. Use when building new skills, updating existing skills, designing SKILL.md metadata, organizing skill folders, validating skill structure, or adding Python and TypeScript scripts for deterministic operations.
---

# [H1][SKILL-BUILDER]
>**Dictum:** *Structured authoring produces discoverable, maintainable skills.*

<br>

Create and refine Claude Code skills via structured workflows.

**Tasks:**
1. Collect parameters — Scope: `create | refine`, Type: `simple | standard | complex`, Depth: `base | extended | full`
2. Read [frontmatter.md](./references/frontmatter.md) — Discovery metadata, trigger patterns
3. Read [structure.md](./references/structure.md) — Folder layout gated by Type
4. Read [depth.md](./references/depth.md) — LOC limits, nesting gated by Depth
5. (complex) Read [scripting.md](./references/scripting.md) — Automation standards
6. Capture requirements — purpose, triggers, outputs
7. Invoke `skill-summarizer` with skill `style-standards` — Extract voice, formatting, taxonomy
8. Invoke `deep-research` — Domain research for skill topic
9. Plan with 3 agents — file inventory, section structure, content framework
10. Execute per Scope:
    - (create) Author new artifacts; select template:
      - [simple](./templates/simple.skill.template.md) - DEFAULT
      - [standard](./templates/standard.skill.template.md)
      - [complex](./templates/complex.skill.template.md)
    - (refine) Compare input to existing frontmatter; see [refine.md](./references/workflows/refine.md):
      - Input = existing → optimize (density, fixes, quality)
      - Input > existing → upgrade (expand structure or depth)
      - Input < existing → downsize (combine, refactor, remove low-relevance)
11. Validate — Quality gate, LOC compliance, structure match

**Dependencies:**
- `deep-research` — Domain research via parallel agents
- `skill-summarizer` — Voice and formatting extraction (with skill `style-standards`)
- `report.md` — Sub-agent output format

[REFERENCE]: [index.md](./index.md) — Complete file listing

---
## [1][FRONTMATTER]
>**Dictum:** *Metadata enables discovery before loading.*

<br>

Frontmatter indexed at session start (~100 tokens). Description is ONLY field parsed for relevance—quality determines invocation accuracy.

**Guidance:**
- `Discovery` — LLM reasoning matches description to user intent. No embeddings, no keyword matching.
- `Trigger Density` — Include file types, operations, "Use when" clauses. Every word aids matching.
- `Voice` — Third person, active, present tense. Prohibit: 'could', 'might', 'probably', 'should'.

**Best-Practices:**
- **Length** — 1-2 sentences. Concise triggers outperform verbose explanations.
- **Classification** — Include `type` and `depth` fields for refine workflow detection.

---
## [2][STRUCTURE]
>**Dictum:** *Type determines breadth—folder existence defines capability scope.*

<br>

Type gates folder creation. Structure defines WHAT exists; Depth constrains HOW MUCH content.

| [INDEX] | [TYPE]   | [FOLDERS]                          |
| :-----: | -------- | ---------------------------------- |
|   [1]   | Simple   | SKILL.md only                      |
|   [2]   | Standard | +index.md, references/, templates/ |
|   [3]   | Complex  | +scripts/                          |

**Guidance:**
- `Naming` — Skill folder matches frontmatter `name` exactly. Kebab-case throughout.
- `Index` — Standard/Complex require index.md at root listing all reference files.
- `Upgrade Path` — Start with simplest type satisfying requirements.

**Best-Practices:**
- **Directory Purpose** — references/ for domain knowledge, templates/ for output scaffolds, scripts/ for automation.
- **File Limit** — Max 7 files in references/ (including nested).

---
## [3][DEPTH]
>**Dictum:** *Depth determines comprehensiveness—hard caps prevent bloat.*

<br>

Depth enforces LOC limits and nesting rights. Each level adds +50 SKILL.md, +25 reference files (cumulative).

| [INDEX] | [DEPTH]  | [SKILL.MD] | [REF_FILE] | [NESTING]      |
| :-----: | -------- | :--------: | :--------: | -------------- |
|   [1]   | Base     |    <300    |    <150    | Flat only      |
|   [2]   | Extended |    <350    |    <175    | 1 subfolder    |
|   [3]   | Full     |    <400    |    <200    | 1-3 subfolders |

**Guidance:**
- `Nesting Gate` — Subfolder requires 3+ related files OR distinct domain concern.
- `Content Scaling` — Base: 1-2 items per Guidance/Best-Practices. Extended: 2-4. Full: comprehensive.
- `LOC Optimization` — Density over deletion; see [depth.md§LOC_OPTIMIZATION](./references/depth.md).
- `Content Separation` — SKILL.md = WHY, references = HOW; see [depth.md§CONTENT_SEPARATION](./references/depth.md).

**Best-Practices:**
- **Hard Caps** — Exceeding limits requires refactoring, not justification.
- **No Brute-Force** — Consolidate → restructure → densify → prune (in order).

---
## [4][SCRIPTING]
>**Dictum:** *Deterministic automation extends LLM capabilities.*

<br>

Complex type enables scripts/ folder for external tool orchestration, artifact generation, validation.

**Guidance:**
- `Justification` — Script overhead demands explicit need: tool wrapping, exact reproducibility, schema enforcement.
- `Depth Scaling` — Base/Extended: single script. Full: multiple when distinct concerns justify.

**Best-Practices:**
- **Type Selection** — Standard suffices for most skills. Complex only when automation is core purpose.
- **Augmentation** — Scripts support workflows; core logic remains in SKILL.md and references.

---
## [5][TEMPLATES]
>**Dictum:** *Templates enforce canonical structure.*

<br>

Templates define output scaffolds. Agent combines user input with template skeleton for consistent artifacts.

**Guidance:**
- `Purpose` — Follow template exactly. No improvisation.
- `Composition` — Input data + template skeleton = generated artifact.

**Best-Practices:**
- **Placeholder Syntax** — Use `${variable-name}` for insertion points.
- **Structure Match** — Template complexity matches depth selection.

---
## [6][VALIDATION]
>**Dictum:** *Gates prevent incomplete artifacts.*

<br>

[VERIFY] Completion:
- [ ] Parameters: Scope, Type, Depth collected and applied.
- [ ] Research: `deep-research` completed fully before authoring.
- [ ] Style: `skill-summarizer` constraints applied to output.
- [ ] Workflow: Executed per Scope (create | refine).
- [ ] Quality: LOC within limits, content separation enforced.

[REFERENCE] Operational checklist: [→validation.md](./references/validation.md)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/frontmatter.md

```markdown
# [H1][FRONTMATTER]
>**Dictum:** *Metadata quality determines invocation accuracy.*

<br>

[IMPORTANT] Frontmatter indexed at session start. Description quality determines invocation accuracy.

---
## [1][SCHEMA]
>**Dictum:** *Two Claude Code fields; two classification fields.*

<br>

| [INDEX] | [FIELD]          | [TYPE]  | [REQ]  | [CONSTRAINT]                                              |
| :-----: | ---------------- | ------- | :----: | --------------------------------------------------------- |
|   [1]   | `name`           | string  |  Yes   | Lowercase+numbers+hyphens, max 64, no XML, no reserved^1^ |
|   [2]   | `description`    | string  |  Yes   | Non-empty, max 1024 chars, no XML tags                    |
|   [3]   | `type`           | enum    | Yes^2^ | `simple`, `standard`, `complex` — see structure.md        |
|   [4]   | `depth`          | enum    | Yes^2^ | `base`, `extended`, `full` — see depth.md                 |
|   [5]   | `model`          | string  |   No   | `opus*`, `sonnet`, `haiku`, or `inherit`                  |
|   [6]   | `context`        | enum    |   No   | `fork` — isolated execution, no shared parent state       |
|   [7]   | `agent`          | string  |   No   | Execution agent type override                             |
|   [8]   | `user-invocable` | boolean |   No   | `false` hides from slash menu                             |
|   [9]   | `hooks`          | object  |   No   | Scoped PreToolUse, PostToolUse, Stop hooks                |

^1^Reserved: "anthropic", "claude" — registration fails.
^2^Required by skill-builder for refine workflow.

[CRITICAL]:
- [NEVER] Use `allowed-tools`—strictly forbidden.
- [ALWAYS] Include `type` and `depth`—enables refine classification.

---
### [1.1][NAME]
>**Dictum:** *Identifier enables registration and folder matching.*

<br>

| [INDEX] | [VALID]         | [INVALID]       |
| :-----: | --------------- | --------------- |
|   [1]   | `pdf-processor` | `PDF_Processor` |
|   [2]   | `mcp-builder`   | `mcp.builder`   |
|   [3]   | `code-reviewer` | `code reviewer` |

**Naming Form:** Gerund preferred (`processing-pdfs`), noun phrase (`pdf-processing`), or action verb (`process-pdfs`).

[IMPORTANT]:
- [ALWAYS] Lowercase letters, numbers, hyphens only.
- [ALWAYS] Match containing folder name exactly.

[CRITICAL]:
- [NEVER] XML tags, reserved words (`anthropic`, `claude`), vague names (`helper`, `utils`).

---
### [1.2][DESCRIPTION]
>**Dictum:** *Trigger sentence determines discovery.*

<br>

[CRITICAL] Description is PRIMARY discovery mechanism. LLM reasoning matches user intent—no embeddings, no keyword matching.

**Voice:** Third person, active, present tense. Prohibit: "might", "could", "typically".<br>
**Structure:** `[Capability statement]. Use when [trigger 1], [trigger 2], or [trigger 3].`<br>
**Token Economics:** ~100 tokens at startup (name + description only). SKILL.md loads on relevance match.

---
## [2][TRIGGERS]
>**Dictum:** *Explicit triggers maximize discovery accuracy.*

<br>

### [2.1][PATTERNS]

| [INDEX] | [PATTERN]            | [EXAMPLE]                                    | [MECHANISM]               |
| :-----: | -------------------- | -------------------------------------------- | ------------------------- |
|   [1]   | "Use when" clause    | `Use when building MCP servers`              | Direct activation signal  |
|   [2]   | Enumerated scenarios | `(1) creating, (2) modifying, (3) analyzing` | Parallel pattern matching |
|   [3]   | Technology embedding | `Python (FastMCP) or TypeScript (SDK)`       | Framework-specific        |
|   [4]   | File extension       | `working with PDF files (.pdf)`              | Path-based triggering     |
|   [5]   | Catch-all            | `or any other document tasks`                | Broadens applicability    |

### [2.2][ANTI_PATTERNS]

| [INDEX] | [ANTI_PATTERN]       | [PROBLEM]                        | [FIX]                        |
| :-----: | -------------------- | -------------------------------- | ---------------------------- |
|   [1]   | Vague description    | `Helps with documents`           | Add specifics + "Use when"   |
|   [2]   | Implementation focus | `Uses Python library docx-js...` | Describe WHEN, not HOW       |
|   [3]   | First/second person  | `I help you create...`           | Third person: "Creates..."   |
|   [4]   | Missing file types   | `Work with Word documents`       | Include extension: `(.docx)` |

---
## [3][SYNTAX]
>**Dictum:** *YAML parsing constraints prevent registration failure.*

<br>

| [INDEX] | [CONSTRAINT]             | [VIOLATION]                | [RESULT]              |
| :-----: | ------------------------ | -------------------------- | --------------------- |
|   [1]   | `---` on line 1          | Content before delimiter   | Skill not discovered  |
|   [2]   | `---` closes on own line | Missing closing delimiter  | YAML parse failure    |
|   [3]   | Spaces only (no tabs)    | Tab indentation            | Parse error           |
|   [4]   | Quote special characters | Unquoted `: # @ \| >`      | Field value corrupted |
|   [5]   | Name matches folder      | `name` differs from folder | Registration failure  |
|   [6]   | Use `>-` for multi-line  | Literal scalar `\|`        | Indexing error        |

**Multi-line:** Folded scalar `>-` renders as single line:
```yaml
description: >-
  Comprehensive document processing. Use when working with PDF files,
  Word documents, or spreadsheets.
```

[REFERENCE] Frontmatter validation checklist: [→validation.md§2](./validation.md#2frontmatter)

```

### references/structure.md

```markdown
# [H1][STRUCTURE]
>**Dictum:** *Type determines breadth—folder existence defines capability scope.*

<br>

[IMPORTANT] Structure defines folder existence. Depth constrains folder contents.

---
## [1][TYPE_IMPACT]
>**Dictum:** *Type gates folder creation—each level adds capability.*

<br>

| [INDEX] | [TYPE]   | [SKILL.MD] | [INDEX.MD] | [REFERENCES/] | [TEMPLATES/] | [SCRIPTS/] |
| :-----: | -------- | :--------: | :--------: | :-----------: | :----------: | :--------: |
|   [1]   | Simple   |    Yes     |     —      |       —       |      —       |     —      |
|   [2]   | Standard |    Yes     |    Yes     |      Yes      |     Yes      |     —      |
|   [3]   | Complex  |    Yes     |    Yes     |      Yes      |     Yes      |    Yes     |

**Simple:** Single file. All content in SKILL.md. No supporting folders. Sections map to workflow steps.<br>
**Standard:** Distributed content. references/ for deep knowledge, templates/ for output scaffolds. Domains map to reference files.<br>
**Complex:** Standard + scripts/ for deterministic automation.

[CRITICAL] Create only folders appropriate to type. Empty folders prohibited.

---
## [2][FOLDER_PURPOSE]
>**Dictum:** *Each folder serves distinct function.*

<br>

| [INDEX] | [FOLDER]      | [PURPOSE]                | [CONTENTS]                          |
| :-----: | ------------- | ------------------------ | ----------------------------------- |
|   [1]   | `/`           | Skill root               | SKILL.md, index.md                  |
|   [2]   | `references/` | Domain knowledge         | Tables, examples, deep explanations |
|   [3]   | `templates/`  | Output scaffolds         | `${placeholder}` syntax, structure  |
|   [4]   | `scripts/`    | Deterministic automation | Python/TypeScript executables       |

**references/** — Content too detailed for SKILL.md. On-demand loading via Required/Conditional Tasks. Must include validation.md.<br>
**templates/** — Source of truth for generated artifacts. Follow template exactly.<br>
**scripts/** — Operations requiring exact reproducibility. External tool wrapping, automation.

[CRITICAL] Max 7 files in references/ (Standard/Complex).

---
## [3][NAMING]
>**Dictum:** *Naming conventions enable rapid discovery.*

<br>

| [INDEX] | [CONTEXT]      | [PATTERN]                     | [EXAMPLE]                    |
| :-----: | -------------- | ----------------------------- | ---------------------------- |
|   [1]   | Skill folder   | `{skill-name}/`               | `skill-builder/`             |
|   [2]   | Reference file | `{domain}.md`                 | `frontmatter.md`, `depth.md` |
|   [3]   | Subfolder      | `{domain}/`                   | `taxonomy/`, `voice/`        |
|   [4]   | Subfolder file | `{topic}.md`                  | `lexicon.md`, `grammar.md`   |
|   [5]   | Template file  | `{type}.{output}.template.md` | `simple.skill.template.md`   |
|   [6]   | Script file    | `{verb}-{noun}.{ext}`         | `validate-prompt.py`         |

[IMPORTANT]:
- [ALWAYS] Kebab-case for all files and folders.
- [ALWAYS] Domain-specific names reflecting content purpose.
- [ALWAYS] Skill folder name matches frontmatter `name` field exactly.

[CRITICAL]:
- [NEVER] Generic names: `utils.md`, `helpers.md`, `misc.md`, `common.md`.
- [NEVER] Numeric prefixes: `01-intro.md`, `02-setup.md`.

---
## [4][INDEX_FILE]
>**Dictum:** *index.md provides single navigation source.*

<br>

Standard/Complex types require index.md at skill root.

**Requirements:**
- Located at skill root, not in subfolders.
- Lists ALL reference files with path, domain, and dictum.
- Single navigation source—no per-folder indexes.

**Format:**
```markdown
| [INDEX] | [DOMAIN] | [PATH]                         | [DICTUM]           |
| :-----: | -------- | ------------------------------ | ------------------ |
|   [1]   | Domain   | [→file.md](references/file.md) | Brief description. |
```

[REFERENCE] Nesting rights by depth: [→depth.md§2](./depth.md#2unlocks)

---
## [5][VALIDATION_FILE]
>**Dictum:** *validation.md centralizes operational checklists.*

<br>

Standard/Complex types require validation.md in references/.

**Purpose:**
- Consolidates operational verification checklists from all domains.
- SKILL.md §VALIDATION contains high-level gates (3-5 items).
- validation.md contains detailed checklists, error symptoms, commands.

**Requirements:**
- Located at `references/validation.md`.
- Sections map to domain concerns (frontmatter, structure, depth, scripting).
- Includes error symptoms table for diagnosis.
- Operational commands for verification (`wc -l`, `grep`, etc.).

**Simple type exception:** Validation remains in SKILL.md §VALIDATION (no references/ folder).

[REFERENCE] Validation content guidelines: [→validation.md](./validation.md)

```

### references/depth.md

```markdown
# [H1][DEPTH]
>**Dictum:** *Depth gates LOC—scales with selection.*

<br>

[IMPORTANT] Depth prevents bloat through hard caps. Each level adds +50 LOC to SKILL.md, +25 LOC to reference files (cumulative).

---
## [1][LIMITS]
>**Dictum:** *Hard caps enforce quality through constraint.*

<br>

| [INDEX] | [DEPTH]  | [SKILL.MD] | [REF_FILE] |
| :-----: | -------- | :--------: | :--------: |
|   [1]   | Base     |    <300    |    <150    |
|   [2]   | Extended |    <350    |    <175    |
|   [3]   | Full     |    <400    |    <200    |

[CRITICAL] Exceeding limits requires refactoring, not justification. No exceptions.

[REFERENCE] File count limit: Max 7 files in references/ — see [→structure.md§2](./structure.md#2folder_purpose)

---
## [2][UNLOCKS]
>**Dictum:** *Each depth level scales content density.*

<br>

| [INDEX] | [DEPTH]  | [NESTING]      | [GUIDANCE] | [BEST-PRACTICES] |
| :-----: | -------- | -------------- | :--------: | :--------------: |
|   [1]   | Base     | Flat only      | 1-2 items  |    1-2 items     |
|   [2]   | Extended | 1 subfolder    | 2-4 items  |    3-4 items     |
|   [3]   | Full     | 1-3 subfolders |  4+ items  |  Comprehensive   |

### [2.1][NESTING]

Nesting rights apply to Standard/Complex types only. Simple type has no folders.

**Flat (Base):**
- All reference files directly at `references/` root.
- No subfolders permitted.

**Nested (Extended):**
- ONE subfolder permitted.
- Identify most essential domain (becomes subfolder).

**Nested (Full):**
- 1-3 subfolders permitted.
- Subfolder requires 3+ related files OR distinct domain concern.

[CRITICAL] Folder creation requires semantic grouping. Content volume alone: insufficient.

---
### [2.2][SECTIONS]

All domain sections include Guidance and Best-Practices. Depth scales content density.

**Base:**
- Guidance: 1-2 core concepts. Essential "why" only.
- Best-Practices: 1-2 critical constraints. No exhaustive lists.

**Extended:**
- Guidance: 2-4 concepts with moderate rationale.
- Best-Practices: 3-4 items covering primary patterns.

**Full:**
- Guidance: Comprehensive coverage with detailed rationale.
- Best-Practices: Exhaustive patterns and constraints.

[IMPORTANT] Simple type: All content inline in sections. Standard/Complex: Guidance in SKILL.md, detailed content in references/.

---
## [3][LOC_OPTIMIZATION]
>**Dictum:** *Density over deletion—retain all semantic value.*

<br>

[CRITICAL] Brute-force trimming is PROHIBITED. Cutting content to meet LOC limits without optimization destroys value.

**Optimization sequence:**
1. **Consolidate** — Identify repeated information across files; keep in ONE location, remove elsewhere
2. **Restructure** — Find better organization to reduce redundant tables, headers, boilerplate
3. **Densify** — Rewrite lines for maximum information per token; explicit, no filler
4. **Prune** — Remove ONLY low-impact/low-value content after above steps exhausted

**Quality signals:**
- Every line provides unique value
- No repeated concepts across sections
- Tables consolidated where patterns overlap
- Instructions dense, explicit, no filler phrasing

[IMPORTANT] High-quality skills achieve maximum value within LOC limits. Constraint drives density, not reduction.

---
## [4][CONTENT_SEPARATION]
>**Dictum:** *SKILL.md builds ON references—never copies.*

<br>

**SKILL.md contains:**
- Tasks — Sequential actions with links
- Domain sections — WHY (rationale, guidance, best-practices)
- Summary-level information that references detailed content

**Reference files contain:**
- HOW — Detailed specifications, tables, schemas
- Deep knowledge — Implementation details, patterns, examples
- Content exceeding 10 lines in SKILL.md

**Section quality gate:**
- Guidance = core concepts explaining WHY something matters
- Best-Practices = constraints/patterns that BUILD ON reference content
- NEVER copy/re-iterate reference content verbatim
- ALWAYS provide additive value beyond what references contain

[CRITICAL] Even simple skills without references: sections must be high-impact, crafted with care. No boilerplate. Every item earns its LOC.

[REFERENCE] Depth validation checklist: [→validation.md§4](./validation.md#4depth)

```

### references/scripting.md

```markdown
# [H1][SCRIPTING]
>**Dictum:** *Scripts enforce deterministic operations.*

<br>

Scripts extend skill capabilities with executable automation. Required for: CLI tooling, exact reproducibility, tool orchestration.

---
## [1][CRITERIA]
>**Dictum:** *Clear boundaries prevent unnecessary scripting overhead.*

<br>

| [INDEX] | [INCLUDE]                    | [EXCLUDE]               |
| :-----: | ---------------------------- | ----------------------- |
|   [1]   | External tool orchestration  | Simple transformations  |
|   [2]   | File generation/scaffolding  | Context-dependent logic |
|   [3]   | CLI tooling for skill users  | One-time operations     |
|   [4]   | Exact reproducibility needed | LLM-suitable tasks      |

---
## [2][STANDARDS]
>**Dictum:** *Scripts embody project philosophy in minimal surface area.*

<br>

**Purpose:**
- *Orchestration:* Wrap external tools (protoc, pandoc, prisma) for downstream skill workflows.
- *Generation:* Scaffold artifacts requiring exact structure (OpenAPI specs, database migrations).
- *Validation:* Enforce constraints beyond LLM generation (schema compliance, AST transforms).

**Tooling:**
- *Python:* 3.14+ with `slots=True`, `Final`, type hints. Standard library first.
- *TypeScript:* 6.0+ with Effect 3.19+, ESM imports, `satisfies` for exhaustiveness.

**Philosophy:**
- *Algorithmic:* Derive values from frozen `B` constant.
- *Polymorphic:* Route variants through dispatch tables.
- *Functional:* Compose via `pipe`, Effect pipelines, Option monads.
- *Expression-Centric:* Ternaries over conditionals, implicit returns.

**Density:**<br>
Maximum functionality in minimum LOC. Single script addresses single concern. No wrapper abstractions.

[REFERENCE] Script validation checklist: [→validation.md§5](./validation.md#5scripting)

---
## [3][PYTHON]
>**Dictum:** *Frozen config with dispatch tables maximizes portability.*

<br>

```python
#!/usr/bin/env -S uv run --quiet --script
# /// script
# ///
"""Transform input through format-specific handlers."""

# --- [IMPORTS] ----------------------------------------------------------------
import argparse
import json
import sys
from collections.abc import Callable
from dataclasses import dataclass
from pathlib import Path
from typing import Final

# --- [TYPES] ------------------------------------------------------------------
type Data = dict[str, object]
type Handler = Callable[[Data], Data]

# --- [CONSTANTS] --------------------------------------------------------------
@dataclass(frozen=True, slots=True)
class _B:
    indent: int = 2
    encoding: str = "utf-8"

B: Final[_B] = _B()

# --- [PURE_FUNCTIONS] ---------------------------------------------------------
# (stateless utilities would go here)

# --- [DISPATCH_TABLES] --------------------------------------------------------
handlers: dict[str, Handler] = {
    "upper": lambda d: {k: (v.upper() if isinstance(v, str) else v) for k, v in d.items()},
    "lower": lambda d: {k: (v.lower() if isinstance(v, str) else v) for k, v in d.items()},
    "keys": lambda d: {"keys": list(d.keys())},
}

# --- [ENTRY_POINT] ------------------------------------------------------------
def main() -> int:
    p = argparse.ArgumentParser(description=__doc__)
    [p.add_argument(a, **o) for a, o in [
        ("-i", {"dest": "input", "type": Path, "required": True}),
        ("-o", {"dest": "output", "type": Path}),
        ("-m", {"dest": "mode", "choices": handlers.keys(), "default": "upper"}),
    ]]
    a = p.parse_args()
    data = json.loads(a.input.read_text(B.encoding))
    result = json.dumps({"status": "success", "data": handlers[a.mode](data)}, indent=B.indent)
    _ = a.output.write_text(result, encoding=B.encoding) if a.output else print(result)
    return 0

if __name__ == "__main__":
    sys.exit(main())
```

---
## [4][TYPESCRIPT]
>**Dictum:** *Effect pipelines with Schema validation ensure composability.*

<br>

```typescript
#!/usr/bin/env npx tsx
import { Effect, pipe, Option, Schema } from "effect";
import { readFile, writeFile } from "node:fs/promises";
import { parseArgs } from "node:util";

const B = Object.freeze({ indent: 2, encoding: "utf-8" } as const);

const Mode = Schema.Literal("upper", "lower", "keys");
type Mode = typeof Mode.Type;

class FileError { readonly _tag = "FileError"; constructor(readonly path: string) {} }
class ParseError { readonly _tag = "ParseError"; constructor(readonly reason: string) {} }

const handlers = {
    upper: (d: Record<string, unknown>) => Object.fromEntries(Object.entries(d).map(([k, v]) => [k, typeof v === "string" ? v.toUpperCase() : v])),
    lower: (d: Record<string, unknown>) => Object.fromEntries(Object.entries(d).map(([k, v]) => [k, typeof v === "string" ? v.toLowerCase() : v])),
    keys: (d: Record<string, unknown>) => ({ keys: Object.keys(d) }),
} as const satisfies Record<Mode, (d: Record<string, unknown>) => unknown>;

const run = (input: string, output: Option.Option<string>, mode: Mode) =>
    pipe(
        Effect.tryPromise({ try: () => readFile(input, B.encoding), catch: () => new FileError(input) }),
        Effect.flatMap((c) => Effect.try({ try: () => JSON.parse(c), catch: () => new ParseError("Invalid JSON") })),
        Effect.flatMap((d) => Effect.try({ try: () => Schema.decodeUnknownSync(Schema.Record({ key: Schema.String, value: Schema.Unknown }))(d), catch: () => new ParseError("Invalid structure") })),
        Effect.map((data) => JSON.stringify({ status: "success", data: handlers[mode](data) }, null, B.indent)),
        Effect.flatMap((json) => Option.match(output, {
            onNone: () => Effect.sync(() => console.log(json)),
            onSome: (p) => Effect.tryPromise({ try: () => writeFile(p, json), catch: () => new FileError(p) }),
        }))
    );

const { values: v } = parseArgs({ options: { input: { type: "string", short: "i" }, output: { type: "string", short: "o" }, mode: { type: "string", short: "m", default: "upper" }, help: { type: "boolean", short: "h" } } });
v.help ? console.log("Usage: transform.ts -i <input> [-o <output>] [-m upper|lower|keys]") : Effect.runPromise(run(v.input!, Option.fromNullable(v.output), Schema.decodeSync(Mode)(v.mode)));
```

---
## [5][ORGANIZATION]
>**Dictum:** *Consistent naming enables rapid discovery.*

<br>

| [INDEX] | [PREFIX]     | [PURPOSE]             |
| :-----: | ------------ | --------------------- |
|   [1]   | `generate-`  | Creation, scaffolding |
|   [2]   | `validate-`  | Verification, checks  |
|   [3]   | `transform-` | Data conversion       |
|   [4]   | `run-`       | External tool wrapper |

[IMPORTANT]:
- [ALWAYS] Support `--help` for discoverability.
- [ALWAYS] JSON output for agent parsing.
- [ALWAYS] Document external tool dependencies in script header.

```

### templates/simple.skill.template.md

```markdown
---
name: ${kebab-case-name}
type: simple
depth: ${base|extended}
# context: fork
# user-invocable: false
# agent: Explore
description: ${action-verb-capability}. Use when ${scenario-1}, ${scenario-2}, or ${scenario-3}.
---

# [H1][${NAME}]
>**Dictum:** *${core-truth-one-sentence}.*

<br>

${one-sentence-purpose}

**Workflow:**
1. §${STEP_1} — ${step-1-action}
2. §${STEP_2} — ${step-2-action}
3. §${STEP_N} — ${step-n-action}

**Dependencies:** ${remove-if-none}
- `${skill-name}` — ${purpose}

**Input:** ${remove-if-none}
- `${param}`: ${description}

**Exclusions:** ${remove-if-none} ${comma-separated-exclusions}

---
## [1][${STEP_1}]
>**Dictum:** *${step-principle}.*

<br>

${step-context-and-purpose}

${content: tables, code blocks, bullet lists as needed}

[IMPORTANT]: ${remove-if-not-needed}
- [ALWAYS] ${positive-rule}.
- [NEVER] ${negative-rule}.

[VERIFY] ${gate-name}: ${inline-gate-for-decision-points-only}
- [ ] ${precondition-before-expensive-operation}

---
## [2][${STEP_2}]
>**Dictum:** *${step-principle}.*

<br>

${step-context-and-purpose}

${content: tables, code blocks, bullet lists as needed}

[CRITICAL]: ${remove-if-not-needed}
- [ALWAYS] ${critical-rule}.

---
## [N][${STEP_N}]
>**Dictum:** *${step-principle}.*

<br>

${step-context-and-purpose}

${content: subsections [N.1], [N.2] if needed for complex steps}

---
## [N+1][VALIDATION]
>**Dictum:** *Gates prevent incomplete execution.*

<br>

[VERIFY] Completion:
- [ ] ${step-1}: ${observable-outcome}
- [ ] ${step-2}: ${observable-outcome}
- [ ] ${step-n}: ${observable-outcome}
- [ ] Quality: ${domain-specific-quality-gate}

```

### templates/standard.skill.template.md

```markdown
---
name: ${kebab-case-name}
type: standard
depth: ${base|extended|full}
# context: fork
# user-invocable: false
# agent: Explore
description: ${action-verb-capability}. Use when ${scenario-1}, ${scenario-2}, or ${scenario-3}.
---

# [H1][${NAME}]
>**Dictum:** *${core-truth-one-sentence}.*

<br>

${one-sentence-purpose}

**Tasks:**
1. Read [index.md](./index.md) — Reference file listing for navigation
2. Read [${domain-1}.md](./references/${domain-1}.md) — ${domain-1-description}
3. Read [${domain-n}.md](./references/${domain-n}.md) — ${domain-n-description}
4. (${condition}) Read [${conditional}.md](./references/${conditional}.md) — ${conditional-description}
5. (prose) Load `style-standards` skill — Voice, formatting, constraints
6. Execute per ${workflow} — ${workflow-phases}
7. Validate — Quality gate; see §VALIDATION

**Scope:** ${remove-if-not-needed}
- *${Scope-1}:* ${what-this-covers}.
- *${Scope-N}:* ${what-this-covers}.

**Domain Navigation:** ${remove-if-not-needed}
- *[${DOMAIN_1}]* — ${domain-summary}. Load when ${trigger}.
- *[${DOMAIN_N}]* — ${domain-summary}. Load when ${trigger}.

**Templates:** ${remove-if-not-needed} [→${template}.md](./templates/${template}.md) — ${template-purpose}.

**Dependencies:** ${remove-if-none}
- `${skill-name}` — ${purpose}

[REFERENCE]: [index.md](./index.md) — Complete reference file listing

---
## [1][${DOMAIN_1}]
>**Dictum:** *${domain-truth}.*

<br>

${domain-context-sentence-explaining-why}

${optional: decision gate, tables, or key concepts}

**Guidance:**
- `${Concept}` — ${why-it-matters}.

**Best-Practices:** ${remove-if-not-needed}
- **${Pattern}** — ${constraint-or-rule}.

---
## [N][${DOMAIN_N}]
>**Dictum:** *${domain-truth}.*

<br>

${domain-context-sentence-explaining-why}

**Guidance:**
- `${Concept}` — ${why-it-matters}.

**Best-Practices:** ${remove-if-not-needed}
- **${Pattern}** — ${constraint-or-rule}.

---
## [N+1][VALIDATION]
>**Dictum:** *Gates prevent incomplete execution.*

<br>

[VERIFY] Completion:
- [ ] References: All required domain files loaded per Tasks.
- [ ] Workflow: ${workflow} phases executed.
- [ ] Style: `style-standards` constraints applied.
- [ ] Quality: LOC within limits, content separation enforced.

[REFERENCE] Operational checklist: [→validation.md](./references/validation.md)

```

### templates/complex.skill.template.md

```markdown
---
name: ${kebab-case-name}
type: complex
depth: ${extended|full}
# context: fork
# user-invocable: false
# agent: Explore
description: ${action-verb-capability}. Use when ${scenario-1}, ${scenario-2}, or ${scenario-3}.
---

# [H1][${NAME}]
>**Dictum:** *${core-truth-one-sentence}.*

<br>

${one-sentence-purpose}

**Tasks:**
1. Collect parameters — ${param-1}: `${options}`, ${param-n}: `${options}`
2. Read [index.md](./index.md) — Reference file listing for navigation
3. Read [${domain-1}.md](./references/${domain-1}.md) — ${domain-1-description}
4. Read [${domain-n}.md](./references/${domain-n}.md) — ${domain-n-description}
5. (scripting) Read [scripting.md](./references/scripting.md) — Automation standards
6. (prose) Load `style-standards` skill — Voice, formatting, constraints
7. Execute per ${workflow}:
   - (${param-value-1}) ${action} — see [${workflow-1}.md](./references/workflows/${workflow-1}.md)
   - (${param-value-n}) ${action} — see [${workflow-n}.md](./references/workflows/${workflow-n}.md)
8. Validate — Quality gate; see §VALIDATION

**Dependencies:**
- `${skill-name}` — ${purpose}
- `${output-style}` — Sub-agent output format

[REFERENCE]: [index.md](./index.md) — Complete file listing

---
## [1][${DOMAIN_1}]
>**Dictum:** *${domain-truth}.*

<br>

${domain-context-sentence-explaining-why}

${tables, key concepts, decision gates as needed}

**Guidance:**
- `${Concept}` — ${why-it-matters}.
- `${Concept}` — ${why-it-matters}.

**Best-Practices:**
- **${Pattern}** — ${constraint-or-rule}.

---
## [2][${DOMAIN_N}]
>**Dictum:** *${domain-truth}.*

<br>

${domain-context-sentence-explaining-why}

**Guidance:**
- `${Concept}` — ${why-it-matters}.

**Best-Practices:**
- **${Pattern}** — ${constraint-or-rule}.

---
## [N][SCRIPTING]
>**Dictum:** *Deterministic automation extends LLM capabilities.*

<br>

scripts/ folder for external tool orchestration, artifact generation, validation.

**Guidance:**
- `Justification` — Script overhead demands explicit need: tool wrapping, reproducibility, schema enforcement.
- `Standards` — Python 3.14+/TypeScript 6.0+, frozen config, dispatch tables, JSON output.

**Best-Practices:**
- **Augmentation** — Scripts support workflows; core logic remains in SKILL.md and references.

---
## [N+1][VALIDATION]
>**Dictum:** *Gates prevent incomplete execution.*

<br>

[VERIFY] Completion:
- [ ] Parameters: ${param-list} collected and applied.
- [ ] References: All required domain files loaded per Tasks.
- [ ] Workflow: ${workflow} executed per parameter fork.
- [ ] Style: `style-standards` constraints applied.
- [ ] Quality: LOC within limits, content separation enforced.

[REFERENCE] Operational checklist: [→validation.md](./references/validation.md)

```

### references/workflows/refine.md

```markdown
# [H1][WORKFLOW_REFINE]
>**Dictum:** *Research-driven transformation without semantic loss.*

<br>

Refine scope: compare `deep-research` findings to existing skill, apply changes based on input vs frontmatter.

[CRITICAL] `deep-research` MUST complete fully before comparison. Sub-agents use `report.md` output format per SKILL.md Task 7.

---
## [1][COMPARISON_MODES]
>**Dictum:** *Input/frontmatter delta determines action.*

<br>

| [INDEX] | [CONDITION]      | [MODE]   | [ACTION]                                     |
| :-----: | ---------------- | -------- | -------------------------------------------- |
|   [1]   | Input = existing | Optimize | Improve density, fix issues, enhance quality |
|   [2]   | Input > existing | Upgrade  | Expand structure (type) or depth             |
|   [3]   | Input < existing | Downsize | Combine content, refactor, remove low-value  |

---
## [2][GAP_CATEGORIES]
>**Dictum:** *Gap analysis drives surgical planning.*

<br>

| [INDEX] | [CATEGORY] | [SIGNALS]                                |
| :-----: | ---------- | ---------------------------------------- |
|   [1]   | Missing    | Research reveals undocumented capability |
|   [2]   | Incorrect  | Existing content contradicts research    |
|   [3]   | Outdated   | Deprecated patterns, superseded APIs     |
|   [4]   | Redundant  | SKILL.md duplicates reference content    |
|   [5]   | Tiered     | Basic/advanced/expert language present   |

---
## [3][PRIORITY_RANKING]
>**Dictum:** *Fix order maximizes impact.*

<br>

| [INDEX] | [PRIORITY] | [CLASS]         | [ACTION]                         |
| :-----: | :--------: | --------------- | -------------------------------- |
|   [1]   |     0      | Incorrect       | Fix immediately—misinformation   |
|   [2]   |     1      | Tiered language | Remove—violates singular quality |
|   [3]   |     2      | Redundant       | Consolidate—no duplication       |
|   [4]   |     3      | Outdated        | Update with research findings    |
|   [5]   |     4      | Missing         | Add if within LOC headroom       |

---
## [4][EXECUTION_ORDER]
>**Dictum:** *Surgical first, rewrites second, quality last.*

<br>

**Phase 1 (Surgical):** Small, targeted changes
- Add missing fields, matchers, values
- Correct inaccuracies with authoritative sources
- Remove deprecated patterns

**Phase 2 (Rewrite):** Research-driven restructuring
- Apply when surgical insufficient
- Maintain semantic content

**Phase 3 (Quality):** Final pass
- Remove all tiered language
- Verify LOC within limits
- Ensure SKILL.md builds FROM references

[IMPORTANT]:
- [ALWAYS] Compress representation, not meaning
- [NEVER] Delete semantic content—refactor for density

```

### index.md

```markdown
# [H1][INDEX]
>**Dictum:** *Centralized index enables rapid reference discovery.*

<br>

| [INDEX] | [DOMAIN]    | [PATH]                                                              | [DICTUM]                                        |
| :-----: | ----------- | ------------------------------------------------------------------- | ----------------------------------------------- |
|   [1]   | Workflow    | [→create.md](references/workflows/create.md)                        | Sequential phases prevent incomplete artifacts. |
|   [2]   | Workflow    | [→refine.md](references/workflows/refine.md)                        | Surgical transformation preserves semantics.    |
|   [3]   | Structure   | [→structure.md](references/structure.md)                            | Type determines breadth.                        |
|   [4]   | Depth       | [→depth.md](references/depth.md)                                    | Depth gates LOC—scales with selection.          |
|   [5]   | Frontmatter | [→frontmatter.md](references/frontmatter.md)                        | Schema and trigger optimization for discovery.  |
|   [6]   | Scripting   | [→scripting.md](references/scripting.md)                            | Scripts enforce deterministic operations.       |
|   [7]   | Validation  | [→validation.md](references/validation.md)                          | Operational criteria verify execution quality.  |
|   [8]   | Template    | [→simple.skill.template.md](templates/simple.skill.template.md)     | Minimal skill scaffold.                         |
|   [9]   | Template    | [→standard.skill.template.md](templates/standard.skill.template.md) | Reference-backed skill scaffold.                |
|  [10]   | Template    | [→complex.skill.template.md](templates/complex.skill.template.md)   | Multi-domain skill scaffold.                    |

```

### references/validation.md

```markdown
# [H1][VALIDATION]
>**Dictum:** *Operational criteria verify execution quality.*

<br>

Consolidated checklist for skill-builder workflows. SKILL.md §VALIDATION contains high-level gates; this file contains operational verification procedures.

---
## [1][PHASE_GATES]
>**Dictum:** *Workflow phases require sequential verification.*

<br>

| [INDEX] | [PHASE]    | [GATE]                 | [VERIFICATION]                                       |
| :-----: | ---------- | ---------------------- | ---------------------------------------------------- |
|   [1]   | Parameters | Collection complete    | Scope, Type, Depth captured before reference loading |
|   [2]   | References | All required loaded    | frontmatter.md, structure.md, depth.md read          |
|   [3]   | Research   | deep-research complete | Both rounds + critiques finished, findings captured  |
|   [4]   | Style      | skill-summarizer run   | Voice/formatting extracted from style-standards      |
|   [5]   | Execute    | Workflow scope matched | create OR refine path executed per Scope parameter   |
|   [6]   | Artifacts  | All files generated    | SKILL.md + type-appropriate folders created          |

---
## [2][FRONTMATTER]
>**Dictum:** *Discovery metadata gates skill registration.*

<br>

[VERIFY] Frontmatter compliance:
- [ ] Delimiters: `---` on line 1; closing `---` before markdown content.
- [ ] `name`: lowercase+hyphens only; max 64 chars; matches folder name exactly; no XML tags; no reserved words (`anthropic`, `claude`).
- [ ] `description`: non-empty; max 1024 chars; no XML tags; third person/active/present tense.
- [ ] `description`: contains "Use when" clause with specific triggers + file types/extensions.
- [ ] `type`: valid enum (`simple`, `standard`, `complex`); matches folder structure.
- [ ] `depth`: valid enum (`base`, `extended`, `full`); matches LOC and nesting.
- [ ] Syntax: spaces only (no tabs); special characters quoted; `>-` for multi-line descriptions.

---
## [3][STRUCTURE]
>**Dictum:** *Type gates folder existence.*

<br>

[VERIFY] Structural compliance:
- [ ] Type selected and documented in frontmatter.
- [ ] Folders match type:
  - Simple: SKILL.md only (no references/, templates/, scripts/).
  - Standard: SKILL.md + index.md + references/ + templates/.
  - Complex: Standard + scripts/.
- [ ] No empty folders—every folder contains at least one file.
- [ ] Skill folder name matches frontmatter `name` exactly.
- [ ] `references/` contains ≤7 files total (including nested subfolders).
- [ ] `index.md` exists at skill root (Standard/Complex only).
- [ ] All file and folder names are kebab-case, domain-specific (no `utils.md`, `helpers.md`).

---
## [4][DEPTH]
>**Dictum:** *LOC limits enforce density over deletion.*

<br>

[VERIFY] Depth compliance:
- [ ] Depth selected and documented in frontmatter.
- [ ] SKILL.md within LOC limit: Base <300, Extended <350, Full <400.
- [ ] All reference files within LOC limit: Base <150, Extended <175, Full <200.
- [ ] Subfolder count matches depth: Base = 0, Extended ≤1, Full ≤3.
- [ ] Guidance/Best-Practices item count scales with depth (Base: 1-2, Extended: 2-4, Full: comprehensive).

[VERIFY] LOC optimization applied (in order):
1. [ ] Consolidate — repeated information exists in ONE location only.
2. [ ] Restructure — organization reduces redundant tables/headers/boilerplate.
3. [ ] Densify — lines rewritten for maximum information per token.
4. [ ] Prune — low-impact content removed ONLY after above steps exhausted.

[VERIFY] Content separation enforced:
- [ ] SKILL.md contains WHY (Tasks, Guidance, Best-Practices).
- [ ] References contain HOW (specs, tables, schemas, examples).
- [ ] SKILL.md sections build ON references—no verbatim duplication.

---
## [5][SCRIPTING]
>**Dictum:** *Scripts require additional quality gates.*

<br>

[VERIFY] Script quality (Complex type only):
- [ ] Frozen `B` constant consolidates all tunables.
- [ ] Dispatch table routes all mode variants.
- [ ] JSON output for agent parsing.
- [ ] `--help` flag supported for discoverability.
- [ ] Zero hardcoded paths—all via arguments or environment.
- [ ] External dependencies documented in script header comment.
- [ ] Script executes without errors.

---
## [6][ERROR_SYMPTOMS]
>**Dictum:** *Symptom diagnosis accelerates fix identification.*

<br>

| [INDEX] | [SYMPTOM]                      | [CAUSE]                        | [FIX]                                              |
| :-----: | ------------------------------ | ------------------------------ | -------------------------------------------------- |
|   [1]   | Skill not discovered           | Frontmatter delimiter missing  | Ensure `---` on line 1, closing `---` before body  |
|   [2]   | Registration fails             | Name contains reserved word    | Remove `anthropic`, `claude` from name field       |
|   [3]   | Skill invoked incorrectly      | Description lacks triggers     | Add "Use when" clause with specific scenarios      |
|   [4]   | LOC limit exceeded             | Brute-force trimming attempted | Apply consolidate→restructure→densify→prune        |
|   [5]   | SKILL.md duplicates references | Content separation violated    | Move HOW to references, keep WHY in SKILL.md       |
|   [6]   | Folders missing for type       | Structure mismatch             | Create required folders per type table             |
|   [7]   | Validation scattered           | Per-file validation sections   | Consolidate to validation.md, remove from refs     |
|   [8]   | Script fails silently          | Missing --help or JSON output  | Add argparse/parseArgs with help flag, JSON output |

---
## [7][OPERATIONAL_COMMANDS]
>**Dictum:** *Verification requires observable outcomes.*

<br>

```bash
# LOC verification
wc -l SKILL.md                    # Must be < limit for depth
wc -l references/*.md             # Each must be < limit for depth

# Structure verification
ls -la                            # Verify folder existence matches type
find references/ -type f | wc -l  # Must be ≤7

# Frontmatter verification
head -1 SKILL.md                  # Must be exactly "---"
grep "^name:" SKILL.md            # Must match folder name
grep "Use when" SKILL.md          # Must exist in description

# Name matching
basename $(pwd)                   # Folder name
grep "^name:" SKILL.md | cut -d: -f2 | tr -d ' '  # Frontmatter name
# These must match exactly
```

```