Skill Creator

Structured creation workflow that produces high-quality skills by front-loading decision-making through exhaustive discovery. Effectiveness is measured against the quality checklist in SKILL_STANDARDS.md.

Critical Rules (MUST follow)

Discovery before writing — MUST complete discovery and planning before writing any skill files. No skipping ahead.
Approval gate before scaffold — MUST present planning output to user and get explicit approval before creating files.
Skill-audit is mandatory — MUST run /skill-audit on every created skill before considering it complete.
Under 300 lines — created SKILL.md MUST stay under 300 lines. Extract to REFERENCE.md if approaching the limit.
MUST/SHOULD/MAY on every instruction — every instruction in created skills MUST be classifiable as MUST, SHOULD, or MAY.
Persist state incrementally — save to state file after every phase. Long creation sessions WILL hit compaction.
Recommend with rationale — at every decision point, state your recommendation and explain WHY.

When to Use

Creating a new skill from scratch
Updating or improving an existing skill (major changes)
User explicitly invokes /skill-creator

When NOT to Use

Auditing an existing skill's quality — use /skill-audit
Creating an audit-type skill — use /create-audit
Checking all skills for issues — use /skill-ecosystem-audit
Quick structural check — use npm run skills:validate

What This Skill Does NOT Do

Ecosystem-wide analysis (use /skill-ecosystem-audit)
Structural validation only (use npm run skills:validate)
Behavioral quality evaluation (use /skill-audit)
Audit-specific scaffolding (use /create-audit)

Routing Guide

Situation	Use	Why
Create new skill	`/skill-creator`	Full discovery + planning
Improve existing skill	`/skill-audit` first	Audit identifies what to fix
Create audit-type skill	`/create-audit`	Specialized audit scaffolding
Check all skills	`/skill-ecosystem-audit`	Ecosystem-wide analysis
Quick structural check	`npm run skills:validate`	Fast, no AI needed

Input

Argument: Skill name or description, passed as /skill-creator <name> or in conversation context.

Output location: .claude/skills/<skill-name>/ (MUST — user-created skills go here, not in vendor directories).

Complexity Tiers

Tier	Characteristics	Process
Simple	Reference-only, <50 lines, no companions	Skip discovery, write directly
Standard	Workflow, 50-200 lines, 0-2 companions	Full process
Complex	Multi-phase, 200-300 lines, 3+ companions	Full process + enhanced planning

Process Overview

WARM-UP    Orientation    -> Skill name, process, effort estimate, welcome
PHASE 1    Context        -> ROADMAP check, neighbor scan, existing patterns
PHASE 2    Discovery      -> Exhaustive questions (6 categories, floor ~12)
PHASE 3    Planning       -> Decision record + skill structure plan + approval
PHASE 4    Build          -> Scaffold, write SKILL.md + companions
PHASE 5    Validate       -> Structural + behavioral checklist
PHASE 6    Audit          -> Run /skill-audit on created skill
PHASE 7    Closure        -> Retro, invocation tracking, session cleanup

Use phase markers: ======== PHASE N: [NAME] ========

Warm-Up (MUST)

Present before any work: skill name, process overview, complexity tier estimate, effort estimate (Simple: 10min, Standard: 30min, Complex: 60min+).

"Before we start: any specific concerns, constraints, or existing patterns you want this skill to follow?"

Done when: User confirms proceed.

Phase 1: Context Gathering (MUST)

Check ROADMAP.md — verify skill aligns with project direction (MUST). If misaligned: present conflict, offer proceed/reframe/abort. Do NOT silently proceed.
Scan .claude/skills/ for existing neighbors (MUST)
Check CLAUDE.md for relevant conventions (MUST)
Extraction context (MUST): Scan .research/EXTRACTIONS.md for candidates relevant to the skill being created (human-readable, grouped by source). For targeted filtering, query .research/extraction-journal.jsonl (match by type, tags in notes, or source domain). If matches found, present as "Prior art from analyzed sources" — these are patterns, architectures, and design principles already identified from external repos/websites that may inform the skill's design.
Read existing skill files if updating (MUST for updates)
Domain research check (SHOULD) — if the skill being created covers a domain the AI lacks expertise in (unfamiliar technology, specialized workflow, external ecosystem), suggest: "This skill targets a domain that would benefit from research. Run /deep-research first to understand the landscape?" Prior research at .research/<topic-slug>/ feeds directly into better discovery questions and informed defaults in Phase 2.

Reframe path: If context reveals the user doesn't need a skill — they need a hook, script, CLAUDE.md entry, or agent — present the reframe before proceeding.

Done when: Context gathered, no ROADMAP conflict (or conflict resolved).

Phase 2: Discovery (MUST for Standard/Complex, skip for Simple)

Read .claude/skills/skill-creator/REFERENCE.md for the 6 question categories with example questions.

