/skill-creator — create an IWE skill

Scope: create a new skill OR guide an update to an existing skill in .claude/skills/ or .kimi/skills/. Not in scope: full re-scaffold without deleting the old SKILL.md first (delete manually, then call /skill-creator again); creating a WP; creating a Pack. Role: ad-hoc content-role "Skills Engineer"; formalize in Pack if ≥3 skills/year.

When to use

• Pilot wants a new skill for a repeated workflow.
• A new tool/agent/system needs a Service Clause + Role + SKILL.md.
• A skill needs promotion from author repo to IWE.

Preconditions (checked, not performed)

1. WP Gate precondition. The task must be attached to an agreed WP in the weekly plan or explicitly named by the pilot. /skill-creator does not conduct the WP Gate ritual itself.
2. Routing Gate. Decide target platform (Claude vs Kimi) and level (project vs user). Default: project-level .claude/skills/ in the author repo.
3. IntegrationGate hard-check. DP.SC.* and DP.ROLE.* must exist in the PACK repo. If not, the skill stops and offers to create them. Bypass only by explicit pilot instruction "skip gate" — no code flag.

Algorithm

Step 1 — Check WP Gate precondition

Look up the current weekly plan (current/WeekPlan W{N}.md) or ask:

Which WP is this skill creation linked to?

If no WP is named and none matches the skill topic → stop:

Creating a skill requires an agreed WP. Open a WP through WP Gate first.

Step 2 — Routing Gate

Ask or infer:

Target path:

• Claude project: .claude/skills/<name>/
• Kimi project: .kimi/skills/<name>/
• User level: ~/.claude/skills/<name>/ or ~/.kimi/skills/<name>/

Step 2.5 — Detect existing skill

Check whether <target_path>/SKILL.md already exists.

If it exists → switch to update mode. Do NOT re-scaffold. Show the pilot:

Skill <name> already exists (version X.Y.Z).
What would you like to update?
  [ ] description
  [ ] slash / phrase triggers
  [ ] version bump (current: X.Y.Z → new: ?)
  [ ] algorithm step (add / edit)
  [ ] bundled resource (add scripts/ references/ assets/)
  [ ] full re-scaffold → delete SKILL.md manually, then run /skill-creator again
  [ ] cancel → make no changes

Collect the pilot's choices. A requested description must contain at least 10 words; if shorter, explain the validation requirement and ask for an expanded wording before editing. Apply agreed changes directly to the existing SKILL.md via Edit.

Skip Steps 3–6 unless the pilot selected "bundled resource" or any change that expands the skill's scope or gates — in that case, run Step 3 (IntegrationGate) before applying.

For Step 7 (register + verify): run verify-skill.sh always. Run generate-skills-catalog.sh only if frontmatter changed (name, description, triggers, version).

Version bump rule: bump patch for trigger / description edits; bump minor for algorithm changes or adding a bundled resource; bump major for gate or scope changes.

If it does not exist → continue to Step 3 (normal creation flow).

Step 3 — IntegrationGate

Check PACK repo for files matching DP.SC.* and DP.ROLE.*. If missing:

Service Clause (DP.SC.*) and Role (DP.ROLE.*) not found.
Create them now via /pack-new or the appropriate process.
To continue without them, say explicitly: "skip gate".

Stop until the gate is satisfied or explicitly bypassed by pilot words.

Step 4 — Collect parameters (4 short steps)

4a. Name and description

Skill name (hyphen-case): <name>
Short description — what it does and when to use it:

The description must contain at least 10 words; count the YAML value, not surrounding metadata.

4b. Agents and interaction axes

agents: single | multi
interaction: one-shot | multi-step

4c. Triggers

slash commands (comma-separated):
phrase triggers (comma-separated):

Keep phrase triggers narrow: include a skill name placeholder to avoid accidental activation.

4d. Bundled resources

Which bundled resources are needed?
[ ] scripts/
[ ] references/
[ ] assets/

Default: assets/ for scaffold template, scripts/ for verify script.

Step 5 — Generate scaffold

Choose scaffold template based on skill complexity:

• Minimal (assets/skill-scaffold-minimal.md): single-step skills without external gates
• Full (assets/skill-scaffold-full.md): multi-step skills with Preconditions and Bundled resources

Copy chosen template to target path and substitute:

• {{name}}, {{description}}, {{version}} (default 0.1.0), {{status}} (default experimental)
• {{agents}}, {{interaction}}, {{layer}}
• {{slash_triggers}}, {{phrase_triggers}}
• {{gates_rationale}} — required when gates_required and gates_enforced are both empty

Create selected bundled resource directories with placeholder files.

Step 6 — Show draft

Print generated SKILL.md and file list to stdout. No P5 question. Pilot can cancel with:

/skill-creator undo

