[H1][SKILL-BUILDER]

Dictum: Structured authoring produces discoverable, maintainable skills.

Create and refine Claude Code skills via structured workflows.

Tasks:

• Collect parameters — Scope: create | refine , Type: simple | standard | complex , Depth: base | extended | full

• Read frontmatter.md — Discovery metadata, trigger patterns

• Read structure.md — Folder layout gated by Type

• Read depth.md — LOC limits, nesting gated by Depth

• (complex) Read scripting.md — Automation standards

• Capture requirements — purpose, triggers, outputs

• Invoke skill-summarizer with skill style-standards — Extract voice, formatting, taxonomy

• Invoke deep-research — Domain research for skill topic

• Plan with 3 agents — file inventory, section structure, content framework

• Execute per Scope:

• (create) Author new artifacts; select template:

• simple - DEFAULT

• standard

• complex

• (refine) Compare input to existing frontmatter; see refine.md:

• Input = existing → optimize (density, fixes, quality)

• Input > existing → upgrade (expand structure or depth)

• Input < existing → downsize (combine, refactor, remove low-relevance)

• 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 — Complete file listing

[1][FRONTMATTER]

Dictum: Metadata enables discovery before loading.

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.

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.

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.

• Content Separation — SKILL.md = WHY, references = HOW; see depth.md§CONTENT_SEPARATION.

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.

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.

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.

[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