# Skill Creator Pro > Use when creating new skills, iterating on existing skills, auditing skill quality, bumping skill versions, or optimizing skill trigger descriptions. Pro-grade lifecycle covering scaffold, baseline testing, evals, lint, semver, CHANGELOG, and description optimization. Triggers on "create a skill", "new skill", "迭代 skill", "优化 skill", "skill 版本", "skill lint", "review this skill", "write a skill for X", "turn this into a skill", or whenever the user starts or edits a SKILL.md. - Skill: `zwbao/skill-creator-pro` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add zwbao/skill-creator-pro` - Raw SKILL.md: https://api.skillmd.com/api/skills/zwbao/skill-creator-pro/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: zwbao (https://skillmd.com/u/zwbao) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/zwbao/skill-creator-pro --- # skill-creator-pro — A pro-grade skill lifecycle You are about to create or change a skill. That is a high-leverage act: one skill lives in the system prompt of every future conversation and gets invoked tens, hundreds, or thousands of times. **Treat it like production code.** The lifecycle is one pipeline: **RED → GREEN → EVAL → LINT → BUMP → OPTIMIZE-DESC → PACKAGE / SYNC**. Each step exists because skipping it has produced a specific failure mode in real use. --- ## The Core Loop ``` Understand intent │ ▼ RED: Run 1-2 baseline subagent scenarios WITHOUT the skill │ (watch it fail; record rationalizations verbatim) ▼ GREEN: scripts/init_skill.py → fill SKILL.md addressing those failures │ (description = "Use when ..."; body explains WHY, not just WHAT) ▼ EVAL (optional, recommended for non-trivial skills): │ write evals.json → spawn with-skill + baseline subagents → benchmark.json │ → eval-viewer → user feedback → improve → re-run ▼ REFACTOR: close new rationalizations surfaced by evals │ ▼ LINT: scripts/lint_skill.py → fix all errors, then warns │ ▼ BUMP: scripts/bump_version.py --type -m "..." │ (creates/updates CHANGELOG.md, badges, frontmatter.metadata.version) ▼ OPTIMIZE TRIGGER DESC: (when accuracy matters) │ iterate the description against 20 trigger queries (10 should-trigger, 10 near-miss) ▼ PACKAGE / SYNC: deploy to ~/.claude/skills/ — or ship a multi-platform library (npx skills add + .claude/.codex/.cursor plugin manifests) ``` **Do not skip RED.** The biggest failure mode of hand-written skills is that they solve problems the model never had — you assumed a rationalization that never appears, and missed the one that does. --- ## Decide the Track Up Front Not every skill earns the full pipeline. Pick a track **before** you start: | Track | When | Skip | |-------|------|------| | **Lightweight** | Personal utility, narrow scope, pure-reference, one user | RED, EVAL, description optimization | | **Full** | Discipline skill (TDD-like), shipped to others, >1 use case, high stakes | Nothing; run the whole loop | | **Audit-only** | Existing skill the user wants polished | Start at LINT, skip RED/GREEN | Announce the track to the user in one line: *"Going with the lightweight track because X."* Let them redirect. --- ## Decide the Skill Shape (orthogonal to track) A skill has one of two shapes. Pick before scaffolding — retrofitting is costly. | Shape | Structure | Use when | |-------|-----------|----------| | **Single-file** | one `SKILL.md` (+ `references/`, `scripts/`) | the skill does one thing, or a few tightly-related things sharing one procedure | | **Router + workflows** | thin router `SKILL.md` indexing `workflows/*.md`; agent loads only the selected one | **≥3 distinct user intents**, body would exceed ~400 lines of independently-invoked sections, or the capability set will grow | The router shape is how `LLMQuant/skills` ships 18 category skills and how meta+companion families (firefly / cancer-buddy / beacon) scale. A router is **progressive disclosure**: the model reads a ~40-line index + the one relevant workflow instead of skimming a 2000-line monolith on every near-miss. Less irrelevant text in context is a correctness lever, not just a cost one. Scaffold a router with `init_skill.py --router` (creates the router, `workflows/`, a sample workflow, and multi-platform plugin manifests). Full guide: `references/router-and-workflows.md`. Templates: `templates/SKILL_ROUTER_TEMPLATE.md` + `templates/WORKFLOW_TEMPLATE.md`. --- ## Classify the School (capability vs discipline) Every top-tier skill is one of two schools. Classify before writing — they have different body structures, trigger styles, and verification methods, and blending them produces an incoherent skill. | | **Capability / reference** | **Discipline / process** | |---|---|---| | PRD says | "extract / convert / generate / analyze X" | "always / never / enforce / stop the agent from Z" | | Body | table-first, ✅/❌ code recipes, scripts, QA loop | flowchart + one Iron Law + rationalization table + red-flags | | Trigger | exhaustive keyword enumeration + `Do NOT` clause | minimal "Use when " | | Verify | mandatory "assume-failure" QA loop (fresh-eyes subagent) | RED-GREEN-REFACTOR under multi-pressure scenarios | Full taxonomy + the distilled quality bar from the top-50 starred skill repos: `references/top-skills-playbook.md`. --- ## PRD-Driven Generation (input a PRD → finished skill) When the user hands you a PRD / spec and says "build the skill", run the whole pipeline driven by the PRD. Do **not** stop at a draft — a PRD asks for a *finished, top-tier* skill. 1. **Ingest & classify** — extract the PRD intake (school, shape, trigger phrasings, inputs/outputs, dangerous-to-guess values, acceptance criteria, target models). Missing trigger phrasings or acceptance criteria → ask the user once (`AskUserQuestion`); both gaps produce a bad skill. 2. **Derive evals from the PRD** — each acceptance criterion → ≥1 checkable assertion (≥3 scenarios). Eval-first: tests before docs. 3. **RED → scaffold → GREEN** — run the baseline, then fill SKILL.md by school, applying the playbook. 4. **Verify → LINT → OPTIMIZE-DESC → BUMP → PACKAGE** — to completion. 5. **Report against the PRD** — list every requirement and whether the shipped skill meets it, with eval evidence; be honest about anything deferred. Full procedure + the PRD intake template: `references/prd-to-skill.md`. --- ## Step-by-Step ### 1. Understand intent (2 min) Ask, using `AskUserQuestion` when available: - What should this skill enable a future Claude to do? - What would a user **actually type** that should trigger it? (Get 2-3 real phrasings, not abstract intents.) - Input → output: concrete shape, formats, file types. - One sentence on **why it doesn't already work without a skill** — this is the gap the skill fills. If the user says "turn this conversation into a skill", mine the transcript instead of asking: extract the steps they corrected, the tools used, the unobvious judgment calls. Then confirm the gaps. ### 2. RED — baseline subagent test (full track only) **Before writing a single line of the skill**, run one pressure scenario with a subagent **without** the skill. Use the Agent tool: > Execute this task: [the realistic user prompt]. Report what you did and how > you decided, verbatim. No skill is available. Record: *what did it do wrong? what rationalizations did it use?* These become the specific things your skill must counter. If the baseline succeeds effortlessly, **the skill is probably unnecessary** — tell the user. See `references/tdd-for-skills.md` for pressure-scenario patterns, pressure types (time, sunk cost, authority, exhaustion), and a catalog of rationalizations. ### 3. GREEN — scaffold + write ```bash python scripts/init_skill.py --dest ~/.claude/skills # single-file python scripts/init_skill.py --dest ~/.claude/skills --router # router + workflows ``` The default creates `//` with: - `SKILL.md` — frontmatter template + TODO placeholders - `README.md` — human-readable, version badge, install snippet, options table - `scripts/` — empty; create if the skill has deterministic helpers - `references/` — empty; create for heavy reference material (>100 lines) `--router` instead creates a router `SKILL.md`, a `workflows/` dir with a sample workflow, and `.claude-plugin/` + `.codex-plugin/` + `.cursor-plugin/` manifests for multi-platform install. See `references/router-and-workflows.md`. Now fill `SKILL.md`: - **Frontmatter** (see `references/frontmatter-spec.md` for the full spec): ```yaml --- name: description: Use when . Triggers on . license: MIT metadata: author: version: "0.1.0" tags: --- ``` `name` and `description` are the only hard requirements; the rest improves discoverability, versioning, and lint signal. - **Body** (≤500 lines; split to `references/` beyond that): - One-paragraph overview. - "When to Use" bullet list of symptoms, and "When NOT to Use" for adjacent cases. - Workflow steps (imperative: "Do X", not "You should do X"). - A quick-reference table for scanning. - Common mistakes with fixes. - **Explain the WHY** for every non-obvious rule. Today's models have theory of mind — rigid MUSTs without reasoning produce brittle compliance. - **Evidence Contract** (any skill that touches external facts — strongly recommended for medical / research / financial skills). Declare three things so the model never re-litigates "can I just make this up?" under pressure: - **Sources of record** — the API / DB / files / tools that supply ground truth. Prefer live retrieval over the model's memory. - **Fallback** — if a required input is missing, name the exact missing input and continue only with retrieved or user-provided evidence; never fill the gap from memory. - **Never fabricate** — the value types that are dangerous to guess (quotes, prices, citations, lab values, dosages, trial IDs). A model synthesizing these *is* the failure the contract exists to stop. Match the contract to the domain's "things dangerous to guess". See `references/router-and-workflows.md` § The Evidence Contract pattern. - **README.md** — humans read this on GitHub or in the file browser. Keep the version badge, install command, and a minimal usage example. ### 4. EVAL — objective benchmark (full track) Write 2-3 realistic test prompts in `evals/evals.json`, spawn **with-skill** and **baseline** subagents in the same turn, collect outputs into `-workspace/iteration-1/`, grade against assertions, aggregate into `benchmark.json`, review the side-by-side output, iterate. See `references/evals-and-benchmark.md` for the schemas, workspace layout, and what a benchmark review should surface. ### 5. REFACTOR — close new rationalizations When you read the transcripts (not just outputs) from the with-skill runs, look for: - **Repeated helper scripts** the subagent wrote independently — bundle one into `scripts/`. - **New rationalizations** the skill didn't counter — add them to a rationalization table in the body, keep the *why* attached. - **Instructions the model ignored** — they're likely too abstract or too rigid; rewrite as a principle with a concrete example. ### 6. LINT — automated audit ```bash python scripts/lint_skill.py --path # or: python scripts/lint_skill.py --dest ~/.claude/skills --json ``` Checks (see `references/lint-rules.md` for the full list): - Structure: `SKILL.md` present, optional `README.md`, `CHANGELOG.md`. - Frontmatter: `name` + `description` required; `description` starts with "Use when"; `metadata.version` is semver; `tags` present; `description` ≥ 80 chars (below = almost never enough trigger info). - **Description anti-pattern**: warns if the description reads like a workflow summary ("then ... next ... finally ..."). When the description describes *what* the skill does, the model follows the description and skips the body. Keep it strictly "when to use". - Body: no `TODO` placeholders left, ≤500 lines, interactive skills mention `AskUserQuestion` (or explicitly declare non-interactive). - Scripts: Python CLIs use `argparse`, no `pip --break-system-packages` in production code paths. Fix `error`-severity findings before shipping. Treat `warn` as a checklist. ### 7. BUMP — semver + CHANGELOG ```bash python scripts/bump_version.py --path \ --type patch \ --message "primary change summary" \ --change "additional bullet" \ --change "additional bullet" ``` | Bump | Use for | |------|---------| | `patch` | Bug fix, wording, frontmatter tweak, CJK rendering fix | | `minor` | New CLI flag, new option, new reference doc, expanded scope | | `major` | Breaking CLI change, removed option, renamed skill | Stay in `0.x` until the skill has stabilized across real use. The script updates `README.md` version badge, `SKILL.md` frontmatter `metadata.version`, and prepends a dated entry to `CHANGELOG.md` (auto-created in Keep-a-Changelog format if missing). ### 8. OPTIMIZE trigger description (optional, full track) Build a 20-query eval set (≈10 should-trigger, ≈10 near-miss should-not-trigger) and iterate the description against it. Split 60/40 train/test and pick the winner by **test** score, not train, to avoid overfitting. See `references/description-optimization.md` for the "when-to-use-only" rule, a worked set of good/bad description examples, and how to write realistic near-miss queries. ### 9. PACKAGE / SYNC - **Single-location deploy** (most users): the skill is already live in `~/.claude/skills//`. Verify with a fresh conversation. - **Multi-platform library** (shipping several skills to other people / agents): lay the repo out as `skills//…` and ship plugin manifests so one command installs everywhere: ```bash npx skills add / # auto-detects CC / Codex / Cursor / OpenCode / … npx skills add / -g --all ``` Manifests: `.claude-plugin/plugin.json` + `marketplace.json`, `.codex-plugin/`, `.cursor-plugin/`. Add `CONTRIBUTING.md` (required contract + PR checklist + Conventional Commits) and a parallel `README.zh-CN.md`. Full guide: `references/shipping-a-skill-library.md`. - **Source-of-truth sync**: keep one source repo, symlink `~/.claude/skills/`, and `rsync` outward to any distribution repo. Never let copies drift — an installer must get the same bytes as your local source. --- ## The Three Iron Laws ### 1. No skill without a failing test (or a documented reason why) If you skipped RED, write one sentence in the skill's commit message explaining why: *"Lightweight track, pure reference, verified by eyeballing the rendered output."* Forcing yourself to justify it in writing prevents lazy skipping. ### 2. Description = what + when, **never how** Anthropic's official shape is `. Use when .` — state the capability AND the triggering conditions, third person. The red line is the **workflow**: when the description summarizes the *steps*, the model follows the description **instead of reading the body**. A description saying "performs code review between tasks" (a how) caused the model to do ONE review; the skill required TWO. "Reviews code for X. Use when executing plans with independent tasks" (what + when) fixed it. So: name what it does and when to fire — never recite first/then/finally. The lint's `FM_DESC_WORKFLOW_SUMMARY` enforces the *how* red line, not the *what*. See `references/top-skills-playbook.md` § The description is the product. ### 3. Violating the letter = violating the spirit If the skill says "run lint before bump", running bump first and lint after "because it's faster" is a violation. The letter exists because the spirit isn't self-enforcing. When tempted to bend a rule, **update the skill instead** so the rule reflects your current judgment. --- ## When NOT to create a skill Push back on the user — politely — if: - The task is a one-off; skills are for repeated patterns. - The rule is mechanically enforceable (regex, linter, type system). A skill documents judgment calls; automate the rest. - The project-specific convention belongs in `CLAUDE.md`, not in a globally loaded skill. - There's already a skill doing this; **improve the existing one** rather than forking. --- ## Rationalization Table — watch yourself for these | Excuse | Reality | |--------|---------| | "Skipping RED because the skill is obvious" | Obvious to you ≠ obvious under pressure. Takes 3 minutes. Run it. | | "I'll polish the description later" | Description is the only thing that makes the skill discoverable. Polish it before shipping, not "later". | | "Just this once I'll summarize the workflow in the description" | The model will shortcut past the body. This is the single most tested failure mode. | | "The lint warning isn't a real problem" | If you're right, fix the lint rule. If the rule is right, fix the skill. Don't suppress. | | "I'll bump version later" | Every change without a CHANGELOG entry is a loss of history. Bump now. | | "It's working for me" | A skill's job is to work for **future Claude** in conversations you won't see. Test from that stance. | --- ## Where to go next - `references/top-skills-playbook.md` — the distilled quality bar from the top-50 starred skill repos: two schools, description craft, progressive- disclosure hard rules, degrees of freedom, anti-patterns, pre-ship checklist. - `references/prd-to-skill.md` — PRD → finished top-tier skill: ingest/classify, derive evals from acceptance criteria, the PRD intake template. - `references/router-and-workflows.md` — the two skill shapes, when to use a router, anatomy of routers/workflows, the Evidence Contract pattern. - `references/shipping-a-skill-library.md` — multi-platform packaging (`npx skills add`, plugin manifests), CONTRIBUTING contract, Conventional Commits. - `references/frontmatter-spec.md` — every field, when to set it, common mistakes. - `references/tdd-for-skills.md` — RED pressure scenarios, subagent prompts, rationalization capture. - `references/description-optimization.md` — the "when-to-use-only" rule, good vs bad examples, iteration loop mechanics. - `references/evals-and-benchmark.md` — evals.json schema, workspace layout, benchmark review, grading assertions. - `references/lint-rules.md` — full list of lint checks, severities, and the reasoning behind each.