I read Matt's skill source: the four rules he writes good skills by (and caught him deleting caveman)

30-second TL;DR

A good skill has exactly one goal: predictability — same situation, same process, every time. Four rules serve that goal, each with its own anti-example:

How it triggers: model decides when to use it (and pays context for that), or only fires when you call it by name. Wrong pick = context burned for nothing.

How much to put in: SKILL.md keeps only what every path needs; the rest sinks to linked files. Anti-examples: sprawl, sediment.

Which words to use: borrow a concept the AI already knows as the leading word — one word anchors a whole behavior. Anti-examples: no-op, duplication.

How it finishes: every step gets a verifiable completion criterion. Anti-example: stopping before the work is done.

All four come from Matt Pocock’s writing-great-skills. All four anti-examples are real, pulled from his own commit history.

I read through Matt’s skill source

Same / invocation, different outcomes: some skills finish the job every time, some are hit or miss. The difference isn’t luck. It’s how they’re written.

Nobody reads skill source. I did, so you don’t have to. I went after Matt Pocock — the guy who built a whole set of AI-collaboration skills. He wrote a neat one: a skill about how to write good skills (writing-great-skills). I read that, plus the source and commit history of a few dozen of his other skills, and pulled out four rules.

Four rules, each with an anti-example. None invented — every one is from Matt’s own commit history, mistakes he made and then fixed. If even he had to go back and fix them, the trap is real.

Learn the four and you write better skills. Don’t write skills at all, and you still pocket his method for wringing determinism out of a random machine.

A good skill has exactly one standard: predictability

The model is stochastic. Ask the same question twice and you might get two different answers. The entire point of a skill is to squeeze determinism out of that random machine: make it run the same process every time.

“A skill exists to wrangle determinism out of a stochastic system.” — Matt, writing-great-skills

Note: the process, not the output. Brainstorming should throw up different ideas each time, but the way it unfolds should be steady.

One standard judges a skill: predictability. The four rules below all serve it.

Rule 1 · How it triggers: do you call it, or does the model decide?

First call when writing any skill: should the model decide on its own when to use this, or should it fire only when you call it by name? Technically it’s one switch — whether you write a description.

Model-invoked (has a description): the AI can see it and decides when to use it. The price is that the description sits in context every single turn, eating tokens and attention. Call that the context load.
User-invoked (set disable-model-invocation): the description is stripped, the model can’t see it, and it starts only when you type the name. Costs the AI nothing. The price moves to you: you have to remember it exists. Call that the cognitive load.

The principle: let it auto-trigger only when the model (or another skill) genuinely has to reach it on its own; otherwise make it manual and pocket the zero context load.

Anti-example: a skill you only ever invoke by hand, but you left the description on, so it squats in your context every turn for nothing.

Real example: Matt has weighed this exact trade-off both ways. He first deleted the disable-model-invocation switch on grill-with-docs — letting the model auto-trigger it — then in the latest version added it back, returning to pure manual. Same switch, deleted then re-added. That back-and-forth tells you “auto or manual” is a real decision, not a default to set on autopilot.

How you use it: default to manual, save the context first. Give it a description only when you actually need the model to judge “now’s the time.” A one-line check: “Who needs to reach this skill?” If the answer is “only me,” make it manual.

Pile up enough manual skills and you can’t keep track of them — that’s cognitive load overflowing. The fix is another skill: a router skill, a manual one that lists the others and tells you which to use when. Matt’s ask-matt does exactly this.

Rule 2 · How much to put in: SKILL.md keeps only what every path needs

Information ladder: anything every usage path needs goes in the SKILL.md body; anything only some cases need sinks to a separate linked file, with the body keeping a one-line pointer (“go read that when you need it”). The point is to keep the top clean — pile too much in and the action the AI should actually take gets buried.

Two anti-examples, both named:

Sprawl: cram everything into one file and it grows without end. Even if every line is correct and non-repeating, length itself is the disease — the AI has to wade through a wall of text before it reaches the work.
Sediment: old content gets added but never removed, layer on layer, until whoever comes next has to dig like an archaeologist to find the part that still applies.

Real example: grill-with-docs started as a fat monolith — interview logic, doc formats, ADR templates, all in one file. Matt split it three ways: the interview half became grilling, the documentation half became domain-modeling, and even the ADR and glossary format files sank into domain-modeling. What’s left of grill-with-docs is a one-line shell that wires the two together. That’s the information ladder used to put a bloated skill on a diet.

How you use it: go back and cut after you write. For each line, ask “does every path need this?” If not, sink it to a link or delete it outright. A crude but reliable instinct: the shorter the SKILL.md, the more it’s down to the trunk, the more dependable it tends to be.

Rule 3 · Which words to use: borrow a concept the AI already has

This one’s the most counterintuitive. It took me a while to get it.

Leading word: a concept the AI already learned in training, carrying a full set of associations. Not limited to jargon — games, the military, medicine, everyday idioms all count, as long as the AI gets it on sight. Write it into a skill and you don’t explain anything; it pulls up the whole chain of behavior.

Examples (all borrowed, none invented by Matt):

