Skillify

Abstract "the thing you just pulled off" into a reusable skill. This is an analyze → extract → save flow:

• Step 1 is always analysis: first decide whether the conversation / recent context holds knowledge worth distilling into a skill. If not, say so and stop — never force it.
• The placement directory and other args are only needed at the final save step — do NOT front-load a "where should it go?" question.

Applies when the user says: "abstract this into a skill", "write up what we just learned as a skill", "do this automatically next time", "skillify this", "capture this workflow".

Core goal: turn a one-time success into a stable procedure, not copy a transient chat into a prompt.

Arguments (all optional; used only at save time)

• Trailing text (after /skillify) = the object / lead to skillify; if omitted, distil from recent context.
• Placement directory <skills-dir> = where the skill lands; the canonical source goes to <skills-dir>/<slug>/SKILL.md. Only needed at the "save" step; ask only if the user hasn't provided it — never ask before analysis.

Step 1: Analyze — is there knowledge worth capturing (scan → gate)

Answer "should this even be extracted" first. Most candidates die here, not in the writing.

1a. Three-phase scan: don't miss invisible skills

Review what you just did, sweeping each phase once, asking one question per phase: is there a "non-obvious action / judgement" here?

Phase	What to scan	Why it's easily missed
Discovery	How did you locate / trigger / diagnose the real problem? Which signal did triage use?	No visible deliverable — most often missed
Decision	What justified the judgement call at the sticking point? Any reusable criterion?	Treated as "intuition", not realized it can be codified
Solution	Is the execution skeleton / tool-combo / verification reusable?	Visible — easiest to fixate on

The scan is about breadth, anti-omission: people naturally notice only "solution" (it has deliverables), while "discovery / decision" — the diagnosing and judging moves — are high-value yet invisible.

The three phases are only for scanning candidates, not chapters in SKILL.md. The body should be organized by failure mode / investigation action, not by these three categories.

1b. The real gate: don't over-extract

For each candidate, all four must pass:

• Recurs: will you hit this kind of scenario again? (One-off → a note is enough, no skill.)
• Non-obvious: is there an action / judgement you "wouldn't know without looking it up"? (Obvious things aren't worth codifying.)
• Cost: is the cost of getting it wrong / missing it high?
• Stable: is the procedure stable, not bound to this session's transient context / data?

Missing "non-obvious" or "recurs" → basically drop it.

If nothing passes the gate → tell the user "not worth a skill this time", explain why, and stop. Do not force a deliverable, and do not ask for a placement directory at this step.

1c. Merge or split: the boundary question

If discovery / decision / solution all surface candidates in one scenario, decide whether they go into one closed-loop skill or split into a combination:

• Will any single phase be invoked alone? Yes → split; always entered from the top → lean merge.
• Is the value inside a phase or at the handoff? At the handoff (upstream expected-state / contract must reach downstream for verification) → merge; each phase self-contained, handoff carries no info → splittable.
• Would merging make one unit carry orthogonal failure modes? Yes (e.g. static breadth vs dynamic-reasoning depth) → split.
• Does this phase run first in other problems too? Fan-out ≥2–3 → split into a reusable leaf.

Third state (need both): when the loop must stay intact but a phase needs depth / reuse, use orchestrator + leaf — one closed-loop skill holds the contract and verification, delegating orthogonal phases to reusable sub-skills.

Default to one closed-loop skill. Split only on a real signal (a phase reused by a second scenario, or attention spread too thin for depth).

1d. Classify: decides how to write, not whether to extract

Type	Example	Skill focus
Investigation	pull sources → build timeline → locate issue	evidence sources, steps, output template
Debug	reproduce → red test → fix → verify	invariants, tests, acceptance
Tool-combo	chain multiple log/monitor/analysis tools	query order, correlation IDs
Habit/convention	directory structure, naming, placement	path rules, naming rules
Writing template	issue / PR / retro report	structure, tone, prohibitions

Do NOT write one-off details into the skill (a transient session, a full specific chat, a temporary verification code, etc.).

Step 2: Extract — distil stable principles and draft

If 1c decided on a split or orchestrator + leaf, run Step 2 once for each skill to land (each its own directory).

2a. Distil stable principles

Break the experience into:

• Trigger: when this skill should be used
• Input: what the user might provide, what to ask when it's missing
• Evidence sources / tools: which sources, files, CLIs, logs to check
• Steps: the stable, reusable execution order
• Output: what to hand the user, or what artifact to create
• Boundaries: what NOT to do, when to stop / ask
• Verification: how to confirm the skill worked

Write principles, not a play-by-play.

2b. Choose a slug

Slug: lowercase, alphanumeric + hyphen, short and clear, verb/task- or topic-oriented. Before drafting, ls <skills-dir>/ to avoid collisions and match existing naming style (when the save dir is known).

2c. Draft SKILL.md

Use the generic-compatible frontmatter:

---
name: <slug-or-display-name>
description: "One line: what the skill does and when to use it."
argument-hint: "<optional, describe args>"
alwaysAllow: ["Bash"]      # optional
requiredSources: []         # optional
---

Suggested body structure:

# <Skill Name>

One-line goal.

## Trigger / When to use
## Preconditions
## Workflow / Steps
## Output format
## Boundaries & prohibitions
## Verification
## Examples

Writing style:

• Instructions must be executable, not vague.
• Don't write dead behaviors like "after reading, tell the user the rules are loaded".
• Action-type skills proceed by default; ask only when a key argument is missing.
• Keep concrete paths, APIs, command examples, but scrub one-off sensitive data.
• Match the existing style of the target skill library.

2d. Icon (optional)

• Prefer 3D / color / skeuomorphic style, consistent with existing visuals.
• Recommended source: Microsoft Fluent Emoji.
• Filename must be icon.svg/icon.png/icon.jpg/icon.jpeg, placed in the skill directory.
• No ad-hoc hand-drawn SVG stand-ins unless the user explicitly asks. If none fits, ask first — don't force one.

Step 3: Save — land it in the given directory

Only now do you need the placement directory <skills-dir>:

• User gave a directory up front → use it directly.
• Not given → ask now where to put it; do not pick a directory on your own.

Conventions:

1. One skill, one directory: <skills-dir>/<slug>/SKILL.md (required) + optional icon.svg / references/ / helper scripts.
2. Never drop a SKILL.md directly in the <skills-dir> root: even a single-file skill gets its own subdirectory.
3. Keep helper data/scripts in the same directory so the skill is self-contained.

mkdir -p <skills-dir>/<slug>
# write SKILL.md into that dir; include helper scripts/data if any

<skills-dir>/ IS the canonical source — no need to symlink elsewhere.

Verification

ls -la <skills-dir>/<slug>/

• SKILL.md exists, frontmatter valid, name/description non-empty
• Body non-empty with executable steps
• No hardcoded sensitive info (accounts, tokens, transient session ids)
• Slug doesn't collide with an existing one

Output to the user

When done, briefly report: skill slug, source path (<skills-dir>/<slug>/SKILL.md), whether an icon was added, whether helper scripts/data are included. Don't paste the full SKILL.md unless asked.

Key principles

• The user wants a captured capability, not a copied conversation.
• Analysis first: decide whether there's knowledge worth capturing; if not, stop — don't force it, and don't ask for a directory early.
• The canonical source always lives in <skills-dir>/<slug>/; even a single-file skill gets its own subdirectory.
• Distinguish fact / hypothesis / to-be-confirmed; don't hardcode a solution too early.