Skill maker

<objective> Generate a new skill (or slash-command) that matches a clean, consistent house style: pushy trigger-phrase description, XML-tagged body with numbered phases, rolling-window state files, saved-rules accumulation, checkpoint resumption, attribution conventions, and the right compaction-with-preservation pattern for the use case. Single source of truth for structuring skills well — loads the style guide, presents the canonical scaffold, walks through structured intake, generates the skill files, and validates them. Pairs well with Anthropic's `skill-creator` plugin (defer to it for the eval/iteration loop). Skills generated by this skill should pass a structure audit cleanly on first try. </objective> <context> @references/skill-style.md @references/compaction-patterns.md @references/frontmatter-fields.md @references/intake-questions.md @./state.md </context>

<execution_context>

• Auto-load the style guide + compaction patterns at start (via <context> injection above)
• Auto-execute scaffolding (mkdir + boilerplate writes) — these are reversible
• ASK before writing the actual SKILL.md body — preview must be approved
• ASK before deferring to Anthropic skill-creator for eval iteration — only if user opts in
• Saved Rules: accumulate per-user-style preferences (e.g., "always wants Phase 5.5 deep-clean for stateful skills") in state.md
• Rolling window: keep last 10 generated-skill entries full, compact older to one-line in archive section </execution_context>

<process> <phase name="0_initialize"> ## Phase 0 — Initialize + Load State

1. TaskCreate one task per phase (8 phases).
2. Read state.md if exists; check for IN_PROGRESS marker.
3. If IN_PROGRESS found → AskUserQuestion:
   • Resume from last checkpoint
   • Start fresh (archive previous as ABORTED)
   • Show full history (abort, let the user review)
4. Otherwise → record current generation as IN_PROGRESS with checkpoint: INITIALIZED.
5. Read references/skill-style.md + references/compaction-patterns.md into context (loaded via @ in <context> block above, but verify accessible).

TaskUpdate Phase 0 → completed. </phase>

<phase name="1_capture_intent"> ## Phase 1 — Capture Intent (free-form, only if missing)

If the user provided a skill name + description in their initial message → skip to Phase 2.

Otherwise, free-form prompt:

"What should this skill do? In 1-2 sentences, describe the workflow you want to capture."

Record their answer → intent field. Update checkpoint: INTENT_CAPTURED.

TaskUpdate Phase 1 → completed. </phase>

<phase name="2_structured_intake"> ## Phase 2 — Structured Intake (batched AskUserQuestion)

ONE AskUserQuestion call with up to 4 questions covering the highest-leverage decisions. Use the question set in references/intake-questions.md as the canonical source.

The 4 batched questions (4 is the max per AskUserQuestion call):

1. Skill name + form — what's the name (kebab-case)? Skill in ~/.claude/skills/<name>/ or slash-command in ~/.claude/commands/<name>.md or both?
2. Stateful? No (stateless) / Yes-simple (one history file) / Yes-checkpointed (sync-style with IN_PROGRESS recovery) / Yes-multi-actor (with attribution suffixes)
3. State location (if stateful) — skill dir / current repo / external repo (multi-device sync) / .planning/
4. Compaction pattern (if stateful) — pick one of 14 from references/compaction-patterns.md (default: "rolling-window-saved-rules" for most cases)

Then a SECOND AskUserQuestion for follow-ups depending on Q1-4 answers:

5. Autonomy matrix — auto-fix-safe / ask-on-medium / never-touch — with examples
6. Hard invariants — what should NEVER be done regardless of context (free-form)
7. References needed? (templates, schemas, long docs to offload from SKILL.md)
8. Scripts needed? (shell helpers, generators, validators)

For each answer, record to intake/ block in current state entry.

Update checkpoint: INTAKE_COMPLETE. TaskUpdate Phase 2 → completed. </phase>

<phase name="3_pick_template"> ## Phase 3 — Pick Template

Based on intake, pick from references/examples/:

