i-have-adhd

What It Does

i-have-adhd is a skill that reshapes a coding agent's output for a reader who has trouble acting on long, buried answers. It is not a "be concise" instruction. It is ten specific rules: lead with the next runnable action, number multi-step work, end with one concrete next step, suppress tangents, restate state every turn, give time estimates in real units, make completed work visible, report errors matter-of-factly, cap lists at five items, and cut all preamble, recaps, and closers. The core artifact is a 140-line SKILL.md prompt contract, but the repo also ships an executable SessionStart hook (Node, sh, PowerShell), a TypeScript extension for the Pi coding agent, and a 371-line Python eval harness with a weighted rubric. It targets developers whose agent writes verbose prose replies and buries the actual command or fix three paragraphs in. The name references ADHD and the rules are adapted from a clinical textbook (The Adult ADHD Tool Kit by Ramsay and Rostain), but the README is explicit that no diagnosis is needed.

The Good

The SKILL.md is the best-written output-shaping prompt GearScope has tested. Every one of the ten rules pairs a concrete Bad example with a concrete Good example using the same scenario, so the model sees the exact transform required. Rule 1 (lead with the next action) shows the same auth-flow fix as both a buried prose paragraph and a one-line command plus a numbered list. The skill also defines six explicit override conditions where the rules bend: when the user asks to "explain" (go long, keep the shape), before destructive actions (safety beats brevity), in a debug spiral after three failed fixes (stop and name the doubtful assumption), on real ambiguity (one short clarifying question), when a rule would delete the answer itself, and when the harness system prompt conflicts. The closing pre-send check lists five things to delete before sending (the announcing first sentence, the "anything else" last sentence, any "by the way" sidebar, empty hedging adverbs, figurative idioms) and a verification question: if the reader reads only the first and last line, do they know what to do next and what just happened. That is a testable contract, not a vibe.

It ships a weighted, release-gated eval harness, which is rare for a single prompt skill. The 371-line scripts/run_evals.py drives a three-condition design (baseline with no skill, candidate with this skill, comparator with a competing skill you supply) across 14 cases in 11 categories. The rubric in evals/rubric.md weights five dimensions: Correctness 35 percent, Autonomy 25 percent, Actionability 20 percent, Safety 10 percent, Concision 10 percent. Judging is blind (conditions labeled A, B, C). The release gate refuses to pass the candidate unless it has no blocking findings, its Correctness and Safety scores are each within 0.1 points of baseline or better, and its weighted score beats baseline. The harness enforces dollar budgets per condition, rejects runners that never report cost (unless you pass --allow-unmetered), and resumes partial runs by skipping completed (case, trial, condition, runner) keys. The test suite (tests/test_run_evals.py) verifies the weighting math, the blocker gate, the duplicate-row rejection, and the unmetered-runner rejection all behave correctly.

The eval harness is methodologically sharp about self-contamination, which most skill evals ignore entirely. The evals/README.md warns explicitly that the operator's own always-on flag (~/.claude/.i-have-adhd-always) would inject the full ruleset into the baseline condition and make the comparison measure the skill against itself. The example runners isolate the call from the operator's agent config (--setting-sources "" for Claude, --ignore-user-config --ephemeral for Codex) and pin --model explicitly, because without a pin the eval silently runs whatever the operator defaults to and per-token cost varies with it. This is the same class of subtle bias that invalidates most "my prompt is better" benchmarks, and it is called out by name in the docs.

The always-on hook is defensively engineered and opt-in by default. The SessionStart hook (hooks/always-on.mjs) only fires when the user has created a flag file (~/.claude/.i-have-adhd-always), so installing the plugin changes nothing by itself. It resolves SKILL.md relative to the script's own location via import.meta.url rather than trusting an environment variable, strips the YAML frontmatter with a regex before injecting (so disable-model-invocation never leaks into the model's context), and wraps everything in a try/catch that exits 0 on any failure so it never blocks session start. There are three runtime implementations (Node, sh, PowerShell) and the test suite (tests/test_always_on_hooks.py) runs all available runtimes as subtests and asserts they produce byte-identical normalized output across edge cases including trailing-whitespace frontmatter and an unclosed frontmatter fence. I verified all three behaviors directly: silent without the flag, injecting with the flag, and frontmatter stripped.

The multi-agent install is genuine and the native Hermes path is verified end to end. INSTALL.md is 665 lines covering 11 named agents (Antigravity, Claude Code, Codex, Gemini CLI, GitHub Copilot, Hermes, Kimi Code, Pi, Qwen Code, Zed, Cursor/OpenCode/Amp) plus the universal npx skills path, each with install, verify, update, and uninstall commands and an optional always-on snippet. The skill is published to skills.sh. I ran the full Hermes cycle on the host: hermes skills install resolved the skill from skills.sh and wrote SKILL.md, agents/gemini.toml, and agents/openai.yaml into ~/.hermes/skills/i-have-adhd/, hermes skills list showed it as enabled, and hermes skills uninstall removed it cleanly. The skill declares disable-model-invocation: true in its frontmatter so it stays off until invoked, and the docs are honest about which harnesses honor that flag (Claude Code, Qwen Code, Codex) versus which may auto-activate.

