i-have-adhd: The Tiny AI Skill That Makes Coding Agents Finally Answer First

Your coding agent is not useless. It is often just badly shaped for the moment you are in.

You ask for the next command. It opens with “Great question.” You ask why a test failed. It gives you a paragraph of emotional cushioning before the failing line. You ask for a fix. The answer is there, but it is hiding under context, caveats, recap, and a polite closer.

That is the small but painful problem i-have-adhd solves. It is a lightweight skill for AI coding agents that says: put the action first, number the steps, make progress visible, and stop talking when the work is done.

The repo has 14 000 stars and 740 forks as of July 2026. That number is the story: this is not only an ADHD accessibility problem. It is a developer-experience problem hiding in plain sight.

---

TL;DR

• What it is: A 10-rule skill that changes how AI coding agents format answers: command first, numbered steps, concrete next action, no social filler.
• Why it went viral: Every developer has lost time scrolling through a polite AI answer to find the one line they actually needed.
• Best fit: Claude Code, Cursor, Codex, Copilot, Gemini CLI, or any agent setup where output shape matters as much as model quality.
• Important nuance: It does not make the model smarter. It makes the answer more executable.
• Try it first on: A failing test, an install error, or a confusing terminal message. That is where the difference is obvious.

---

Beginner Map

If you are new here, read this in three passes:

1. Part 1 (Foundations) — understand the problem the repo solves.
2. Part 2 (Investigation) — see how the ten rules actually work.
3. Part 4 (Resolution) — follow the install steps and try it immediately.

Student First Assignment

Pick any AI coding tool you already use. Ask it a technical question. Count how many lines pass before the actual answer appears. Write that number down. Then install i-have-adhd and repeat the same question. Compare the two outputs side by side. That is the whole experiment, and it takes under 30 minutes.

By the end of the post, you should be able to explain the repo in one sentence:

i-have-adhd treats AI output like a user interface: if the next action is hidden, the interface failed.

---

Part 1: Foundations (Mental Model)

Why AI Output Is Hard to Scan

Modern language models are trained to be helpful and polite. That sounds good until you realize “helpful and polite” in training data often means:

• Open with a friendly acknowledgment
• Repeat the question back to prove you understood it
• Provide context before the answer
• Give the answer
• Summarize what you just said
• Close with “Hope this helps!”

For a written essay, that structure works. For a coding session where you need the next command in three seconds, it is friction.

That is the key mental model: AI output is a UI.

We usually talk about AI tools as if the only thing that matters is model intelligence. Better benchmark score, bigger context window, cheaper tokens, smarter coding ability. Those things matter, but they are not the whole experience.

If the model knows the fix but buries it on line 17, the interface is still poor. If it gives five possible next steps when you only need one, the interface is still noisy. If it says “this may take a little while” instead of “about 15 minutes,” the interface is still vague.

i-have-adhd does not try to change the model’s brain. It changes the shape of the model’s answer.

The five facts that drive every rule in i-have-adhd:

1. Working memory is small. Anything not on screen is forgotten. The agent should not ask you to “keep X in mind.”
2. Knowing the answer ≠ doing the answer. The gap between understanding and executing is where work dies.
3. Starting is the hardest step. The first action must be obvious, small, and doable now.
4. Time feels uniform. “A bit of work” and “a few hours” register identically. Vague estimates fail.
5. Dopamine is scarce. Visible progress matters. Buried wins do not register.

These are not character flaws. They are how attention works under load. The rules in this skill work with that reality instead of against it.

The One-Line Product Thesis

Most prompt packs try to make the assistant sound smarter. i-have-adhd tries to make the assistant easier to act on.

That distinction is why the project is interesting. It does not chase a new personality. It removes friction from the moment between “I understand” and “I did it.”

---

Part 2: The Investigation

How the Repository Is Structured

The core of the repo is a single SKILL.md file at skills/i-have-adhd/SKILL.md. Everything else is delivery infrastructure.

skills/i-have-adhd/SKILL.md   ← the 10 rules
hooks/                         ← always-on SessionStart hook (Claude Code)
.claude-plugin/                ← Claude Code plugin manifest
.codex-plugin/                 ← Codex plugin config
.cursor/skills/i-have-adhd/    ← Cursor skills copy
.agents/plugins/               ← Codex plugin compatibility
INSTALL.md                     ← step-by-step for every major agent
evals/                         ← automated eval harness to test compliance
tests/                         ← test suite for the evals

The skill is designed to be installed via a plugin system, not copy-pasted. That means when the maintainers improve a rule, you get the update through the normal plugin update flow.

