About
Every session starts from nothing. These files don’t.
A skill is a procedure I got tired of typing. Once it is a file, Claude Code reads it before it starts work instead of waiting for me to explain the job again.
The second reason is narrower and took longer to notice: the same request, made twice, tends to come back in two different shapes. These files exist to take that variation out of the parts where it was never wanted.
Two problems worth a file
Neither is visible the first time. Both are obvious by the tenth.
01
Explaining the same thing again
Conventions, checklists, the definition of done — none of it survives the end of a session. Without a file, every project pays for that context again in the first ten minutes. Writing it down once moves the cost to a write instead of a re-explanation.
02
The same ask, a different answer
Ask for a landing page twice and you get two different ideas of what a landing page is: different sections, different depth, different idea of finished. A written procedure pins the steps and the checks, so what varies is the prose rather than the work.
What is actually in one
Three things, in one SKILL.md. Everything a skill does, it does by being read.
- The front matterTwo lines at the top: a name, and a description. The description decides everything — Claude Code reads it to work out whether the skill applies to what you just asked for, so a narrow one fires when it should and a vague one fires constantly.
- The procedureSteps in the order they have to happen, written as instructions rather than advice. Most of the length is here, which is why one skill is 654 bytes and another is 77 KB — the size tracks how much of the task is actually decided in advance.
- The checksWhat has to be true before the work counts as finished — pass or fail, not a suggestion. This is the part that keeps two runs of the same skill from disagreeing about whether they are done.
What they are not
Not a framework. There is nothing to install and nothing to import: copying a folder is the whole setup, and deleting it is the whole uninstall. Nothing in this repository runs.
Not general, either. Each one was written for a task I repeat often enough to have opinions about, which is why the descriptions stay narrow. A skill that claims to cover everything gets invoked for everything, and then you are back to guessing — which is the problem it was supposed to solve.
And not finished. They change whenever a run comes back wrong, which is the honest argument for keeping them as plain Markdown: fixing one is editing a paragraph.