Turn a repeated workflow into a skill

01The goal

Turn a workflow you keep repeating into a project skill: a file that runs when you type its name, and that Claude loads on its own when a request matches what it is for.

02The idea

A skill is a folder holding a SKILL.md file: YAML frontmatter that says what the skill is for, then the instructions Claude follows. A project skill lives in .claude/skills/<name>/SKILL.md. Commit it, and everyone who works in the repository gets it — the same argument as CLAUDE.md, one level up: written, reviewable, versioned beats retyped.

The economics are the reason this is lesson 1. Until a skill runs, at most its description sits in the context window — a line or two. When it runs, the whole file loads. You pay for the full instructions exactly when they earn their keep, and never before. A CLAUDE.md rule is always in the window; a skill is in the window only while it works.

One frontmatter field matters for safety: disable-model-invocation: true keeps the skill to the first way only — you, typing its name. Use it for workflows with side effects, a deploy being the canonical case; Claude should not decide on its own to run a deploy. And if your repository already has files under .claude/commands/, they are the older format and still run as /name — prefer a skill for new work.

03The walkthrough

Pick the thing you have now explained to Claude three times. If nothing comes to mind, use ours: five whys, the root-cause routine — reproduce, ask why of the evidence, stop at a cause the team can fix. Create the folder and write the file yourself; reading it before it runs is the habit.

1. 01Start claude in your repo and run /skills: the list includes five-whys, marked as a project skill. If the skills folder did not exist when the session started, run /reload-skills first.
2. 02Run it by name, with a problem from your repository: /five-whys npm test fails on one machine but not the other — adjust to something real for you. Watch it reproduce, ask why of the evidence, and land on a cause. In a second terminal, git status should list nothing new: the skill said don’t change any files, and it held.
3. 03/clear, then ask a question that matches the description without naming the skill: "Why does this keep happening? I want the root cause, not a quick fix." Before Claude answers, the transcript shows the skill loading through the Skill tool — Claude found it from the description alone. That is the moment this lesson exists for.

Once a skill has run, its text stays in the conversation and Claude Code does not re-read the file — edit a skill and it reaches the session the next time it runs, not the next turn.

04Your turn

Build a test-first skill the same way, and finish it yourself: a folder .claude/skills/tdd/SKILL.md, description saying it builds small features test-first and when to use it, body running Red (write the failing test, watch it fail) then Green then Refactor — the Green and Refactor steps are yours to write, and they are the exercise. Leave disable-model-invocation off: this one should load on its own when you ask for a small feature test-first. Run it by name on something small — a slugify(heading) function, or your repo’s equivalent — approve the edits and test runs, and let it commit. Then /clear and ask for a second small feature test-first without naming it, and watch the Skill tool load it. Commit the skill.

Two guardrails worth the ink. A skill can pre-approve tools with allowed-tools, and a project skill’s grant applies even in a claude -p run in a folder you have never trusted — so read the skills in a repository before you run Claude Code there, and think hard before adding allowed-tools to your own. And keep side-effect workflows behind disable-model-invocation: true; auto-loading is for analysis, not for deploys.