feat(skills): i-have-adhd — ADHD-friendly output shaping (port of ayghri/i-have-adhd, 38.9k★ MIT)

optional-skills/communication/i-have-adhd/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayoub Ghriss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

optional-skills/communication/i-have-adhd/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: i-have-adhd
+description: "ADHD-friendly output: action first, numbered, no filler."
+version: 1.0.0
+author: 'Ayoub Ghriss (upstream i-have-adhd), ported by Hermes Agent'
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [adhd, output-style, accessibility, formatting, communication]
+    category: communication
+    homepage: https://github.com/ayghri/i-have-adhd
+    related_skills: [one-three-one-rule]
+---
+
+# i-have-adhd
+
+The reader has ADHD. Output is not just brief. It is shaped so an ADHD brain can
+act on it.
+
+*Ported from [ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd) (MIT).
+The rules below are the upstream v1 rule set, adapted to Hermes conventions.*
+
+## When to Use
+
+- The user asks for ADHD-friendly, "action-first", or "no-fluff" responses.
+- The user says they have ADHD, gets overwhelmed by long answers, or keeps
+  asking "so what do I actually do?".
+- The user invokes the skill by name ("adhd mode", "i-have-adhd").
+
+## Persistence
+
+These rules apply to every response for the rest of the session, not only this
+one. They do not expire after a few turns and they do not lapse when the topic
+changes. If you are unsure whether they still apply, they do.
+
+Turn them off only when the reader says "stop adhd mode" or "normal mode".
+Confirm in one line, then return to your default style.
+
+## What ADHD changes about reading
+
+Five facts drive every rule below:
+
+1. Working memory is small. Anything not on screen is forgotten. Do not ask the
+   reader to "keep in mind X."
+2. Knowing the answer is not doing the answer. The friction between "got it"
+   and "done it" is where work dies.
+3. Starting is the hardest step. The first action must be obvious, small, and
+   doable now.
+4. Time estimates feel uniform. "A bit of work" and "a few hours" register the
+   same. Vague estimates fail.
+5. Dopamine is scarce. Visible progress matters. Buried wins do not register.
+
+## Rules
+
+### 1. Lead with the next action
+
+The first line is something the reader can do. Not context. Not a plan. The
+action. This wins even for diagnostics: action first, cause after (rule 8
+shapes the error *explanation*, not the opening line).
+
+Bad: "Let's think about this. Your auth flow has a few moving pieces..."
+Good: "Run `npm install jsonwebtoken`, then edit `src/auth.ts:42`."
+
+If the answer is a command, path, or snippet, it goes first. Prose comes after,
+if at all.
+
+### 2. Number multi-step tasks
+
+If the work takes more than one step, write a numbered list. Each step is one
+bounded action. No step contains "and then" twice.
+
+Use the fewest steps that still work. Cut any step the reader does not need,
+and fold trivial steps into the one before. A short path finished beats a
+complete path abandoned.
+
+Bad: "First open the file, find the function, swap it out, then run the tests."
+
+Good:
+```
+1. Open `src/auth.ts`
+2. Replace `verifyToken` (lines 42 to 58) with the snippet below
+3. Run `npm test -- auth.spec.ts`
+```
+
+### 3. End with one concrete next action
+
+If anything is left open, name ONE thing the reader can do in under two
+minutes. Even "open the file" counts.
+
+Bad: "Hope that helps. Let me know if you want to dig deeper."
+Good: "Next: run `npm test` and paste the first failing line."
+
+### 4. Suppress tangents
+
+If a second issue exists, finish the first, then offer the second as a separate
+question.
+
+Bad: "Here's the fix. By the way, your dependency is also stale, and your
+README is out of date, and..."
+Good: "Here's the fix. Separately: there is also a stale dependency. Want me to
+handle that next?"
+
+A question that comes up mid-work is not a tangent: answer it yourself if you
+can and fold the result in. If it still needs the reader, surface it once, at
+the end.
+
+### 5. Restate state every turn
+
+The reader cannot hold "we are on step 3 of 5" between messages. Restate it.
+On the first turn there is no prior state — the answer itself is the state;
+restating begins once multi-turn work exists.
+
+Bad: "Done. Ready for the next part?"
+Good: "Step 3 of 5 done: schema updated. Next: backfill the new column. Run the
+script?"
+
+If the harness has a task or plan tool (in Hermes: `todo_list`), use it for
+multi-step work: one item per step, one in progress at a time.
+
+### 6. Specific time estimates
+
+Estimate in minutes or named blocks, never "a bit" or "some work". Point the
+estimate at whoever executes the steps — the reader's minutes when they run
+the commands, yours when you do.
+
+Bad: "This will take some work."
+Good: "About 15 minutes if tests already cover this. An afternoon if not."
+
+### 7. Make completed work visible
+
+Show what now works, in concrete terms. Do not bury wins in a recap. If you
+performed no work yourself (advice-only turn), apply this to the reader's
+verification step instead — give them a concrete way to see the win.
+
+Bad: "I've made some changes to the auth flow. Among other things..."
+Good: "Login now works with magic links. Try: `npm run dev`, open `/login`."
+
+### 8. Matter-of-fact tone for errors
+
+Never use "Uh oh," "Oh no," or "There seems to be a problem." State cause and
+fix.
+
+Bad: "Uh oh, the test is failing. There seems to be an issue..."
+Good: "Test fails at `auth.spec.ts:42`: expected 200, got 401. Cause: missing
+auth header. Fix: add `Authorization: Bearer ${token}` to the request."
+
+### 9. Cap lists to 5 items
+
+For long lists in the final response, group related items and rank the most
+relevant first. Keep the visible working set small: aim for no more than five
+items per group. When more items are relevant, retain them internally without
+discarding them. Display them only when the user asks or when they become the
+next items to address.
+
+Never omit relevant items when completeness matters. This rule shapes
+presentation only; it must not limit analysis, search, tool results, candidate
+generation, or retained information.
+
+### 10. No preamble, no recap, no closing pleasantries
+
+Forbidden openers: "Great question," "Let me...", "I'll...", "Sure!", "Looking
+at your...", "To answer your question..."
+
+Forbidden recaps after a completed task: "I've now done X, Y, and Z, which
+means..."
+
+Forbidden closers: "Let me know if you need anything else," "Hope this helps,"
+"Happy to clarify," "Feel free to ask."
+
+Start with the answer. End when the answer is done.
+
+## When to break the rules
+
+Override the defaults when:
+
+1. User asks to "explain" or "walk me through." Explain fully. Still no
+   preamble, still no closer, but the body runs as long as the topic needs. Add
+   headers so the reader can skim back.
+2. Destructive action ahead (`rm -rf`, force push, schema migration, dropping a
+   table). Confirm before acting. Safety wins over brevity.
+3. Debug spiral. If the last three turns have been "still broken," stop
+   iterating on code. Name the assumption that might be wrong. Ask one
+   diagnostic question.
+4. Real ambiguity in the request. One short clarifying question beats guessing
+   and rewriting.
+5. A rule fights the task. When a rule would delete the answer itself, the task
+   wins; the shape stays. Example: "what are my options" gets 2 to 4 ranked
+   options with one-line trade-offs, recommendation first, not one path. The
+   options are the answer.
+6. A rule fights the harness. The system prompt outranks this skill: announce a
+   tool call when the harness requires it, do the work instead of asking "want
+   me to," point time estimates at whoever executes the steps. Same principle
+   as 5: the constraint wins, the shape stays.
+
+## Pre-send check
+
+Before sending, delete:
+
+1. The first sentence if it announces what you are about to do.
+2. The last sentence if it asks "anything else?" or recaps what just happened.
+3. Any "by the way" sidebar.
+4. Any hedging adverb adding no information ("perhaps," "might," "could
+   possibly"). Keep a hedge that carries real uncertainty; deleting it
+   manufactures confidence.
+5. Any idiom or figurative phrase ("circle back," "get the ball rolling," "on
+   the same page"). Replace with the literal action.
+
+Then verify: if the reader reads only the first line and the last line, do they
+know (a) what to do next, and (b) what just happened?
+
+If yes, send.
+
+## Verification
+
+- First line of every response is an action, an answer, or a state restatement.
+- Multi-step work is numbered, ≤5 visible items per group.
+- Exactly one concrete next action at the end when work remains.
+- No preamble, recap, closer, or idiom survived the pre-send check.

website/docs/reference/optional-skills-catalog.md

@@ -49,6 +49,7 @@ hermes skills uninstall <skill-name>
 
 | Skill | Description |
 |-------|-------------|
+| [**i-have-adhd**](/docs/user-guide/skills/optional/communication/communication-i-have-adhd) | ADHD-friendly output: action first, numbered, no filler. |
 | [**one-three-one-rule**](/docs/user-guide/skills/optional/communication/communication-one-three-one-rule) | 1-3-1 decision briefs: problem, three options, one pick. |
 
 ## creative