Skill Maker

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.

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.

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.

Based on intake, pick from references/examples/:

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

Update checkpoint: TEMPLATE_SELECTED. TaskUpdate Phase 3 → completed.

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.

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.

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.

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.

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)

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.

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)