Skill Creator

Skill Creator

Create new Claude Code skills interactively, following all conventions from SKILLS_GUIDE.md and the learning/configurability/feedback patterns proven in the best existing skills.

Preferences

On startup, use the Read tool to load ~/.claude/skills/skill-creator/preferences.md. If missing, treat as "no preferences set".

Context

Before starting:

• Use the Glob tool to discover existing skills at ~/.claude/skills/*/SKILL.md (so you don't reinvent or collide with a name).
• Read ~/.claude/skills/SKILLS_GUIDE.md once at Step 3 — it's the canonical manifest.
• Treat svg-art, should-i-buy, and step-through as the gold-standard reference for learning + feedback patterns.

Command routing

Check $ARGUMENTS:

• help → display help, then stop
• config → interactive setup, then stop
• reset → delete ~/.claude/skills/skill-creator/preferences.md, confirm, stop
• --from-description "..." → skip Q1, use the quoted text as the skill's purpose
• anything else (including empty) → run the skill

Help

Skill Creator — Creates Claude Code skills, manifest-compliant by default

Usage:
  /skill-creator                             Interactive skill creation
  /skill-creator                       Start with a name pre-filled
  /skill-creator --from-description "..."    Start from a plain-text description
  /skill-creator config                      Set preferences
  /skill-creator reset                       Clear preferences
  /skill-creator help                        This help

Examples:
  /skill-creator                             Full interactive walkthrough
  /skill-creator deploy-preview              Create a skill named "deploy-preview"
  /skill-creator --from-description "A skill that triages PR comments"

Current preferences:
  (loaded from ~/.claude/skills/skill-creator/preferences.md)

Config

Use AskUserQuestion to collect:

• Q1 — Default skill location: ~/.claude/skills/ (standard) or custom path
• Q2 — Auto-update inventory in SKILLS_GUIDE.md after creation: yes/no
• Q3 — Publish repo path (e.g. ~/Dev/claude-skills) or "none"
• Q4 — Default learning posture: learning-on (include feedback + journal + sessions) / learning-off (stateless tool by default) / ask-each-time

Save to ~/.claude/skills/skill-creator/preferences.md.

Reset

Delete ~/.claude/skills/skill-creator/preferences.md and confirm: Preferences cleared. Using defaults.

First-time detection

If no preferences file exists:

> First time using /skill-creator? Run /skill-creator config to set defaults, or just continue with sensible defaults.

Then proceed.

---

Manifest patterns reference (read once, apply every time)

Every generated SKILL.md must satisfy these — no exceptions unless explicitly justified to the user.

Required (from SKILLS_GUIDE.md)

1. Frontmatter — name (kebab-case, ≤64 chars), description (third-person, "Use when …" trigger, ≤1024 chars), argument-hint, minimal allowed-tools.
2. disable-model-invocation: true — required for any skill that creates / modifies / pushes / posts.
3. AskUserQuestion in allowed-tools — every skill needs it for help/config/reset.
4. Subcommand pattern — help, config, reset, default behaviour.
5. Read of preferences on startup — never ! backtick interpolation for ~/.claude/ paths.
6. First-time detection — warm one-liner, never blocking.
7. No ! backtick interpolation — use runtime "On startup, use Bash to …" instructions instead.
8. Under 500 lines — push reference material to reference/ or examples/.
9. Numbered workflow — checklists, not prose.
10. Graceful degradation — every external read/tool call must have a fallback.
11. Validation loops — after any action, verify before moving on.

Required for skills with discrete sessions / outputs (default ON unless stateless)

1. Three-tier preferences format:

```markdown # / preferences Updated: YYYY-MM-DD

## Defaults

• knob: value

## Profile (optional — edit freely)

• user-editable bias

## Learned

• (populated from feedback over time)

```

1. feedback subcommand — /skill feedback collects ratings on the most recent session via AskUserQuestion.
2. feedback-journal.md — append a per-session block with a Signal: one-liner generalisation.
3. sessions/YYYY-MM-DD-HHMM.md — incremental session log when the skill has discrete invocations worth tracking.
4. Promotion rule — when 3+ sessions show the same signal, promote it to ## Learned in preferences.md. Mention once: "Noticed you consistently … Saved as standing default."
5. Drift correction — when a Learned rule is contradicted in 2 newer sessions, demote it (log the demotion in the journal). Never leave stale rules.
6. Step 0 — Load learning context — read preferences.md and feedback-journal.md before the main workflow. Continue silently on missing files.
7. Invite feedback line at the end of the workflow: Run / feedback — even one rating helps me sharpen defaults.
8. Reset clears the lot — preferences.md, feedback-journal.md, sessions/, any resume-state.md.

Required for skills that render UI (HTML, React, SVG, posters, dashboards, reports)

1. DESIGN.md is mandatory. Any skill that generates user-facing UI — HTML reports, React components, SVG artefacts, Markdown with structured visuals, posters, slide decks — must include a DESIGN.md at the skill root. The DESIGN.md is the renderer contract: it specifies aesthetic direction, type system, colour tokens, layout, visualisation principles, anti-patterns to avoid, and accessibility guarantees. Renderers reach for DESIGN.md before generating any markup, and prefer its tokens over hard-coded values.
2. At runtime, the skill MUST Read DESIGN.md before rendering any UI — and the workflow must explicitly cite it (e.g. "Step N — Load DESIGN.md. Apply its tokens, type system, anti-patterns, and a11y contract to every emitted artefact."). Treat missing DESIGN.md the same as missing preferences: degrade gracefully with built-in defaults, but never silently ignore it when present.
3. DESIGN.md sections (canonical structure):

```markdown # / design

## Aesthetic direction The committed point of view. References, tone, what this is NOT.

## Type system Display font + body font + mono font, with fallbacks. Scale, weights, letter-spacing.

## Colour tokens CSS custom properties. AA-compliant for any token used as text. Dark-mode mirrors.

## Layout Max widths, spatial moments, grid/asymmetry rules.

## Visualisation principles How charts encode data. Density binning, sparse-data fallback, redundancy beyond colour.

## Anti-patterns to avoid Project-specific don'ts, plus the universal slop list.

## Renderer contract Hard guarantees: ARIA on every SVG; contrast ≥4.5:1 for text; no color-only encoding; no title-only tooltips; pre-computed colour-mix fallbacks; anonymisation rules; etc.

## Component patterns The reusable HTML/JSX/SVG snippets — each shown inline, using tokens not hex values. ```

1. DESIGN.md vs preferences.md — DESIGN.md is the skill's aesthetic contract (versioned in the skill, identical for every user). preferences.md is the user's runtime configuration (per-machine, edited freely). When they conflict, user preferences win for runtime knobs (e.g. tone, depth, framework); DESIGN.md wins for renderer guarantees (e.g. a11y contract, anti-patterns). Encode this priority in the workflow: load DESIGN.md, then preferences, and only let preferences override DESIGN.md tokens flagged as user-tunable.
2. Anti-pattern baseline. Every UI-rendering skill must include the universal slop list in its DESIGN.md's "Anti-patterns" section (with [[from skill-creator]] link):

• Inter / Roboto / Arial as primary font choice — pick distinctive pairings
• Purple gradients on white
• Glassmorphism / backdrop-blur for decoration
• Hero metrics without scale legend
• Color-only encoding (must pair with shape/size/position/texture)
• Tooltips via title="" only (need focusable + visible alternatives)
• Nested cards (cards inside cards)
• Bounce / spring easing on serious / professional content
• font-feature-settings: "ss01", "cv11" applied to non-Inter fallback fonts (dead code)
• -webkit-font-smoothing: antialiased (harms low-vision users)

Recommended (apply when relevant)

1. resume-state.md + / resume — for any skill where the user can stop mid-flow.
2. Confirmation policy — destructive-only by default; configurable to "every action" via preferences.
3. Pre-selection logic in AskUserQuestion — bias the default option using Learned rules.
4. Configurability ≥ 3 knobs — depth, verbosity, output format, source selection, confirmation policy. A skill with only 1 knob is under-specified.
5. Templates (templates/.md) — when a skill has a recurring "preset workflow" with parameterized inputs (e.g. /publish-note --from-template=raw-idea ""), expose it as a template file inside the skill directory. Each template is a YAML-frontmatter + markdown file declaring inputs, tasks, constraints, tools, postProcesses. The skill should support --from-template= routing in addition to its standard flow. See ~/.claude/skills/publish-note/templates/raw-idea.md for the canonical example. Templates are how a skill compresses an entire conversational workflow ("I want X, with these constraints, ending in Y") into a single command.

When to skip the learning tier (12–20)

Skip only if all of the following are true:

• The skill has no per-session output worth rating (e.g. aws-mfa writes a credential file — there's nothing to thumbs-up).
• The skill is purely procedural and identical every run.
• There's no per-severity / per-output category that could be biased over time.

If skipping, document it in the SKILL.md's Principles section: Stateless by design — no feedback loop because [reason].

---

Step 1 — Understand the skill's purpose

If $ARGUMENTS contains --from-description, use that text. If $ARGUMENTS is a bare name, pre-fill the name and ask the rest. Otherwise, ask:

> What should this skill do? Describe the workflow in a sentence or two.

Extract:

• Working name (kebab-case)
• Core verb (creates, analyses, fetches, organises, walks through, …)
• Trigger phrase (when should the user reach for it)

Confirm with the user: I'll call this /skill-name — a skill that [one-liner]. Sound right?

Step 2 — Determine side effects, context, and learning posture

Use AskUserQuestion with 3 questions in one batch:

Q1 — Side effects: Does this skill create, modify, push, or post anything?

• Yes → disable-model-invocation: true
• No (read-only) → omit disable-model-invocation
• Pre-select Yes if the description mentions create/post/push/update/write/deploy.

Q2 — Context needs: Does this skill need the current conversation history?

• Yes (builds on what we've discussed) → no context field
• No (self-contained, works from its own inputs) → context: fork
• Pre-select fork if the skill processes external input only (URLs, file paths, pasted text).

Q3 — Learning posture: Should this skill learn from per-session feedback?

• Yes — full learning tier (preferences + journal + sessions + feedback subcommand) — pre-select for any skill with discrete outputs, decisions, or judgement calls
• No — stateless tool — pre-select only for purely procedural skills (e.g. credential refresh, fixed pipeline runners)
• If Yes, items 12–20 of the manifest reference are now mandatory.

Step 3 — Identify tools needed

Read ~/.claude/skills/SKILLS_GUIDE.md to confirm conventions.

Use AskUserQuestion (multiSelect):

> Which capabilities does this skill need?

• Read files → Read, Glob, Grep
• Edit files → Write, Edit
• Run commands → Bash (use Bash(git *) / Bash(gh *) glob patterns when scoping)
• Ask questions → AskUserQuestion (always include — auto-add even if not picked)
• Web access → WebSearch, WebFetch
• Linear → use mcp__claude_ai_Linear__* (NOT mcp__linear-server__*):
• Read: list_issues, get_issue, list_comments, list_projects, get_project, list_teams
• Write: above + create_issue, update_issue, create_comment
• Vercel / Slack / Notion / Chrome / Playwright → pick specific MCP tools by action

Always include AskUserQuestion. Always keep the list minimal — granting Write/Edit to a read-only skill is a bug.

Step 4 — Design the workflow

Apply the manifest reference. Draft a numbered workflow that includes (in order, when learning tier is on):

1. Step 0 — Load learning context (read preferences + journal)
2. Domain-specific steps (4–8 of them)
3. Step N–1 — Final summary
4. Step N — Invite feedback (one-line pointer to / feedback)

For stateless skills, drop steps 0 and N.

Identify ≥3 configurability knobs (depth, verbosity, format, source, confirmation policy, …). Identify the 1–3 decision points that get an AskUserQuestion. Identify what the feedback subcommand will rate (per-severity defaults? per-output style? per-source pace?).

Present the outline: > Here's the workflow: > 1. Load learning context > 2. … > N. Invite feedback > > Configurability knobs: [list]. Feedback dimensions: [list]. Want to adjust?

Step 5 — Determine arguments and flags

Propose:

• Positional argument (if any)
• Standard flags: --filter, --start, --from, --dry-run, --verbose (only those that fit)
• Subcommands beyond the standard four: feedback, resume (if applicable)

Confirm via AskUserQuestion or inline.

Step 5.4 — DESIGN.md (ask if the skill renders UI)

If Step 2 / 3 / 4 surfaced that the skill emits user-facing UI (HTML files, React components, SVG artefacts, slide decks, posters, structured-visual markdown), ask once via AskUserQuestion:

> This skill renders UI. Scaffold a DESIGN.md design contract? > - Yes — canonical structure (recommended) — adds DESIGN.md with the eight standard sections (aesthetic direction, type system, colour tokens, layout, visualisation principles, anti-patterns, renderer contract, component patterns). Workflow gets a "Load DESIGN.md before rendering" step. Renderer references tokens, not hex values. > - Yes — minimal stub — DESIGN.md is created with section headings only; user fills in. > - No — skip. (Acceptable only if the skill emits raw text / data, no styling decisions.)

If Yes:

1. Create ~/.claude/skills//DESIGN.md with the canonical structure (see manifest item 28 and the example at ~/.claude/skills/emotional-recap/DESIGN.md).
2. Add to the skill's ## Context section: On startup, use the Read tool to load DESIGN.md. Apply its tokens, type system, anti-patterns, and renderer contract to every emitted artefact. If missing, fall back to built-in defaults but flag once.
3. Add a workflow step before the render step: ### Step N — Load DESIGN.md.
4. In the structure checklist (Step 6), tick the "DESIGN.md loaded before any render" box.
5. Seed the Anti-patterns section with the universal slop list from manifest item 30.

DESIGN.md is the skill's renderer contract: aesthetic + accessibility + token guarantees, versioned in the skill repo. It is distinct from preferences.md (which is per-user runtime configuration). When they conflict, DESIGN.md wins for renderer guarantees (a11y, anti-patterns); preferences wins for user-tunable knobs (tone, depth, framework choice).

Step 5.5 — Templates (optional, ask once)

Ask once via AskUserQuestion:

…

Source & license

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

• Author: mostafa-drz
• Source: mostafa-drz/claude-skills
• License: MIT

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