The Moment Your Hard-Won Knowledge Stops Living Only in Your Head

There's a technique I worked out over several projects for how to approach systematic debugging.

It wasn't in any documentation. I'd arrived at it by getting burned enough times that I stopped guessing and started building a protocol. I knew it worked. I'd seen it save hours. I'd explained it verbally to two different collaborators, one human, one AI, and both had been meaningfully more effective after.

For a long time, I considered that enough.

Then I read the writing-skills skill from obra/superpowers, and I understood what "enough" was costing me.

Expertise Is Not Leverage Until It's Codified

The skill makes a distinction I hadn't thought to make explicitly:

A skill is a reusable technique, pattern, or tool — a reference guide for proven approaches. A skill is not a narrative about how you solved a problem once.

Those two things feel similar from the inside. They aren't.

A narrative is useful to the person who already roughly understands the domain. It's memorable. It communicates judgment in context. But it doesn't transfer cleanly, and it doesn't scale. Each time you want someone else to benefit from it, you have to tell the story again, adapt it to the new situation, hope the important parts land.

A skill is a specification. It says: when you encounter this class of problem, here is the proven protocol, here is why each step exists, here are the failure modes the steps prevent. Anyone — any agent, any collaborator, your future self in six months — can load it and apply it without you in the room.

The difference between expertise and leverage is whether it exists only in your head.

The TDD Frame That Makes Writing Skills Honest

What writing-skills does that nothing else has done for me is apply test-driven development to documentation.

The process is: before you write the skill, watch an agent fail without it. Document the exact rationalizations the agent used to justify skipping the thing you know matters. Then write the skill to address those specific failures. Then verify the agent now complies.

This requirement is ruthless in a useful way.

It means you can't write a skill based on vibes. You can't write it based on "this is how I think about it." You have to be able to watch an agent go wrong without it, which means you have to have a concrete scenario in which the skill matters, which means you have to know exactly what the skill is teaching.

Most knowledge doesn't survive that test in its first form. You think you're codifying a principle, and then you watch an agent find three ways around it, and you realize you were describing your intuition, not the actual rule.

The baseline scenario forces precision.

What Decides Whether Something Becomes a Skill

The skill gives a set of criteria. Create a skill when the technique wasn't intuitively obvious to you, when you'd reference it again across projects, when it applies broadly rather than to a specific codebase, when others would benefit.

The most important of those is the first one.

If something wasn't intuitively obvious to you — if you had to earn the knowledge — there's a high probability it isn't obvious to the agents you work with either, or to future collaborators, or to yourself three months from now when the context has faded and you're looking at a familiar class of problem fresh.

The skills that have paid off most for me are the ones that encoded something I genuinely had to learn the hard way: a failure mode I'd hit enough times that I finally built a protocol for it, a sequence of steps I kept getting wrong until I locked down the order.

That's the signal. If you've made the same mistake enough times to have a protocol for not making it, you have a skill. The question is whether it lives in your head or somewhere accessible.

The Compound Effect

Here's what I didn't anticipate: once you have even a small collection of skills, the act of writing new ones accelerates.

Your existing skills become references. They inform each other. You start recognizing skill-shaped things earlier — not just after you've solved a problem, but sometimes before you start, when you notice that you have strong opinions about how this class of thing should go, opinions you'd have to justify if someone asked.

That moment — when you notice you have implicit opinions worth making explicit — is the moment a skill wants to be written.

I now think of writing-skills as: the practice that converts what I've learned into something I can actually use again — without needing to remember how I learned it.

---

Part of the Superpowers series — 14 specialist skills from obra/superpowers.