skillify

Core insight: A tough problem solved once should be solved once. Capture the method (not the incident), wire it into every runtime, and make it auto-surface, so future-you and the other agents never re-derive it.

The trigger (when to run; this is the automatic part)

Run skillify right after solving a problem where the solution generalizes. The test: "Would future-me, or another agent runtime, on a DIFFERENT project benefit from this?"

When in doubt and it's borderline-specific, write a CLAUDE.md lesson, not a skill. Don't clutter the registry: a skill that's too narrow never fires.

The process

1. Extract the METHOD, not the incident

Strip the project specifics. Keep the transferable decision rules, the gotchas, the anti-patterns. The skill reads like a playbook, not a postmortem. ("When X, do Y because Z; watch for gotcha W", not "on 2026-06-05 we hit...").

2. Write the SKILL.md in the house format

~/.claude/skills/<kebab-name>/SKILL.md:

• Frontmatter name + description. The description is load-bearing: it's what makes the skill auto-surface, so list the concrete SYMPTOMS and PHRASES a future session would say ("the token keeps expiring", "make this a fortress"). Vague description = never fires.
• Body: Core insight (one line) → the decision/process → a gotchas / anti-patterns table → a checklist. Tight: ~80–130 lines. Reference sibling skills by name. Match the tone of existing ~/.claude/skills/*/SKILL.md.
• House rules: no em dashes in any output; concrete over abstract.

3. Choose scope FIRST, then register (this is what makes it STICK)

DEFAULT to PROJECT scope. Most skills are learnings about one app's quirks (its detection, outreach, deploy, auth). Write them to <project>/.claude/skills/<name>/SKILL.md so they only load in that project and don't clutter every global session. Reference them from that project's CLAUDE.md. Do NOT global-register or broadcast project-specific skills (standing rule).

Promote to GLOBAL only for genuinely cross-project tooling: meta/reasoning skills (like skillify, problem-breakthrough) that apply on ANY project. For those, run your registration script if you have one (the name below is an example):

~/bin/skill-register <kebab-name> [category]   # symlink into your other runtimes + auto-memory + reindex

It symlinks into your other agent runtimes' skill directories (symlink never copy), adds an auto-memory pointer, and re-indexes your notes/search index if you keep one. Without a script, do those steps by hand. THEN, for a global skill, you still: add a **Last updated:** entry atop your shared cross-agent memory file (prose: what it is + a note that your other runtimes apply it when work matches), and if broadly applicable, add it to the "Standing skill directives" section of your global CLAUDE.md.

For a PROJECT-scoped skill: skip registration / cross-runtime symlinks / shared memory entirely; just add the lesson + skill reference to that project's CLAUDE.md.

4. Verify the wiring

Confirm the skill resolves in EVERY runtime you registered (e.g. ~/.claude/skills/<name>/SKILL.md and each other runtime's skill directory). A registration script should print this check for you.

Make future application automatic

The skill only pays off if it FIRES later. Two levers:

• Description quality (step 2): the matcher keys off it.
• The standing habit in your global CLAUDE.md: a "Standing skill directives" section lists the high-value skills to ALWAYS apply when work matches, and says to skillify new wins. When you create a broadly-applicable skill, add it to that list too.

Anti-patterns

Checklist

• Solution genuinely generalizes (passed the "different project" test)
• Method extracted, not the incident
• SKILL.md written, description rich with trigger phrases, tight + house-format
• Registered globally only if cross-project (cross-runtime symlink + auto-memory + reindex)
• Shared cross-agent memory entry added (other-runtimes directive)
• Project runbook updated if project-specific
• Added to your global CLAUDE.md "Standing skill directives" if broadly applicable
• Resolves in every registered runtime