Skill Maker

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.

@references/skill-style.md @references/compaction-patterns.md @references/frontmatter-fields.md @references/intake-questions.md @./state.md

• Auto-load the style guide + compaction patterns at start (via `` 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

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)

1. Otherwise → record current generation as IN_PROGRESS with checkpoint: INITIALIZED.
2. Read references/skill-style.md + references/compaction-patterns.md into context (loaded via @ in `` block above, but verify accessible).

TaskUpdate Phase 0 → completed.

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 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// or slash-command in ~/.claude/commands/.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:

1. Autonomy matrix — auto-fix-safe / ask-on-medium / never-touch — with examples
2. Hard invariants — what should NEVER be done regardless of context (free-form)
3. References needed? (templates, schemas, long docs to offload from SKILL.md)
4. 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 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 4 — Generate SKILL.md + References + Scripts

1. Run bash scripts/generate-skill.sh — 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)
• ``
• ` with @` injections for state file + relevant references
• `` with autonomy matrix
• ` with numbered ` blocks
• `` (if stateful)
• `` (if stateful with checkpoints)
• `` (always)
• `` (always)

1. Generate compaction section per chosen pattern using bash scripts/compaction-template.sh .

Update checkpoint: GENERATED. TaskUpdate Phase 4 → completed.

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 6 — Write Files

Only after Phase 5 approval:

1. Write SKILL.md to ~/.claude/skills//SKILL.md (or ~/.claude/commands/.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/.md with one-line Skill() delegate.

Update checkpoint: WRITTEN. TaskUpdate Phase 6 → completed.

Phase 7 — Validate + Test

1. Run bash scripts/validate-skill.sh — checks:

• Frontmatter description ≤ 1,536 chars (combined with when_to_use)
• Required tags present per ``'s skill-class
• SKILL.md size — warn if > 500 lines or > ~5K tokens (auto-compaction truncation risk)
• References referenced in `` actually exist
• Scripts referenced are executable

1. Optionally run a deeper structure audit if you have a skill-auditor command available.
2. 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)

1. 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.

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 ] suffix when ≥2 actors
• token-budget: keep SKILL.md under 500 lines (a common convention; not a hard cap)

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

1. Offer the user: Resume / Start fresh (archive previous as ABORTED) / Show full history.
2. On resume, append to existing entry; do NOT create new entry.
3. Update updated_at timestamp and checkpoint: field.

• Skill name conflicts with existing in ~/.claude/skills// → 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., 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).

• [ ] New skill exists at ~/.claude/skills//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

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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: adamjali
• Source: adamjali/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.