The case suite covers the failure modes the skill is most likely to break, including a medical boundary. The 14 eval cases include a destructive-action case (delete every untracked file), a real-ambiguity case (deploy it to production), a debug-spiral proxy, a casual-message case (thanks, that solved it) that checks the skill does not manufacture a numbered workflow where none is wanted, and a medical-boundary case (does using this response style prove I have ADHD) that checks the skill refuses to make a diagnostic claim. The casual-message and medical-boundary cases are the ones that catch an overzealous output-style skill turning every reply into a rigid template, and their presence shows the author thought about where the rules backfire.

The Bad

The eval harness exists and validates, but no actual results are committed. There are no responses.jsonl or scores.jsonl files in the repo showing a real baseline-versus-candidate run with measured scores. The rubric, the cases, the release-gate logic, and the weighting are all present and tested, but the headline claim (this skill makes output more actionable without hurting correctness) is asserted by the design of the harness rather than demonstrated by committed data. A reader who wants to know the measured Actionability delta has to run the eval themselves with their own API budget. By contrast, peer skills in the token-compression category commit fixture ratios and benchmark tables. The eval README does instruct the operator to record exact CLI and model versions with published results, so the infrastructure expects results to be published, they just are not in the repo yet.

Zero git tags and zero GitHub releases despite 19,486 stars. The only version number anywhere is 0.1.0 in package.json and .claude-plugin/plugin.json. There is no way to pin the skill to a known version, diff what changed between updates, or audit a specific release. With 1,166 forks and 26 contributors, every install pulls from whatever is on main today. This is the same release-discipline gap that affects most high-star single skills, and it is a real operational risk for anyone who needs reproducible installs.

The skill adds roughly 6.8 KB of context per turn when active, and that tax is never quantified. SKILL.md is 6,813 bytes. In always-on mode the SessionStart hook injects the full ruleset at the start of every session, and in on-demand mode the rules occupy context for the rest of the session once invoked. On terse workloads where the answer is already a single command, the skill's overhead may exceed the prose it saves. The repo does not measure or disclose this the way the better token-compression skills do. The skill is opt-in by default (disable-model-invocation: true), which limits the blast radius, but a user who turns on always-on mode has no number to compare against.

The clinical framing is handled responsibly but remains a legitimate critique. The name and the rule set reference ADHD, a real diagnosed condition, and the rules are adapted from a clinical textbook. The repo addresses this directly: the README says "No ADHD diagnosis needed," the eval suite includes a medical-boundary case that asserts the style cannot diagnose ADHD, and the credits cite the source. Still, packaging a productivity output style under a disability label is the kind of framing some readers will object to on principle regardless of how carefully it is disclaimed. The skill is aware of the tension and works to defuse it, but it does not eliminate it.

The eval-harness logic tests are not gated in CI. The repo has four GitHub workflows. plugin-load-check.yml runs the always-on hook tests (python -m unittest tests.test_always_on_hooks) and actually loads the plugin in a real Claude Code install, and pi-load-check.yml runs the Pi extension smoke test. Both are real gates. But the full pytest suite, which includes tests/test_run_evals.py (the eval weighting, release-gate, and validation logic), is not run in any workflow. So a regression in the scoring math would only be caught by a local run, not by CI.

Smoke Test Results

Host-based testing on macOS 26.5.2 aarch64 (Python 3.12.13, Node 24.13.1, Hermes v0.15.1). No sandbox VM was used; all commands ran directly on the review host against a fresh shallow clone.

Run A - Fresh clone, no deps preinstalled

$ git clone --depth 1 https://github.com/ayghri/i-have-adhd.git
Cloning into '/tmp/adhd-rev-20260811/clone'... OK

$ python3 --version
Python 3.12.13

$ node --version
v24.13.1

$ python3 -m pytest tests/ -q
13 passed, 6 subtests passed in 0.16s

$ python3 scripts/run_evals.py validate
Evaluation cases are valid.

Pass rate: 5 of 5. Everything runs from a fresh clone with zero additional dependencies. The test suite needs only pytest plus the standard library, and the eval harness needs only the standard library. No npm install or pip install required to reach a green test run and a valid eval catalog.

Run B - Clone with deps, full functional verification

$ node hooks/always-on.mjs # no flag file
(exit 0, empty stdout)

$ touch ~/.claude-test-cfg/.i-have-adhd-always
$ CLAUDE_CONFIG_DIR=~/.claude-test-cfg node hooks/always-on.mjs | head -3
ADHD MODE ACTIVE (always-on). The ruleset below applies to every response...

$ CLAUDE_CONFIG_DIR=~/.claude-test-cfg node hooks/always-on.mjs | grep -c "disable-model-invocation"
0 (frontmatter stripped)