What Makes It Professional, Not Just Cute

The repo could have stopped at a Markdown file and still been useful. What makes it feel like a serious tool is the delivery layer around the rules:

1. Multiple agent targets: Claude Code, Codex, Cursor, Gemini CLI, and other agent-skills harnesses are treated as first-class users.
2. Activation is explicit: In Claude Code, the skill is off until you type /i-have-adhd, so it does not silently reshape sessions you did not intend to change.
3. Always-on mode exists: If the rules fit your brain, the ~/.claude/.i-have-adhd-always flag turns it into a default behavior.
4. The rules include escape hatches: Destructive actions, ambiguity, deep explanations, and debug spirals all override the shortest possible answer.
5. There are evals: The repo includes a harness for checking whether agents actually follow the rules, not just whether the README sounds good.

That last detail matters. A communication style guide is easy to write. A style guide that can be evaluated is much harder to fake.

The 10 Rules, Explained Plainly

The full text lives in SKILL.md. Here is a plain-language summary:

Rule 1 — Lead with the next action.
The first line of every response is something you can do. Not context. Not a plan. The action. If the answer is a command, it goes on line one.

Rule 2 — Number multi-step tasks.
If the work needs more than one step, it gets a numbered list. Each item is one bounded action. No step contains “and then” twice.

Rule 3 — End with one concrete next step.
If anything is still open, name exactly one thing you can do in under two minutes. “Run npm test” counts. “Let me know if you need more” does not.

Rule 4 — Suppress tangents.
If a second issue appears, finish the first and then offer the second as a separate question. One thread at a time.

Rule 5 — Restate state every turn.
You cannot hold “we are on step 3 of 5” between messages. The agent restates it. Every turn.

Rule 6 — Specific time estimates.
“About 15 minutes if tests cover this. An afternoon if not.” — not “this might take a while.”

Rule 7 — Make completed work visible.
Show what now works, concretely. Not “I’ve made some changes.” — “Login works with magic links. Try npm run dev, open /login.”

Rule 8 — Matter-of-fact tone for errors.
No “Uh oh” or “There seems to be an issue.” State cause, state fix.

Rule 9 — Cap lists at 5 items.
If a list grows past five, split it into “do now” vs “later.” Five ranked items beats ten unranked.

Rule 10 — No preamble, no recap, no closers.
Forbidden openers: “Great question,” “Let me…”, “Sure!”, “Looking at your…”
Forbidden closers: “Hope this helps,” “Let me know if you need anything else.”

When Rules Break (and Should)

The skill explicitly defines six override cases where the default shape should give way:

1. User asks to “explain” or “walk me through” — explain fully, still no preamble or closer
2. Destructive action ahead — confirm before acting, safety beats brevity
3. Debug spiral after three failed turns — stop iterating code, ask one diagnostic question
4. Real ambiguity — one short clarifying question beats guessing
5. A rule would delete the answer — the task wins, the shape stays
6. Harness system prompt outranks skill — obey the harness

This last point matters. i-have-adhd is designed to work inside Claude Code, Cursor, Codex, and other systems that have their own system prompts. It does not fight them.

The Hidden Design Choice: It Is Not “Be Brief”

The skill is often described as ADHD-friendly, but the important detail is that it is not simply asking the model to be short.

Short can still be useless:

Try checking your environment variables.

Actionable is better:

printenv | grep -E "OPENAI|ANTHROPIC|GITHUB"

Then the agent should say what the result means and what to do next. The goal is not fewer words at any cost. The goal is lower execution friction.

---

Part 3: The Diagnosis

Before and After: Real Comparisons

The README shows the transformation clearly. Here are a few concrete examples:

The 30-Second Demo

Imagine you ask an agent: “Why is my deploy failing?”

The default AI answer often starts like this:

There are a few possible reasons your deployment might be failing.
First, let's look at the logs and make sure your environment is configured...

That is not wrong. It is just slow to act on.

An i-have-adhd-shaped answer should start closer to this:

Run `pnpm run build` locally and paste the first error line.

1. If build fails locally, fix that before redeploying.
2. If build passes locally, check the deploy log for missing env vars.
3. If the log says frozen lockfile, run `pnpm install --no-frozen-lockfile`.

Same topic. Different posture. The second version gives your hands something to do before your attention leaks away.

Error handling — Rule 8:

Before:
"Uh oh, there seems to be an issue with your auth flow.
It looks like something might be wrong..."

After:
"Test fails at auth.spec.ts:42 — expected 200, got 401.
Cause: missing Authorization header.
Fix: add `Authorization: Bearer ${token}` to the request."

