Read this part first, because the name is ambiguous
There are two popular Claude Code skills with ADHD in the name, and neither of them is the other. If you install the wrong one you will get something genuinely good that does a completely different job, and you will think the guide was wrong.
- A skill named adhd that does parallel divergent ideation. It splits a question into five isolated agent branches under different framings, scores them, prunes, and deepens the best three. It is for thinking wider, not for verifying work. Around 4,000 stars, MIT.
- A skill named i-have-adhd that fixes output formatting, so the agent stops burying the answer under preamble. Very widely starred. Also not a verifier.
- And a third skill, not named ADHD at all, that is the one implementing the mechanism this guide describes: a written ledger, a check command that has to run, and a hook that refuses the word "done" until the check passes.
So treat "the ADHD skill" as a description of a behaviour, not as a package name. What follows is the behaviour, how to recognise a skill that actually implements it, and how to build it yourself in about twenty minutes if you would rather not install anything.
The problem this solves, stated precisely
A coding agent is optimised to produce a response you accept. That is not the same as producing work that is correct, and when the two come apart the agent does not know it. It writes the code, it does not run it, and it tells you the task is complete because completing the task and reporting the task complete feel identical from the inside.
Anthropic evaluates for this directly. Its published system card work on Claude 4.5 includes reward hacking as a measured behaviour category on coding tasks, which is the formal name for an agent taking the shortcut that scores well rather than the path that works. This is a known, documented property of the tooling, not a rumour and not a defect in your prompt.
The failure is quiet, which is the expensive part. You do not find out at the moment it happens. You find out three commits later when something that was reported working never was.
The mechanism, in four parts
- A ledger. A plain file in the repo listing every task the agent has accepted. One row per task, and a row is not free text. It has a check and an expected result.
- A check that is a command. Not a description of a check, an actual shell command that exits zero or non zero. "Run the test suite and see 14 passing" is a check. "Verify the endpoint works" is not.
- A gate that runs it. A small script the agent must call, which executes each check and compares real output against the expected result. It reports pass or fail per row and it does not take the agent's word for anything.
- A refusal. A stop hook that reads the ledger before the agent is allowed to finish, and blocks the completion if any row is unproved. This is the part that matters. Without it the first three are documentation the agent can ignore.
Read that list again and notice what is doing the work. It is not the ledger. It is the refusal. Any agent will happily write and maintain a beautiful ledger of tasks it has not done.
Building it yourself, which is the version you can trust
This takes about twenty minutes and it has the advantage that you can read every line. Four files.
- Create GATES.md at the repo root. Give it a table with four columns: id, task, check, expect. One row per unit of work. Keep the check column executable and the expect column literal, for example "npm test -- --run" and "0 failing".
- Write scripts/gate-check.mjs. For each row it shells out to the check, captures stdout and the exit code, and asserts the expect string appears. It prints a per row PASS or FAIL and exits non zero if any row failed. Under sixty lines.
- Add a CLAUDE.md instruction. Two sentences, and be blunt: every task you accept gets a row in GATES.md before you write code, and you may not report a task complete until node scripts/gate-check.mjs passes for that row.
- Register a Stop hook in .claude/settings.json that runs the gate script. A non zero exit blocks the stop, which is what turns your instruction into a rule rather than a suggestion.
Test it deliberately. Give the agent a task, then edit the ledger's expect column to something that cannot be true, and try to end the session. If it stops cleanly, your hook is not wired up. It should refuse.
Why it is slow out of the box, and the tweak that fixes it
The obvious way to run a ledger is one row at a time. Check row one, wait, check row two, wait. On a repo with a real test suite that is minutes per row, and a twenty row ledger becomes an afternoon. This is the "it takes hours" complaint, and it is a scheduling problem, not a capability problem.
The fix is to change one instruction. Tell the orchestrator to dispatch the unproved rows as parallel sub agents, one row per agent, up to ten at a time, each returning only its row id and a pass or fail. The rows are independent by construction, because a check is a command with an expected output and it does not care what the other checks are doing.
- Cap it. Ten is a sensible ceiling. Past that you are competing for the same CPU and the same rate limit, and the wall clock stops improving.
- Keep the sub agents thin. One row, one command, one verdict. A sub agent that is allowed to fix what it finds will edit the same files as its neighbours, and that is the one way these runs collide.
- Never let a sub agent write its own row's result. It reports, the orchestrator records. Otherwise you have handed the marking back to the student.
Done properly this turns a sequential afternoon into a few minutes, and the ledger is the reason it is safe to parallelise at all.
Free, for your email
Get the full setup steps + the copy-paste setup prompt
The rest of this guide (3 more sections) opens right here. The setup prompt, one paste into Claude that sets it all up, comes by email only. Use your real address.
Unlocks: How to tell it is working · Honest limits · The first twenty minutes
50,000+ follow where these guides come from. No spam, reply “unsubscribe” any time.