$ hermes skills install ayghri/i-have-adhd/skills/i-have-adhd -y
Installed: i-have-adhd
Files: SKILL.md, agents/gemini.toml, agents/openai.yaml

$ hermes skills list | grep adhd
| i-have-adhd | | skills.sh | community | enabled |

$ hermes skills uninstall i-have-adhd (confirmed with "y")
Uninstalled 'i-have-adhd' from i-have-adhd

$ hermes skills list | grep adhd
(clean)

Pass rate: 5 of 5. The opt-in hook is silent without the flag, injects the ruleset with the flag, and strips the frontmatter. The native Hermes install path resolves from skills.sh, writes the skill files, lists as enabled, and uninstalls cleanly with no residue.

Run C - Functional verification (does it do what it claims?)

$ python3 scripts/run_evals.py plan --trials 3 --include-comparator | tail -3
{"case_id": "medical-boundary", "trial": 3, "condition": "baseline"}
{"case_id": "medical-boundary", "trial": 3, "condition": "candidate"}
{"case_id": "medical-boundary", "trial": 3, "condition": "comparator"}

$ python3 -c "import json; cases=json.load(open('evals/cases.jsonl'.replace('.jsonl','.jsonl'))) if False else [json.loads(l) for l in open('evals/cases.jsonl')]; print('cases:', len(cases), 'categories:', len({c['category'] for c in cases}))"
cases: 14 categories: 11

$ grep -c "criteria" evals/cases.jsonl
14 (every case has scoring criteria)

Functional pass rate: 3 of 3 plus the 14-case catalog. The three-condition eval plan generates correctly (baseline, candidate, comparator across all 14 cases and 3 trials), every case carries explicit scoring criteria, and the catalog spans 11 categories including the safety, ambiguity, medical-boundary, and casual-message cases that catch an over-rigid output style. The live LLM judging run requires an API key and budget and was not exercised in real time, but the deterministic harness around it (case validation, plan generation, scoring math, release gate) is fully verified by the test suite.

What the runs tell you

The skill installs, tests green, and validates from a fresh clone with zero extra dependencies. The opt-in always-on hook behaves correctly across all three of its states (silent, injecting, frontmatter-stripped). The native Hermes path is real and reversible end to end. The eval harness is structurally sound and its plan generation is correct. The only layer not exercised is the live model judging run, which needs an API key, and the deterministic infrastructure around it held.

Setup Walkthrough

1. Install for Hermes: hermes skills install ayghri/i-have-adhd/skills/i-have-adhd. The skill lands in ~/.hermes/skills/i-have-adhd/ and is exposed as a slash command at the next session start. Preview without installing first with hermes skills inspect ayghri/i-have-adhd/skills/i-have-adhd.
2. Install for Claude Code: claude plugin marketplace add ayghri/i-have-adhd && claude plugin install i-have-adhd@i-have-adhd, then type /i-have-adhd.
3. Install for any other agent (Cursor, Codex, Copilot, OpenCode): npx skills add ayghri/i-have-adhd -a . The skill is also installable for Codex, Gemini CLI, Qwen Code, Zed, Kimi Code, Pi, and Antigravity with agent-native commands documented in INSTALL.md.
4. Activate in a session by typing /i-have-adhd (or $i-have-adhd in Codex). Rules stay on for the session. Turn them off with "stop adhd mode" or "normal mode".
5. Optional always-on for Claude Code: touch ~/.claude/.i-have-adhd-always. A SessionStart hook loads the full ruleset from message one every session. Delete the file to revert to on-demand. For other agents, paste the always-on snippet (in INSTALL.md) into the agent's persistent rules file.
6. Tune the rules by forking, editing skills/i-have-adhd/SKILL.md, and swapping your copy in. The README documents the exact uninstall-and-reinstall sequence.

Post-install gotcha: in always-on mode the rules add roughly 6.8 KB to context every session. On terse coding Q&A where the answer is already one command, the skill's overhead may exceed the prose it trims. Run an A/B (same task with and without the skill) if you bill per token.

Alternatives

1. caveman (JuliusBrussee/caveman) - the token-compression skill that makes agents talk in terse fragments. Caveman optimizes for fewer output tokens; i-have-adhd optimizes for actionability and readability. They are complements, not substitutes: caveman shortens, i-have-adhd reorders so the action leads. Caveman commits compression fixtures and benchmark numbers; i-have-adhd commits a release-gated eval harness but no results.
2. A hand-written "be brief" instruction in your agent's rules file - free and zero-overhead, but you lose the ten specific rules, the override conditions, the pre-send checklist, the eval harness, and the tested opt-in hook. For a single "answer first" line this is enough; for a real output-shaping contract it is not.
3. The always-on snippets shipped in this repo's INSTALL.md - for any agent that lacks a plugin system, the repo provides a 10-rule markdown block you paste into the agent's persistent rules (GEMINI.md, AGENTS.md, copilot-instructions.md). This is the skill's own rules in a zero-install form, useful when you cannot or will not install a plugin.