# Skill Maker

> Create new Claude Code skills (or slash-commands) in a clean, consistent house style — XML phases, rolling-window state files, saved rules, checkpoint resumption, attribution conventions, and 14 compaction-with-preservation patterns. Use when the user asks to "make a skill", "create a skill", "build a skill", "scaffold a skill", "new skill", "skill for X", "make this a skill", "turn this into a skill", "make a slash command", "create a command", "wrap this workflow", "automate this", "add to my library", "another skill like X", or any phrasing implying turning a workflow into a reusable, well-structured skill. Single point of entry — loads the full style guide + all 14 compaction patterns + canonical scaffold.

- Skill: `adamjali/skill-maker` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add adamjali/skill-maker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/adamjali/skill-maker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: adamjali (https://skillmd.com/u/adamjali)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/adamjali/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)