Capture the current session as a reusable skill — staged as a candidate by default, or live only when the user explicitly asks for a live/active skill.
Install
npx skillscat add kirodotdev/kirocrew/crystallize Install via the SkillsCat registry.
Crystallize a session into a skill
Use this whenever the user asks to capture work as a reusable skill —
"crystallize this", "create a skill", "save this as a skill", "make this
reusable", or "turn this into a skill". This is the on-demand counterpart to
the automatic post-session skill generation: the user is telling you now that
the work is worth keeping.
Two modes, chosen from the user's wording:
- Candidate (default). Stage the skill in the pending queue for human
approval. Every phrasing above means this unless the user says otherwise. - Live (explicit only). Write the skill straight to a live,
immediately-loadable location, bypassing approval. Take this path ONLY
when the user explicitly says "create a live skill" or "create an active
skill" (or confirms it when asked). Never infer it from a plain "create a
skill" — that stays a candidate.
When to use
- The user says any trigger phrase above (candidate mode), or explicitly asks
for a "live" / "active" skill (live mode). - The session demonstrated a procedure that will recur — one a future
session, working on a DIFFERENT target, would run again substantially
unchanged: a repeatable debugging method for a class of error, a fixed
command/API sequence, a verification technique, a research-synthesis flow.
Apply the same recurrence test the automatic pass uses: name the future session
that would load this skill and the different target it would run against. If the
only honest answer reuses this session's own artifact — this bug, this file,
this component, this one question — the procedure does not recur. Effort is not evidence of recurrence: a long, many-step, genuinely difficult session is still one-off if its steps were chosen for one target.
Do not crystallize a task done once and now finished (a specific bug's fix,
a one-time audit or trace of one component, a migration, a probe run to answer a
question that is now answered), a design or planning discussion, a narrative of
what happened in this session, a trivial one-shot answer, a one-off failure, or
a session that touched credentials / sensitive paths. Being asked does not make a one-off reusable — but the call is the user's, not yours. When the session carries no recurring procedure, say so and name what makes it one-off, then let them decide; if they still want it captured, crystallize it. Never silently decline a direct request.
Procedure
Reconstruct the procedure from the whole session — including sub-agents.
Read back over the conversation and, critically, parse any[Subagent completion event]messages: each carries what a sub-agent was
tasked with and the working path it found. Fold those into the procedure so
the skill captures the successful route, not the dead ends.Check for an existing skill first (cross-source dedup). Look at the
current auto-generated skills (Skills tab → theauto/group, or ask). If
this procedure essentially duplicates one that already exists, freshen
that existing skill instead of creating a near-duplicate — and if a
consolidation pass would also capture this same session, don't stage a
second copy.Write prose by default; add a script only when determinism earns it.
Most skills are judgment or workflow guidance and should be plain prose
steps — that is the expected shape. Reach for a helper script only when
part of the procedure is genuinely deterministic and error-prone to
re-improvise: a fixed multi-command chain, a set API sequence, or a fiddly
file transform. If prose captures it clearly, do not write a script. When a
script truly is warranted, it must be Python (so it runs on
macOS/Linux/Windows), must not access credentials, wipe files, or call
unknown network hosts, and must stay under 4 KB. A staged candidate's script
is statically validated and requires human approval before it can run; a
live-mode script (step 4b) gets no such check, so you must hold it to these
same limits yourself.Choose the destination — candidate by default, live only on an explicit
request. First resolve your KiroCrew skills directory — the SAME directory
that holds theauto/group you inspected in step 2 (honor$KIROCREW_HOME
if set; do not assume a literal~/.kirocrew, since migrated installs
live elsewhere).(a) Candidate — the default. For "crystallize", "create a skill",
"save this as a skill", "make this reusable" and every other phrasing, stage
to the pending queue so a human approves before anything loads. Create<skills-dir>/auto/.pending/<slug>/(<slug>kebab-case, 3–64 chars,
starting and ending with a letter or digit — a name outside that shape is
silently skipped by the pending list and cannot be approved) withSKILL.md:--- name: auto/<slug> description: <=150 chars, starts with a verb triggers: <3-8 comma-separated keywords/phrases> source: auto session_key: <this session> created_at: <ISO-8601 UTC> --- # <slug> (auto-generated) ## When to use ... ## Steps ... ## Gotchas ...Always add a
.meta.jsonnext toSKILL.md— the pending list/detail API
reads the candidate'sdescription,triggers,name, andsourcefrom it
(there is no SKILL.md-frontmatter fallback), so without it the candidate
shows blank in Skills → Pending review and dedup loses its match data:{"slug": "<slug>", "name": "auto/<slug>", "source": "crystallize", "created_at": "<ISO>", "description": "...", "triggers": "...", "has_scripts": <bool>, "scripts": [...], "kind": "new"}.
Onlyscripts/is conditional: if you generated a script, put it underscripts/<name>.pyin that folder, set"has_scripts": true, and list it inscripts; for a prose-only candidate use"has_scripts": false, "scripts": [].Freshening an existing live auto-skill is an UPDATE candidate, not a new
one. Same pending folder, but set"kind": "update","target": "auto/<the live slug>"and"base_version": <N>— a JSON integer, theversion:frontmatter of the live SKILL.md you merged from (1 when it has
none). A quoted or missing value silently disables the approval-time check
that refuses an update merged from a stale base.
Approving an update snapshots the live file toauto/<slug>/.versions/v<N>-SKILL.mdbefore overwriting it and keeps the 20
newest snapshots, so the human can roll back.You write these files yourself, so no slug guard runs for you: the
distinct-slug allocation (<slug>-2,<slug>-3, …) belongs to the automatic
pass only. Before creating the folder, check that<skills-dir>/auto/.pending/<slug>/does not already exist (writing into it
overwrites a candidate awaiting review) and, for a NEW candidate, that<skills-dir>/auto/<slug>/does not either (approval refuses a new candidate
whose live name is taken, and it is later pruned unreviewed). If either
exists, pick the next free<slug>-2,<slug>-3, … yourself.(b) Live: ONLY when the user explicitly says "live" / "active" or confirms
it when asked. Write<skills-dir>/<slug>/SKILL.mddirectly, with noauto/prefix,.meta.json, or pending stage.Reuse (a)'s template with
name: <slug>,source: crystallize, and title# <slug>; omitsession_keyandcreated_at. Keep the same description,
triggers, and When to use / Steps / Gotchas sections.Do not overwrite an existing skill: if
<skills-dir>/<slug>/already
exists (a live or builtin skill), pick a different slug or ask the user —
the live path has no collision guard, so writing blindly clobbers it, and
unlike the pending path nothing claims a distinct slug for you. Put
any script underscripts/<name>.pyand, since no approval step runs for
you, mark it executable yourself — on POSIX,chmod +x; skip that on
Windows, where the executable bit is a no-op.In BOTH cases: do not include absolute paths, credentials, tokens, or
user PII in the body or the script.Hand off.
- Candidate: tell the user it is staged and they can review it in
Skills → Pending review — approve to make it live (and mark any script
executable), or dismiss it. Nothing loads until they approve. - Live: tell the user it is active immediately and discoverable by its
triggers (no approval needed), and point them at the file in case they want
to edit or remove it.
- Candidate: tell the user it is staged and they can review it in
Gotchas
- Default to the pending queue. Only write directly to a live location
(<skills-dir>/<slug>/) when the user explicitly asked for a "live" or
"active" skill — otherwise always stage underauto/.pending/so a human
reviews it first. - One skill per distinct procedure — don't bundle unrelated workflows.
- Keep the description trigger-class-focused (it is matched on, and truncated
in the system-prompt skill index).