Undo works only before next commit or within 15 minutes.

Step 7 — Write files, register, verify

Write files to target path. Then regenerate the catalog and run verify:

# Run from the workspace root. Set these two paths from the routing decision;
# creator_dir is the directory containing THIS instruction, not the new skill.
skills_dir=.claude/skills
creator_dir=.claude/skills/skill-creator
workspace="$PWD"
template_root="${IWE_TEMPLATE:-$workspace/IWE}"
if [ -f "$workspace/update-manifest.json" ] && [ -f "$workspace/scripts/generate-skills-catalog.sh" ]; then
  template_root="${IWE_TEMPLATE:-$workspace}"
fi
catalog_script="$workspace/scripts/generate-skills-catalog.sh"
if [ ! -f "$catalog_script" ]; then
  catalog_script="$template_root/scripts/generate-skills-catalog.sh"
fi
catalog_output="$(dirname "$skills_dir")/skills-catalog.yaml"
if ! IWE_WORKSPACE="$workspace" bash "$catalog_script" \
  --skills-dir "$skills_dir" --output "$catalog_output"; then
  echo "Catalog generation failed; verification was not run." >&2
  exit 1
fi
IWE_WORKSPACE="$workspace" IWE_TEMPLATE="$template_root" \
  bash "$creator_dir/scripts/verify-skill.sh" <name> "$skills_dir"

Both commands must pass before the skill is considered created. For Kimi targets set skills_dir=.kimi/skills; if this instruction is installed there too, set creator_dir=.kimi/skills/skill-creator. If either tool is absent, stop with the missing path rather than claiming verification.

The verifier uses the shared workspace scripts/lib/find-python3.sh and the declared PyYAML and markdown-it-py dependencies in requirements.txt. Metadata must be the first complete YAML block; duplicate keys, invalid types, and empty required values fail. Required Markdown sections must be real headings outside code examples. Bundled resources are checked in scripts/, assets/, and references/.

Tell the user where the new skill lives and that nothing preserves it (issue #873): a project-local skill under .claude/skills/<name>/ is usually outside git and outside the day-close.sh backup, and update.sh neither erases nor carries it over. Until the template owner picks a backup model, suggest keeping a copy in a git repository the user controls.

For skills with interaction: multi-step: run /vdv audit on the Algorithm section. Not a gate — does not block creation — but catches steps with missing Input/Output linkage before the skill is used in practice.

Bundled resources

• assets/skill-scaffold-minimal.md — scaffold for single-step skills without external gates
• assets/skill-scaffold-full.md — scaffold for multi-step skills with Preconditions and Bundled resources
• scripts/verify-skill.sh — CLI wrapper using the shared Python resolver
• scripts/verify-skill.py — validates YAML metadata, gates, real sections, bundled resources, templates and platform-specific L1 location

Known schema gaps

Fields used by some existing skills but not yet in the standard frontmatter schema:

• argument-hint — CLI-style hint for script-executor skills (e.g. agent-fault, apply-captures). Encodes the argument contract. Keep until schema is extended or absorbed into description.
• routing.executor — indicates whether the skill runs via script, sonnet, or another executor. Useful for the dispatcher but not validated by verify-skill.sh. Candidate for standardization.

Until standardized: leave these fields as-is in existing skills; do not remove during Step 2.5 updates.

Known tool gaps

• content-audit.sh coverage (F9): audit script checks 5 structural criteria (gates_rationale, Algorithm section, step headings ≥3, step content ≥2 lines, When-to-use section). 7 YELLOW skills (single C3 issue) are simple alias/mode skills without numbered step headings. This is structural noise, not content error — these skills are functionally correct. See scripts/content-audit.sh for full output.

Anti-patterns

• Do not create a skill without a linked WP.
• Do not bypass IntegrationGate with a code flag.
• Do not use wide phrase triggers like "need to create a skill".
• Run generate-skills-catalog.sh after writing files (Step 7) — not before, not manually.
• Do not make the skill verify itself; use scripts/verify-skill.sh.
• Do not skip verify-skill.sh after editing an existing skill — always run it after any update.
• Do not re-scaffold for minor updates (triggers, description, version bump, algorithm); use Step 2.5 update mode instead. Exception: platform or layer change (e.g. Claude→Kimi, L1→L3) requires a new path and a fresh scaffold — delete old SKILL.md first.
• Do not forget version bump when changing gates, scope, or algorithm steps (bump minor or major).

Verification

After creation, run:

bash .claude/skills/skill-creator/scripts/verify-skill.sh <skill-name> .claude/skills

Expected result: PASS with checks for: valid YAML frontmatter, description of at least 10 words, recognized non-empty triggers, gates_required/gates_enforced fields with valid enum values, bundled resource files exist, scaffold templates valid, L1 skills present in FMT.