Multi-step task — Rule 2:

Before:
"First you'll want to open the file, then find the function,
swap it out with the new version, and then run the tests."

After:
1. Open src/auth.ts
2. Replace verifyToken (lines 42–58) with the snippet below
3. Run npm test -- auth.spec.ts

Progress tracking — Rule 5:

Before:
"Done. Ready for the next part?"

After:
"Step 3 of 5 done: schema updated.
Next: backfill the new column. Run the script?"

Each example is the same information. The shape is completely different. The “After” version is scannable without reading every word.

When i-have-adhd Is Not the Right Tool

It is worth being honest about the limits:

• It does not change the model’s knowledge or capabilities. A bad answer stated action-first is still a bad answer.
• It does not help with tasks where rich context and exploration are the goal — research, architectural brainstorming, open-ended thinking. Those tasks benefit from more expansive prose.
• It does not make long responses short. It makes responses scannable. Those are different things.
• In Claude Code specifically, the skill is off by default. You have to invoke /i-have-adhd each session unless you set up the always-on hook.

The cleanest way to use it is not “always force every answer to be tiny.” The cleanest way is: use it when you are trying to execute, debug, install, ship, or recover from an error. Turn it off when you want long-form exploration.

---

Part 4: The Resolution

Installing on Claude Code (2 minutes)

claude plugin marketplace add ayghri/i-have-adhd
claude plugin install i-have-adhd@i-have-adhd

Restart Claude Code. Then type /i-have-adhd to activate for the current session.

To make it always-on (every session, no /i-have-adhd needed):

touch ~/.claude/.i-have-adhd-always

The SessionStart hook reads this flag and loads the full ruleset from message one.

Which Install Path Should You Choose?

If you use	Start here	Why
Claude Code	Plugin marketplace + /i-have-adhd	Best supported path and easiest to toggle
Claude Code every day	Add ~/.claude/.i-have-adhd-always	Makes the rules automatic across sessions
Cursor	npx skills add ayghri/i-have-adhd	Uses Cursor’s skills folder convention
Copilot in VS Code	Put the rules in Copilot instructions	Copilot does not consume Claude plugins directly
Your own fork	Edit SKILL.md and install the fork	Best when you want different wording or limits

Installing on Cursor

npx skills add ayghri/i-have-adhd

Restart Cursor. The skill is indexed at session start.

Installing on Codex

codex plugin install ayghri/i-have-adhd

Or follow the detailed steps in the INSTALL.md.

Installing on Gemini CLI

Add the always-on snippet from INSTALL.md to your Gemini system prompt, or use the extension install path:

gemini extension install ayghri/i-have-adhd

Installing on GitHub Copilot (VS Code / Copilot CLI)

Copy the contents of skills/i-have-adhd/SKILL.md and paste them into your Copilot instructions file (.github/copilot-instructions.md in your repo, or the user-level instructions file in VS Code settings). The rules activate immediately on the next conversation.

Customizing the Rules

If any rule does not fit your workflow, fork the repo, edit skills/i-have-adhd/SKILL.md, and install your fork:

claude plugin uninstall i-have-adhd
claude plugin marketplace remove i-have-adhd
claude plugin marketplace add <your-username>/i-have-adhd
claude plugin install i-have-adhd@i-have-adhd

The rules are plain English. You do not need to understand any code to change them.

A Good First Prompt After Installing

Do not test it with a vague philosophical question. Test it on a real friction point.

/i-have-adhd
My build is failing. Tell me the first command to run, then give me at most 3 next steps.

You should immediately see the value: fewer warm-up sentences, clearer sequencing, and one next action instead of a fog of possible actions.

---

Final Take

i-have-adhd is one of those tools that looks almost too simple when you read the source. Ten rules in a Markdown file. No build step. No dependency maze.

And yet 14 000 developers starred it. That is not an accident.

The insight behind the project is not new: good technical communication leads with the answer, numbers its steps, names the state, and stops talking when it is done. What is new is that the repo makes this behavior installable — one command, one activation, every agent.

The ADHD framing is honest and precise. It describes what the rules optimize for: working memory constraints, the friction between understanding and acting, the cost of vague time estimates. Those constraints apply to most people during focused work, not just people with a diagnosis.

The viral lesson is bigger than this repo: model quality is not enough. The answer also needs the right shape. In developer tools, shape is not decoration. Shape is whether the user can move.

If you have ever scrolled past three paragraphs looking for the command, this is worth trying today.

Install: github.com/ayghri/i-have-adhd