Discovery Rules (MUST follow)

Floor of ~12 questions, no ceiling — ask until ambiguity is resolved
Front-load critical decisions — scope, architecture, neighbors first
Offer defaults for every question — "I recommend X because Y. Override?"
Reference existing patterns — cite actual codebase skills, not generics
Batch 4-6 related questions — group by category, critical first
Inter-batch synthesis — summarize learnings before next batch
State inferences explicitly — "Based on Q3, inferring X for Q7"
Save decisions with rationale after every batch (MUST) — persist to state file, include WHY per decision
Show progress — "Batch 2 of ~3. N decisions captured."
Multi-agent exploration (SHOULD for Complex) — dispatch Explore agents to scan the codebase for relevant patterns before presenting questions. Findings inform defaults and recommendations.
Cross-batch revision (MUST) — if a later batch answer conflicts with an earlier decision, present the conflict and allow revision. Update state file with the revised decision.
Self-audit design (MUST for Standard/Complex) — discovery MUST include questions about the created skill's self-audit phase. See REFERENCE.md Category 2 for the self-audit design questions.

Delegation: If user says "you decide," accept recommended defaults. Document each delegated decision with rationale.

Contradiction detection: If answers conflict, flag immediately: "Decision N said X, but this implies Y. Which takes priority?"

Mid-discovery check (MUST after batch 2): "Discovery progress: N questions, M decisions. Estimated ~K more. Continue or scope-reduce?"

Post-discovery prompt (MUST): "Discovery complete. Anything the questions didn't cover, or concerns before we plan?"

Done when: All 6 categories covered, no remaining ambiguity, user confirms nothing missing.

Phase 3: Planning + Approval (MUST)

Compile decision record — one row per decision, choice + rationale (MUST)
Present skill structure plan (MUST):
- Files to create (SKILL.md, REFERENCE.md, scripts/, etc.)
- Section outline for SKILL.md
- Guard rails and failure modes
- Integration surface (neighbors, handoffs)
- Compaction resilience design
- Self-audit phase design (MUST for Standard/Complex) — list expected output artifacts to verify, verification agents to dispatch, orphan detection scope, and downstream contract checks. Reference SKILL_STANDARDS.md "Self-Audit at Completion" for the 9 dimensions.
Present for approval (MUST): "Here's the planned structure. Proceed? [approve / approve with changes / reject]"

Revision: If writing later reveals a planning decision was wrong, pause, note the revision, confirm with user before continuing.

Done when: User approves plan.

Phase 4: Build (MUST)

4.1 Input Validation (MUST)

Validate skill name: lowercase-kebab-case, no spaces, max 40 chars. Check .claude/skills/ for existing skill. If exists and malformed, offer repair or fresh start.

4.2 Scaffold

Run init_skill.py <name> --path .claude/skills for new skills. Skip for updates.

4.3 Write SKILL.md

Read REFERENCE.md for the full content checklist (MUST/SHOULD items).

Structure for attention management:

Top third (1-100): Critical rules, MUST behaviors, process overview
Middle third (100-200): Step-by-step procedures, checklists
Bottom third (200-300): Guard rails, compaction, version history

Point-of-use reminders (MUST):

Repeat "under 300 lines" in the validation phase
Repeat "MUST/SHOULD/MAY" where instructions are written
Repeat "front-load critical rules" in the writing phase

Project conventions: Reference CLAUDE.md by path. Do NOT duplicate conventions into the skill.

Data standards: If skill produces data files, SHOULD use JSONL as canonical format with .md for human readability.

Convergence-loop integration (SHOULD): If Phase 2 discovery identified a discovery or verification phase in the skill being created (T25 question), wire convergence-loop programmatic mode into that phase. Reference /convergence-loop SKILL.md "Programmatic Mode" section for the integration contract.

Self-audit phase (MUST for Standard/Complex): Two parts.

Prose phase in SKILL.md — write a self-audit phase as the penultimate phase (before Closure). Reference SKILL_STANDARDS.md "Self-Audit at Completion" for the 9 verification dimensions. Customize with the skill's specific deliverables, downstream contracts, and regression detection needs from Phase 3 planning.
Scaffold the script — create scripts/skills/<skill-name>/self-audit.js per SELF_AUDIT_PATTERN.md. Use scripts/skills/skill-audit/self-audit.js as the template and replace domain-specific dimension checks. The Phase 5 prose in SKILL.md MUST invoke this script first (per pattern doc §Wiring to SKILL.md Phase 5), with prose handling judgment-only checks afterwards.

If skill is Simple tier (<50 lines, reference-only), skip both parts — the "Done when:" gate is sufficient per SKILL_STANDARDS.md.

4.4 Write Companions (SHOULD)

Extract to REFERENCE.md if SKILL.md approaches 300 lines. Move examples, templates, question banks to companion files.