Template	When
01-stateless.md	No state, single-purpose (e.g. a one-shot search/fetch tool)
02-stateful-simple.md	One history file, rolling-N + archive (e.g. a send-and-log workflow)
03-stateful-checkpointed.md	IN_PROGRESS recovery + saved rules (e.g. a long resumable sync)
04-stateful-multi-actor.md	Multiple state files + attribution suffixes (e.g. a shared bot/human workflow)
05-slash-command-router.md	One-line delegate to a subagent
06-information-display.md	Read-only output, zero context bloat (e.g. a help/status command)
07-multi-phase-feature.md	Multi-artifact per-feature dirs (e.g. a feature-development workflow)

Show user the picked template + ask "looks right?" before generating.

Update checkpoint: TEMPLATE_SELECTED. TaskUpdate Phase 3 → completed. </phase>

<phase name="4_generate"> ## Phase 4 — Generate SKILL.md + References + Scripts

1. Run bash scripts/generate-skill.sh <name> <template> — creates the directory, writes initial SKILL.md from chosen template + intake answers, scaffolds references/ and scripts/ subdirs if specified.
2. Substitute placeholders: {{SKILL_NAME}}, {{DESCRIPTION}}, {{TRIGGER_PHRASES}}, {{COMPACTION_PATTERN}}, etc.
3. Compose SKILL.md sections per the canonical scaffold:
   • Frontmatter (pushy > description, paths: glob if path-scoped, when_to_use: if it adds clarity, argument-hint: only if $ARGUMENTS used, allowed-tools: only if restricting)
   • <objective>
   • <context> with @ injections for state file + relevant references
   • <execution_context> with autonomy matrix
   • <process> with numbered <phase name="N_named"> blocks
   • <saved_rules_format> (if stateful)
   • <recovery_protocol> (if stateful with checkpoints)
   • <error_handling> (always)
   • <success_criteria> (always)
4. Generate compaction section per chosen pattern using bash scripts/compaction-template.sh <pattern>.

Update checkpoint: GENERATED. TaskUpdate Phase 4 → completed. </phase>

<phase name="5_preview"> ## Phase 5 — Preview to User

Show the FULL generated SKILL.md content in the chat — no surprises before write.

Ask via AskUserQuestion:

• Approve → write files (Phase 6)
• Modify → which section/field/wording? (free-form, then re-generate that section)
• Abort → archive current entry as ABORTED, exit cleanly

Update checkpoint: PREVIEWED. TaskUpdate Phase 5 → completed. </phase>

<phase name="6_write"> ## Phase 6 — Write Files

Only after Phase 5 approval:

1. Write SKILL.md to ~/.claude/skills/<name>/SKILL.md (or ~/.claude/commands/<name>.md for slash-command form).
2. Write any reference files specified in intake to references/.
3. Write any script files specified to scripts/ (with chmod +x).
4. Write initial state file scaffolding if stateful (with header + format docs + empty section).
5. If user wants slash-command shortcut → create ~/.claude/commands/<name>.md with one-line Skill(<name>) delegate.

Update checkpoint: WRITTEN. TaskUpdate Phase 6 → completed. </phase>

<phase name="7_validate"> ## Phase 7 — Validate + Test

1. Run bash scripts/validate-skill.sh <name> — checks:
   • Frontmatter description ≤ 1,536 chars (combined with when_to_use)
   • Required tags present per <execution_context>'s skill-class
   • SKILL.md size — warn if > 500 lines or > ~5K tokens (auto-compaction truncation risk)
   • References referenced in <context> actually exist
   • Scripts referenced are executable
2. Optionally run a deeper structure audit if you have a skill-auditor command available.
3. Surface findings:
   • 🔴 must-fix (description too long, missing required tags, broken @ references)
   • 🟡 should-fix (style inconsistencies, missing optional tags)
   • 🟢 nice-to-have (suggestions for improvement)
4. Optionally defer to Anthropic skill-creator@claude-plugins-official for eval iteration (offer to user — only if they want quantitative test prompts).

Update state.md: append COMPLETED entry with skill name + template chosen + audit results + summary. Apply rolling-window pruning if > 10 entries (compact older to one-liners in archive section).

Update checkpoint: COMPLETED. TaskUpdate Phase 7 → completed. </phase>

</process>