fog of war (from games / the military) → the AI instantly gets “you can’t see ahead, act on the local information you have.”
tracer bullets (from The Pragmatic Programmer) → “punch one thin end-to-end path through first, confirm the direction, then add the rest.”
triage (from the ER), caveman (cut the talk), grilling (interrogate) — grab an existing concept and use it.

Where to find them: state the behavior you want clearly, then work backwards — “which existing word or reference already means this?” Fish in idioms, famous books, methodologies, games and the military, medicine and sports. Everything the AI has read is your vocabulary.

How to check it — the no-op test: write the word alone, no explanation, and does the AI do what you wanted? If yes, it’s a real leading word, cashing in the AI’s prior. If you still have to explain it at length, the word isn’t pulling weight and you’ve landed in an anti-example:

No-op: a line the AI was going to follow anyway. “Be thorough,” say — the AI is already somewhat thorough, so the line does roughly nothing. The fix isn’t more explanation, it’s a sharper word: “be thorough” → “relentless.”
Duplication: the same idea written several times over. It costs maintenance (change one, change them all) and inflates that idea’s weight in the AI’s eyes.

Real example: Matt takes a knife to both. He tightened the review skill in a commit whose message says, in plain text, “single-sourced rules, no-op cuts” — merging duplicate rules, cutting no-op lines. He even went back to writing-great-skills itself and hunted no-ops down to the sentence level.

How you use it: don’t describe the behavior in a full sentence — find an existing word to hook it. Then pull out every adjective and adverb and run the no-op test: delete it, does the AI’s behavior change? If not, it’s water. Cut.

Rule 4 · How it finishes: every step needs a verifiable completion criterion

A skill is usually a chain of steps. Whether each step is actually done comes down to a completion criterion.

A good one does two things. It’s verifiable — the AI can objectively call it “done” or “not done,” not eyeball it. And it’s exhaustive where it should be — “account for every model you changed,” say, not a vague “list the changes.”

Anti-example · premature completion: the criterion is fuzzy (“reach consensus,” “fully understood”), the AI can’t reach a clear boundary, and its attention slides from “finish the work” to “be done with it” — drifting to the next step before the current one is actually done.

There’s a companion effect: if the AI can see what steps are queued up next, the pull toward “hurry up and move on” gets stronger. One fix is to hide the later steps in another skill, so the current step isn’t itching to rush ahead.

Real example: grilling (the interview half split out of grill-with-docs) has one signature move — ask one question, wait for your answer, only then ask the next. Its leading word is “relentless.” Splitting the interview and the documentation into two skills serves the same end: don’t let the AI grill you while it’s already thinking “finish the questions, get to the docs” — it’ll cut corners. Split them, and the interview step is just the interview.

How you use it: write each step’s finish condition as verifiable and, ideally, exhaustive (“every X gets…”, not “close enough”). If you catch the AI jumping the gun on some step, move the later steps into a different skill.

Use the four rules on a strange case: why did he delete caveman?

Take the four rules to a real crime scene.

The caveman from our first article (make the AI shut up and just say the thing) is gone from Matt’s repo now. Deleted. The record is plain:

Late May, he deleted the entire caveman SKILL.md, with a commit message that just said “streamline.”
Two weeks later, he cleared the leftover references in the README and the plugin manifest.
No new skill took its place. Just deleted.

Why? Run the four rules over it and it clicks: caveman was a manual skill, so it cost your cognitive load — you had to remember it was there. And what it did (cut the talk, drop the pleasantries) you can get from a single instruction, or one global output-style setting. Not worth a slot in your head. Deleting it is pruning at the level of the whole skill set, cutting load that doesn’t pay for itself.

One honest caveat: Matt’s commit message only said “streamline,” nothing more — this is my reading through this framework. But the framework gives a coherent explanation, and that’s exactly what it’s for.

The four rules aren’t just a checklist for writing skills. They explain why a real skill lives or dies.

Cheat sheet

Rule	Do	Anti-example	One-line check
How it triggers	`description` only if the model must reach it; otherwise manual	context load burned for nothing	”Who needs to reach this skill?”
How much to put in	SKILL.md keeps only what every path needs; sink the rest	sprawl / sediment	”Does every path need this line?”
Which words to use	borrow an existing concept as the leading word — one word anchors a behavior	no-op / duplication	”Delete this line — does the AI change?”
How it finishes	every step gets a verifiable, exhaustive completion criterion	premature completion	”Can the AI objectively call this step done?”

The one standard: predictability — same situation, same process, every time. All four rules serve it.

Last word

Four rules. Use them directly when you write a skill. And if you never write one, the thinking underneath — how to wring determinism out of a random AI — still makes you steadier at driving the AI day to day. That’s the real payoff of learning from someone good: you don’t walk away with a few rules, you walk away with their judgment.

This is original teaching content from usesuperpowers.com. It breaks down Matt Pocock’s writing-great-skills (and its GLOSSARY.md), from mattpocock/skills, used under its MIT license, at version 6eeb81b. Every “real example” in this article can be found in that repo’s commit history (commit links attached).

Same series: Part 1 · caveman · Part 2 · grill-with-docs