diff --git a/optional-skills/communication/i-have-adhd/LICENSE.txt b/optional-skills/communication/i-have-adhd/LICENSE.txt new file mode 100644 index 0000000000000..19db5f1b0ca65 --- /dev/null +++ b/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. diff --git a/optional-skills/communication/i-have-adhd/SKILL.md b/optional-skills/communication/i-have-adhd/SKILL.md new file mode 100644 index 0000000000000..1177b1a85e294 --- /dev/null +++ b/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. diff --git a/website/docs/reference/optional-skills-catalog.md b/website/docs/reference/optional-skills-catalog.md index cb7034f20396d..60e782e347fa2 100644 --- a/website/docs/reference/optional-skills-catalog.md +++ b/website/docs/reference/optional-skills-catalog.md @@ -49,6 +49,7 @@ hermes skills uninstall | 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 diff --git a/website/docs/user-guide/skills/optional/communication/communication-i-have-adhd.md b/website/docs/user-guide/skills/optional/communication/communication-i-have-adhd.md new file mode 100644 index 0000000000000..e16ef0bf82520 --- /dev/null +++ b/website/docs/user-guide/skills/optional/communication/communication-i-have-adhd.md @@ -0,0 +1,235 @@ +--- +title: "I Have Adhd — ADHD-friendly output: action first, numbered, no filler" +sidebar_label: "I Have Adhd" +description: "ADHD-friendly output: action first, numbered, no filler" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# I Have Adhd + +ADHD-friendly output: action first, numbered, no filler. + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/communication/i-have-adhd` | +| Path | `optional-skills/communication/i-have-adhd` | +| Version | `1.0.0` | +| Author | Ayoub Ghriss (upstream i-have-adhd), ported by Hermes Agent | +| License | MIT | +| Platforms | linux, macos, windows | +| Tags | `adhd`, `output-style`, `accessibility`, `formatting`, `communication` | +| Related skills | [`one-three-one-rule`](/docs/user-guide/skills/optional/communication/communication-one-three-one-rule) | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# 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. diff --git a/website/sidebars.ts b/website/sidebars.ts index 35b8659473794..a80d1a039dc2f 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -344,6 +344,7 @@ const sidebars: SidebarsConfig = { key: 'skills-optional-communication', collapsed: true, items: [ + 'user-guide/skills/optional/communication/communication-i-have-adhd', 'user-guide/skills/optional/communication/communication-one-three-one-rule', ], },