<saved_rules_format>

Saved Rules

Stored in state.md "Saved Rules" section. Surfaced on every /skill-maker run as:

"Previous rule found: '{rule_text}'. Apply this? (Yes / No / Delete rule)"

Format per rule:

- {topic}: {rule} — set {YYYY-MM-DD}

Examples (auto-discovered by observing the user's choices over time):

• naming: prefer kebab-case, prefix with category if part of a family (e.g., myproject-*)
• compaction-default: rolling-window-saved-rules (5 full + saved rules)
• attribution: only add — [actor <time>] suffix when ≥2 actors
• token-budget: keep SKILL.md under 500 lines (a common convention; not a hard cap) </saved_rules_format>

<recovery_protocol> If state.md shows IN_PROGRESS when this skill starts:

1. Identify last completed checkpoint from state entry (INITIALIZED / INTENT_CAPTURED / INTAKE_COMPLETE / TEMPLATE_SELECTED / GENERATED / PREVIEWED / WRITTEN).
2. Map checkpoint → next phase:
   • INITIALIZED → resume Phase 1
   • INTENT_CAPTURED → resume Phase 2
   • INTAKE_COMPLETE → resume Phase 3
   • TEMPLATE_SELECTED → resume Phase 4
   • GENERATED → resume Phase 5
   • PREVIEWED → resume Phase 6
   • WRITTEN → resume Phase 7
3. Offer the user: Resume / Start fresh (archive previous as ABORTED) / Show full history.
4. On resume, append to existing entry; do NOT create new entry.
5. Update updated_at timestamp and checkpoint: field. </recovery_protocol>

<error_handling>

• Skill name conflicts with existing in ~/.claude/skills/<name>/ → ask: rename / overwrite / abort. Default: rename with -v2 suffix.
• AskUserQuestion times out → treat as Skip; mark current entry as ABORTED in state.md.
• Validation script fails → log warning, complete generation anyway, recommend running the audit manually.
• Template not found in references/examples/ → fall back to 02-stateful-simple.md (most common case).
• State.md corrupted → back up to state.md.bak.<ts>, create fresh state.md, warn user.
• Description exceeds 1,536 char cap → re-prompt for shorter version OR auto-truncate (preferring trigger phrases over prose).
• Body exceeds 500 lines at write time → suggest moving content to references/ files (progressive disclosure). </error_handling>

<success_criteria>

• New skill exists at ~/.claude/skills/<name>/SKILL.md with all required frontmatter fields
• All chosen XML tags present per skill-class (stateless / stateful-simple / stateful-checkpointed / stateful-multi-actor)
• References specified in intake actually written to references/
• Scripts specified are written + executable
• State file scaffolded if stateful (with format docs + empty section)
• Validation returns 0 🔴 findings
• state.md has new COMPLETED entry with chosen template + audit results
• Saved Rules accumulated if new patterns detected from this run
• The user can /{new-skill-name} and the skill loads + responds quickly </success_criteria>

Direct actions the user can ask for

If the user explicitly requests something (not full skill creation), handle accordingly:

• "Audit my skill X" → run bash scripts/validate-skill.sh X (and a deeper auditor if available); show findings with fix suggestions
• "Standardize skill X" → read existing skill, diff against canonical scaffold, propose changes via AskUserQuestion
• "Convert command to skill" → migrate ~/.claude/commands/X.md → ~/.claude/skills/X/SKILL.md preserving content + restructuring
• "Show me the style guide" → display references/skill-style.md
• "Show compaction patterns" → display references/compaction-patterns.md
• "Show frontmatter fields" → display references/frontmatter-fields.md
• "List my skills" → ls ~/.claude/skills/ + structured table with status
• "Add Phase X to skill Y" → augment existing skill with new phase, validate

What this skill deliberately does NOT do

• Never modifies a skill without showing diff + getting Phase 5 preview approval
• Never auto-publishes (no auto-commit beyond the local skill dir; you commit when ready)
• Never modifies global ~/.claude/CLAUDE.md without explicit ask
• Never deletes a skill (only archives by adding .disabled suffix at the user's explicit request)