creating-skills

name	creating-skills
description	Use when a task type has occurred twice, when the user says "always do it this way", or when following a skill produced a bad result — extract or improve a skill.
version	3

Creating Skills

Recurring work becomes a skill; failing skills get improved. This is how the system learns — without it, every session starts from zero.

When

• The same shape of task has happened twice → skill, named after the task (import-monthly-csv, generate-quarterly-report).
• The user states a standing preference ("always format dates like this") → skill, or a line added to the existing skill that owns that territory.
• Following a skill produced a bad result → improve THAT skill now: fix the instruction, bump version, journal what went wrong and what changed (journaling skill).

Writing one

• A folder with a SKILL.md; frontmatter: name, description, version (plain integer, bump on every change).
• The description is a TRIGGER, not a topic: "Use when ". A skill that never fires is dead weight — write the description for the moment of need.
• Short, imperative steps. Reference material goes in extra files in the skill folder, loaded only when needed.

Where a skill lives

Every skill of this tool lives in this repo's .claude/skills/. Nothing is installed machine-wide: skills here load in this project and nowhere else, so improving one can never change how Claude behaves in the user's other projects. Edit the skill in place and bump its version:.

If the improvement is generic — it would help ANY project using this setup, not just this tool — also offer to carry it back to the kit: the project's own kit handshake file (if it has one) records kit_origin. If that is a local folder, apply the same change and version bump there and journal it in both places. If it is only a URL, or the user does not want to bother, journal the improvement here with a "not carried back" note and move on; the tool keeps working either way.

Proven patterns

• One create-X skill per recurring content type — a family of small, named skills beats one generic "do stuff" skill.
• Mature tools: extract <tool>-reference / <tool>-how-to project skills from overgrown docs (see documenting), marked "extracted from X — keep in sync".