The best prompting I've seen doesn't trust the model at all

I unpacked the copy of Jesse Vincent's Superpowers sitting in my own plugins cache and read all of it. Fourteen skills, three slash commands, one session-start hook, one subagent definition. Every skill is a markdown file with two lines of YAML on top: a name and a description saying when to use it. That is the whole format. No DSL, no schema, no runtime.

I care because I write prompts for a living and most of mine are suggestions. Superpowers is the first prompt system I've read that starts from the assumption that suggestions do nothing. If you configure agents at all, that assumption is the part worth stealing, whether or not you ever install the plugin.

What is actually in the folder

The skill bodies are the interesting part, but the shape comes first, so here is the inventory.

skills/ holds the fourteen: brainstorming, writing-plans, executing-plans, test-driven-development, systematic-debugging, requesting-code-review, receiving-code-review, subagent-driven-development, dispatching-parallel-agents, verification-before-completion, using-git-worktrees, finishing-a-development-branch, writing-skills, and using-superpowers. commands/ holds three thin wrappers (brainstorm.md, write-plan.md, execute-plan.md) that exist so a human can type a slash command instead of hoping the model picks the right skill on its own. agents/code-reviewer.md defines a second model whose only job is finding what the first one got wrong. hooks/hooks.json registers a single hook on SessionStart, matching startup|resume|clear|compact.

The description line is doing more routing work than it looks like. Skill descriptions read as trigger conditions, not summaries: verification-before-completion describes itself as being for when you are about to claim work is complete, fixed, or passing, before committing or creating PRs. So the model carries a short list of names and conditions, and pays for a full skill body only when one of the conditions matches. That's why fourteen skills fit somewhere a fourteen-file soul document never would.

The hook file is four lines of config and it does more than anything else in the repo. Every time a session starts, resumes, clears, or compacts, the hook fires and puts the skill index back in front of the model. Compaction is the case that matters. Long agent sessions lose their instructions to the summarizer, and a rule the model can no longer see is a rule that doesn't exist. The hook reinstalls the rules at exactly the moment they would otherwise evaporate.

The rule that does all the work

using-superpowers opens with a block wrapped in an EXTREMELY-IMPORTANT tag, and the first sentence is this: if you think there is even a 1% chance a skill might apply to what you are doing, you absolutely must invoke it. The lines under it say you do not have a choice, this is not negotiable, and you cannot rationalize your way out of it.

Read that as prose and it sounds unhinged. Read it as a threshold and it's obvious. A model asked "should I use the careful process here?" answers no far more often than it should, because no is cheap, fast, and usually survives contact with the user. Setting the bar at 1% doesn't make the model more careful. It removes the question. A wrong yes costs you one skill file loaded for nothing. A wrong no costs you silent sloppiness you find in review, if you find it.

That's the thesis of the whole plugin as far as I can tell, and it travels well past Claude Code. Anywhere you have typed "please consider" into a system prompt, you handed an effort decision to something with no stake in the outcome.

It legislates against excuses, by name

The part I didn't expect is a table called Red Flags. Twelve rows, each pairing a thought with its rebuttal. "This is just a simple question" is answered with "questions are tasks, check for skills." "The skill is overkill" gets "simple things become complex, use it." "I remember this skill" gets "skills evolve, read the current version."

So, that's a list of the model's own excuses, written down in advance, in the model's own phrasing. It isn't instruction, it's inoculation. The rationalization shows up, the model finds its exact wording sitting in a table headed Red Flags, and the escape hatch is gone before it gets used.

test-driven-development does the same job with more teeth. The Iron Law is set as a code block: no production code without a failing test first. Then comes the enforcement, which is the part that makes it structural instead of aspirational.

You are an expert engineer.
Please follow test-driven development
where appropriate, and try to write
tests before implementation code.
Use best practices.

## The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

**No exceptions:**
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Don't look at it
- Delete means delete

"Delete means delete" is in there because the obvious cheat is to write the implementation, then write tests describing what you already built, then call it TDD. The file shuts that door, including the softer version where you keep the old code in view and copy from it. It also names the thought that comes right before the cheat: thinking "skip TDD just this once"? Stop. That's rationalization.

The same trick, pointed at the word "done"

verification-before-completion has its own Iron Law, and it is the one I'd install first if I could only take one file: no completion claims without fresh verification evidence. The line under it defines fresh, which is the part that stops the cheat. If you haven't run the verification command in this message, you cannot claim it passes. Not "I ran it earlier." Not "it was passing before the refactor." In this message, or the claim isn't allowed.

The overview says claiming work is complete without verification is dishonesty, not efficiency. That's a strong word to put in a config file, and it's aimed at the single most expensive failure mode in agent coding. An agent that writes a bug costs you a review cycle. An agent that says "fixed and tested" about a bug it did not fix costs you the review cycle plus your trust in every other green checkmark it ever gave you.

writing-skills closes the loop by applying the discipline to itself. It says writing a skill is TDD applied to process documentation: put an agent in the situation without the skill, watch it fail, write the skill, watch the failure stop, then refactor to close the loopholes the agent found. The core principle is stated the same way as the code version. If you didn't watch an agent fail without the skill, you don't know whether the skill teaches the right thing.

I've written a stack of my own skills and I have never once done that. I wrote the file, it looked correct, I shipped it. Reading this one is the closest thing to a professional callout I've had from a markdown file.

A second model whose only job is to disagree

agents/code-reviewer.md defines the reviewer, and requesting-code-review says when to hand work over: after each task in subagent-driven development, after a major feature, before a merge to main. The mechanics are unglamorous. Take a base SHA and a head SHA, dispatch the reviewer at that range, read what comes back.

The value isn't that the second model is smarter. It's that the second model never saw the first one's reasoning, so it can't inherit the assumption that broke the code. I get the same effect on my own work by closing the laptop and looking again the next morning, at considerably worse latency.

Where it costs you

Three things bother me. None of them are fatal.

1. It spends context to buy discipline

   Every gate that fires loads a file. The 1% rule is deliberately generous, so on a short task you can pay for two or three skill bodies before writing a line of code. Over a long session that competes with the actual work for room. The session-start hook fixes forgetting; it does nothing about crowding.

2. Rigid skills are rigid on purpose

   The docs split skills into rigid and flexible and say plainly that TDD and debugging are to be followed exactly, with no adapting away the discipline. Correct for a codebase with a test suite. Point it at a throwaway script and it will still want the ceremony, and you will be the one arguing with a markdown file at midnight.

3. Ordering is a rule, not an inference

   Process skills come before implementation skills. "Let's build X" means brainstorming first, always. I think that ordering is right, and it's also the piece most likely to collide with whatever workflow you already have, because it decides where your task begins.

What I took from it

I went in expecting a prompt library and found something closer to a compliance system. The skills themselves are ordinary writing, and I could have written most of the sentences. The engineering is in the threshold, the hook that reinstalls the rules after the summarizer eats them, the excuse table, and the reviewer who never saw the plan.

None of that needs the plugin. Copy the pattern into whatever you run today: pick the two decisions your agent gets wrong when it's being lazy, write a threshold instead of a request, write its excuses down verbatim, add one hook that restores the rules after compaction. That's an afternoon of work and it's most of the benefit.

What I still don't know is whether the ceremony pays for itself on small tasks. My guess is no, and that the right shape is rigid skills on anything touching a test suite and nothing at all on a scratch file. I haven't measured that either.

If you want the post that set this one up, it's I Stopped Writing Prompts and Started Writing Identity Files.