Done when: All files written, content checklist addressed.

Phase 5: Validate (MUST)

Run npm run skills:validate (MUST) — structural check
Walk the content checklist from REFERENCE.md (MUST) — for each unchecked item, either address it or document why not applicable
Convergence-loop verify (MUST for Complex, SHOULD for Standard) — verify created skill's codebase claims (neighbors, integration points, existing patterns) via convergence-loop quick preset. Skip if skill makes no codebase claims. If claims are wrong: fix in created skill files (Phase 4 re-entry) before continuing validation.
Verify line count under 300 (MUST)
Verify cross-references resolve (SHOULD)
Evidence-based self-check (MUST) — re-read all created files. For each planning decision from Phase 3, grep the output file for a keyword proving implementation. Decisions with no grep match are MISSING — fix before proceeding to Phase 6. See SKILL_STANDARDS.md "Self-Audit at Completion."
Self-audit phase present (MUST for Standard/Complex) — verify both: (a) SKILL.md includes a self-audit phase positioned as penultimate, referencing SKILL_STANDARDS.md dimensions appropriate to tier; (b) scripts/skills/<name>/self-audit.js exists and follows SELF_AUDIT_PATTERN.md (matching CLI shape, exit codes, SUMMARY block, required helpers).
Contract verification wired (MUST if downstream consumers) — verify the self-audit checks output against documented consumer expectations

Done when: skills:validate passes, behavioral checklist addressed, under 300 lines, codebase claims verified, all decisions grep-verified, self-audit phase present (Standard/Complex).

Phase 6: Audit (MUST)

Run /skill-audit <skill-name> on the created skill. The audit verifies behavioral quality that structural validation cannot catch.

Done when: Skill-audit complete, findings addressed.

Phase 7: Closure (MUST)

Closure signal (MUST): List all created/modified files with paths
Retro prompt (MUST): "What did discovery surface that you didn't expect? What did the checklist catch? What would you do differently?" Capture in state file process_feedback.

Invocation tracking (MUST):

cd scripts/reviews && npx tsx write-invocation.ts --data '{"skill":"skill-creator","type":"skill","success":true,"schema_version":1,"completeness":"stub","origin":{"type":"manual"},"context":{"target":"SKILL_NAME"}}'

Session cleanup (SHOULD): Commit created skill files. State file retained as creation record. Run /session-end if ending session.
Version history (MUST): WHAT changed + WHY in every entry.

Guard Rails

Contradiction: Flag conflicting requirements immediately
Scope explosion: If planned skill exceeds 300 lines + 3 companions + 5 scripts, pause: "This is growing large. Split into multiple skills?"
Phase gates: MUST complete Phase 1 before Phase 2. MUST have approved plan (Phase 3) before Phase 4.
Disengagement: If user stops mid-skill, save state, list files created, offer cleanup (delete partial work or keep for later)

Anti-Patterns

Read REFERENCE.md "Anti-Patterns" section for the full 12-item list of common skill creation mistakes (MUST check during Phase 4 Build).

Compaction Resilience

State file: .claude/state/skill-creator.state.json
Update: After every phase boundary and every discovery batch
Contents: Skill name, discovery decisions, planning checklist, current phase, files created, process feedback
Recovery: Re-invoke /skill-creator <skill-name> to read state and resume
Retention: State file retained after completion as creation record and artifact contract for /skill-audit handoff

Integration

Neighbors: /skill-audit (audit created skill), /skill-ecosystem-audit (check all skills), /create-audit (audit-specific scaffolding), /convergence-loop (Phase 4.3: wire into created skill if T25 applies; Phase 5: verify created skill's codebase claims)
References: SKILL_STANDARDS.md (Phase 5 content checklist), SELF_AUDIT_PATTERN.md (Phase 4.3 scaffold + Phase 5 verification), SKILL_AGENT_POLICY.md
Handoff: State file documents intent + discovery decisions for skill-audit

Version History

Version	Date	Description
3.4	2026-04-14	Phase 4.3 + 5.7: scaffold + verify scripts/skills/<name>/self-audit.js per pattern
3.3	2026-04-04	Add mandatory self-audit phase for Standard/Complex skills (9 dimensions)
3.2	2026-03-15	Skill-audit: CL verify MUST for Complex, reorder Phase 5, anti-patterns to REFERENCE
3.1	2026-03-15	Convergence-loop integration: Phase 4.3 build + Phase 5 verify
3.0	2026-03-08	Full rewrite from 52-decision audit (48/100 -> target 82/100)
2.2	2026-03-07	SC-1..5: operational deps, compaction MUST, scope, recommendations
2.1	2026-03-06	Add interactive design, verification phase, UX
2.0	2026-02-28	Add attention management, behavioral quality, guards
1.0	2026-02-25	Initial implementation (Anthropic skill, Apache 2.0)