create-skill

create-skill — distill a session into a reusable skill

Closes the loop between "I've now solved X three times in slightly different ways" and "there's a skill for that." This skill does introspection + intake + first-scaffold. It hands off to writing-skills for the TDD discipline that makes the skill bulletproof.

REQUIRED SUB-SKILL: Use theclauu:writing-skills for the RED-GREEN-REFACTOR cycle after this skill scaffolds the file. Running /create-skill without following up with writing-skills ships an untested draft.

When to reach for this

Triggers:

• Session ending with a clear recurring pattern — agent reached for the same workaround 3+ times
• User correction that generalizes — "stop doing X; prefer Y" that future agents should learn
• New tooling or workflow stabilized during the session
• Gotcha that keeps coming back across sessions

Don't use for:

• One-off narratives / "what I did today" logs → use notes or memory
• Patterns enforceable by lint / CI rules → automate, don't document
• Project-specific conventions → put in project CLAUDE.md
• Anything that only appeared once → wait for the second occurrence

Procedure

Step 1 — Introspect the session

Mine the conversation + tooling in parallel:

• Transcript signals: mirror the phrases dump_session_context.py uses for gotchas (the trick is, watch out, don't forget, be careful, make sure, caveat, footgun).
• Corrections: places the user said "no, don't…" or "actually, do…".
• Repeated tool invocations: same bash pattern called 3+ times with small variations.
• Recent git + memory writes: git log --oneline --since="8 hours ago" and ls -t ~/.claude/projects/<slug>/memory/feedback_*.md | head -3 for learnings already captured this session.

Output a candidate list: 3–5 bullets, each "what happened → why it's worth a skill." If nothing rises to skill-worthy, stop here — forcing it produces a bad skill. Say so and exit.

Step 2 — Structured intake

Use AskUserQuestion to collect the following in a single batched form (not serial prompts):

1. Which pattern? Multi-choice from Step 1's candidates, plus "none of these" and "something different I'll describe below."
2. Scope? personal (→ ~/.claude/skills/<name>/) or plugin (→ PR against Artemis-xyz/theclauu/plugins/theclauu/skills/<name>/).
3. Type? technique / pattern / reference / discipline.
4. Name? Suggest 1–2 names; let user override. Verb-first, hyphen-case.
5. Trigger (description)? Free-text "Use when…". Remind: triggers only, never workflow summary (CSO trap — see writing-skills §CSO).

If the user leaves any field blank, fill in a best-guess default but mark it with TODO(create-skill) so they see where to refine.

Step 3 — Scaffold via writing-skills

Load theclauu:writing-skills and execute its GREEN phase — write a minimal SKILL.md. Use the writing-skills "SKILL.md Structure" template:

• Frontmatter (name, description per Step 2)
• Overview — 1–2 sentences, the core insight
• When to use — symptoms + "don't use for" list
• Procedure OR Core pattern (depending on Type)
• Quick reference — table the user can scan
• Common mistakes — seed from Step 1's session gotchas

Skip writing-skills' full RED phase (baseline subagent pressure testing) — that's too heavy for the session-distill flow. Mention in the "Next steps" report that the user should run /theclauu:writing-skills to validate before shipping.

Step 4 — Write the file

• Personal: write to ~/.claude/skills/<name>/SKILL.md. Usable immediately next session.
• Plugin: write to <plugin-root>/skills/<name>/SKILL.md in the local Artemis-xyz/theclauu checkout. Not usable until the PR merges and the user reinstalls — say so explicitly.

Step 5 — Report back

Scaffolded: <name>
Path:       <absolute path>
Scope:      <personal | plugin>
Type:       <type>
Next:       /theclauu:writing-skills   (pressure-test before shipping)

For plugin scope, also print:

Plugin release TODO:
  1. Bump plugins/theclauu/.claude-plugin/plugin.json → next patch
  2. Add CHANGELOG.md entry under a new ## v0.X.Y heading
  3. Update SKILLS.md (add a row in the matching category)
  4. Open PR on Artemis-xyz/theclauu

Quick reference

Stage	Input	Output
Introspect	Session transcript, git log, recent memories	3–5 candidate patterns
Intake	AskUserQuestion batched form	{pattern, scope, type, name, trigger}
Scaffold	Intake + writing-skills GREEN phase	Draft SKILL.md
Report	File path + next-steps checklist	User knows what to do next

Relationship to writing-skills

writing-skills (vendored from superpowers) is the discipline — RED-GREEN-REFACTOR, pressure testing, rationalization tables, bulletproof skills. Heavy and opinionated.

create-skill is the entry point — turns ambient session context into a starting draft. Composes cleanly with writing-skills for the later pressure-test cycle.

Don't fold create-skill into writing-skills (writing-skills is vendored; edits drift from upstream). Don't fold writing-skills into create-skill (different job — discipline vs. distillation).

Common mistakes

• Skipping the baseline test: the scaffold is a draft. Ship a plugin PR without running /theclauu:writing-skills and you've published untested documentation.
• Defaulting to plugin scope: team-wide skills are higher ceremony and need broader applicability. When in doubt, use personal — promote later if it proves reusable across projects.
• Forcing a skill from one occurrence: the rule of three. If the pattern hasn't bitten twice, it's probably not a skill yet.
• Letting the description summarize the workflow: see writing-skills §CSO. Triggers only — no "this skill does X then Y."

Related

• theclauu:writing-skills — required follow-up for pressure testing
• theclauu:session — similar session-introspection machinery (handoff mode)
• theclauu:notes — for narrative knowledge that's not yet a skill
• theclauu:heist — raid other repos for skill patterns; this skill distills from your own session