Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
{
"name": "adhd",
"description": "Tweet-sized, ADHD-friendly output style for Claude Code: turns verbose answers into short ones — action first, numbered steps, no filler.",
"license": "MIT",
"source": "./",
"category": "productivity"
}
Expand Down
4 changes: 4 additions & 0 deletions .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
{
"name": "adhd",
"description": "Turns verbose answers into tweet-sized ones. ADHD-friendly output style: short, concise answers — action first, numbered steps, one topic per answer, state restated every turn, no filler.",
"author": {
"name": "A dME Inc."
},
"license": "MIT",
"repository": "https://github.com/jjdmev2/adhd",
"homepage": "https://github.com/jjdmev2/adhd"
}
3 changes: 1 addition & 2 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
MIT License

Copyright (c) 2026 Kisu (tweet-me)
Portions copyright (c) 2026 Ayoub Ghriss (i-have-adhd)
Copyright (c) 2026 A dME Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
91 changes: 78 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,11 @@ So I wrote one skill and shared it across every workflow I run. Now every answer

### Before / after

Real outputs. Same prompt — *"My Node app crashes on startup with 'Error: Missing API_KEY'. What's going on?"* — same model, skill off vs on:
Two examples, directly on this page. Same task, skill off vs on.

#### Coding — missing `API_KEY`

Prompt: *"My Node app crashes on startup with 'Error: Missing API_KEY'. What's going on?"*

<table>
<tr>
Expand All @@ -39,15 +43,46 @@ Real outputs. Same prompt — *"My Node app crashes on startup with 'Error: Miss
</td>
<td width="50%">

**After — 292 chars, ~12s read**
**After — action first, ~12s read**

> `API_KEY` env var isn't set. Fix:
>
> 1. Find where it's read: `grep -rn API_KEY --include=*.js .`
> 2. Add it to `.env` (or your shell env): `API_KEY=your_key_here`
> 3. If using `.env`, confirm `dotenv` (or similar) is loaded before that check runs
>
> Want me to grep your repo for where it's read?
> 1/1 done: startup has the key it needs. Next: restart the app.

</td>
</tr>
</table>

#### Research / report — decide what to do next

Prompt: *"10 customer interviews: SSO came up in 3/10, all enterprise. Onboarding and reporting came up in 7/10. Should we build SSO now?"*

<table>
<tr>
<td width="50%">

**Before — the report dump**

> The interviews reveal a number of themes around security, onboarding, procurement, pricing, integrations, and reporting. SSO came up repeatedly, although its importance varied by customer segment. A more comprehensive analysis follows…

</td>
<td width="50%">

**After — evidence → decision → action**

> **Decision:** do not build SSO this sprint.
>
> **Evidence:** 3/10 asked for it; all three are enterprise prospects. Onboarding and reporting appeared in 7/10.
>
> 1. Keep SSO as an enterprise requirement, not the next build.
> 2. Ship onboarding friction fixes first.
> 3. Recheck after five more enterprise interviews.
>
> **State:** decision made; next research checkpoint: 5 interviews.

</td>
</tr>
Expand All @@ -61,7 +96,7 @@ Any agent (Claude Code, Cursor, Codex, Cline, Windsurf, ~50 more):
npx skills add jjdmev2/adhd
```

Or as a Claude Code plugin — adds the `/adhd` command and an on/off switch:
Or as a Claude Code plugin — its forced output style applies this format to every main response while enabled. You can also invoke the skill manually with `/adhd:adhd`:

```bash
git clone https://github.com/jjdmev2/adhd ./adhd
Expand All @@ -71,7 +106,13 @@ claude plugin install adhd@adhd

Pick one path, not both. Claude.ai web: **Settings → Capabilities → Skills** → upload [`skills/adhd/SKILL.md`](./skills/adhd/SKILL.md).

Wary of prompt plugins? This one is a single markdown file — read [SKILL.md](./skills/adhd/SKILL.md) before installing. No code, no dependencies.
For Codex, install with `npx skills add` above, then add this to your global `~/.codex/AGENTS.md` so it is the default for every task:

```md
Always invoke and apply $adhd to every user-facing response unless the prompt starts with "ADHD off for this answer:". Preserve correctness, safety, and requested depth over brevity.
```

Wary of prompt plugins? The [core skill](./skills/adhd/SKILL.md) and [Claude Code output style](./output-styles/adhd.md) are plain Markdown. No code, no dependencies.

### The rules

Expand All @@ -95,9 +136,10 @@ Concise mode shortens the answer. adhd rebuilds it for a brain that reads timeli

### Off / update / tune

- Off: `claude plugin disable adhd`
- One answer only: `ADHD off for this answer: explain the full trade-offs`
- Persistent Claude Code off: `claude plugin disable adhd`
- Update: `cd ./adhd && git pull`
- Tune: edit [SKILL.md](./skills/adhd/SKILL.md), re-run `/adhd`
- Tune: edit [SKILL.md](./skills/adhd/SKILL.md), then invoke `/adhd:adhd`

Turn it off for: deep-dive learning, postmortems, anything where you want every caveat.
Test: if you'd *read* the five paragraphs, disable it. If you'd skim them, keep it on.
Expand All @@ -120,7 +162,23 @@ Así que escribí un solo skill y lo compartí en todos mis workflows. Ahora cad

### Antes / después

Salida real (tabla arriba): misma pregunta, mismo modelo — 1.379 caracteres sin el skill, 292 con él.
Dos ejemplos, visibles aquí mismo. Misma tarea, skill apagado vs. encendido.

#### Código — falta `API_KEY`

Pregunta: *"Mi app de Node falla al iniciar con 'Error: Missing API_KEY'. ¿Qué pasa?"*

| Sin el skill | Con el skill |
|---|---|
| **Antes — 1.379 caracteres, ~60 s**<br><br>Explica que la variable no está definida, enumera causas posibles y sigue con varios párrafos. | **Después — acción primero, ~12 s**<br><br>`API_KEY` no está definida. 1. Encuentra dónde se lee. 2. Agrégala a `.env`. 3. Carga `dotenv` antes de validarla.<br><br>**Estado:** 1/1 listo; reinicia la app. |

#### Investigación / reporte — decidir qué sigue

Pregunta: *"10 entrevistas: SSO apareció en 3/10, todos enterprise. Onboarding y reportes aparecieron en 7/10. ¿Construimos SSO ahora?"*

| Sin el skill | Con el skill |
|---|---|
| **Antes — el reporte largo**<br><br>Resume seguridad, onboarding, compras, precios, integraciones y reportes. SSO aparece varias veces, con importancia distinta según el segmento. | **Después — evidencia → decisión → acción**<br><br>**Decisión:** no construir SSO este sprint.<br><br>**Evidencia:** 3/10 lo pidieron; los tres son prospectos enterprise. Onboarding y reportes aparecieron en 7/10.<br><br>1. Dejar SSO como requisito enterprise. 2. Arreglar onboarding primero. 3. Revisar tras cinco entrevistas enterprise más.<br><br>**Estado:** decisión tomada; próximo corte: 5 entrevistas. |

### Instalar — 30 segundos

Expand All @@ -130,7 +188,7 @@ Cualquier agente (Claude Code, Cursor, Codex, Cline, Windsurf, ~50 más):
npx skills add jjdmev2/adhd
```

O como plugin de Claude Code — agrega el comando `/adhd` y un interruptor de encendido/apagado:
O como plugin de Claude Code — su estilo de salida forzado aplica este formato a cada respuesta principal mientras esté activo. También puedes invocarlo a mano con `/adhd:adhd`:

```bash
git clone https://github.com/jjdmev2/adhd ./adhd
Expand All @@ -140,7 +198,13 @@ claude plugin install adhd@adhd

Elige un camino, no ambos. Claude.ai web: **Settings → Capabilities → Skills** → sube [`skills/adhd/SKILL.md`](./skills/adhd/SKILL.md).

¿Desconfías de los plugins de prompts? Este es un solo archivo markdown — lee [SKILL.md](./skills/adhd/SKILL.md) antes de instalar. Sin código, sin dependencias.
Para Codex, instala con `npx skills add` arriba y agrega esto a tu `~/.codex/AGENTS.md` global para que sea el formato por defecto en cada tarea:

```md
Always invoke and apply $adhd to every user-facing response unless the prompt starts with "ADHD off for this answer:". Preserve correctness, safety, and requested depth over brevity.
```

¿Desconfías de los plugins de prompts? El [skill principal](./skills/adhd/SKILL.md) y el [estilo de salida de Claude Code](./output-styles/adhd.md) son Markdown plano. Sin código, sin dependencias.

### Las reglas

Expand All @@ -158,9 +222,10 @@ Cinco más en [SKILL.md](./skills/adhd/SKILL.md) (en inglés — el skill le hab

### Apagar / actualizar / ajustar

- Apagar: `claude plugin disable adhd`
- Solo una respuesta: `ADHD off for this answer: explica todos los trade-offs`
- Apagar Claude Code de forma persistente: `claude plugin disable adhd`
- Actualizar: `cd ./adhd && git pull`
- Ajustar: edita [SKILL.md](./skills/adhd/SKILL.md), vuelve a correr `/adhd`
- Ajustar: edita [SKILL.md](./skills/adhd/SKILL.md), vuelve a correr `/adhd:adhd`

Apágalo para: aprendizaje a fondo, postmortems, cualquier cosa donde quieras cada detalle.
Prueba: si *leerías* los cinco párrafos, apágalo. Si los saltearías, déjalo encendido.
Expand All @@ -169,4 +234,4 @@ Prueba: si *leerías* los cinco párrafos, apágalo. Si los saltearías, déjalo

---

Inspired by [i-have-adhd](https://github.com/ayghri/i-have-adhd) by Ayoub Ghriss · MIT
A dME Inc. · [MIT](./LICENSE)
34 changes: 34 additions & 0 deletions output-styles/adhd.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
name: ADHD
description: ADHD-friendly answers that are concise, action-first, and easy to scan
keep-coding-instructions: true
force-for-plugin: true
---

Use this response style for every main-conversation answer. Apply it alongside task-specific instructions; change how the answer lands, not the quality of the work.

## One-answer opt-out

If the user's prompt starts with `ADHD off for this answer:`, suspend the compression rules for that answer only. Re-enable them automatically on the next user message. Never suspend correctness or safety.

## Default response contract

1. Tweet first. Fit the whole answer in roughly 280 characters when the task allows it.
2. Put the action, decision, result, or exact cause first. In research and reports, separate evidence from inference, name unknowns, and never invent missing facts, sources, or measurements.
3. Number multi-step work. Keep one bounded action per step and no more than five items in one list.
4. Keep one topic per answer. Offer at most one useful follow-up thread instead of dumping side issues.
5. Restate meaningful progress across turns, using concrete state such as `3/5 done; next: backfill`.
6. Use real time ranges instead of vague effort words.
7. Make wins observable: say what works and how the user can verify it.
8. Report errors as cause + fix; add blast radius for production incidents. Use zero drama.
9. Cut filler, empty hedges, preambles, recaps, generic closers, and meta-commentary about the prompt or style.
10. Go longer rather than becoming vague, cryptic, unsafe, or incomplete.

## Go long when needed

1. Confirm before destructive or consequential actions.
2. Explain fully when the user asks for an explanation or walkthrough; keep it skimmable with short headers.
3. On the third `still broken`, stop patching, name the questionable assumption, and ask one diagnostic question.
4. Ask one short clarifying question when guessing would likely waste a round trip.

Correctness, safety, required caveats, and explicitly requested depth always override brevity.
7 changes: 5 additions & 2 deletions skills/adhd/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
name: adhd
description: Shape output for a reader with ADHD — answers read like a tweet on X, short and straightforward, every character counts. Use this skill when responding to ANY user message, including coding tasks, debugging, explanations, planning, and casual conversation. Lead with the action, number the steps, keep one topic per answer, restate state across turns, give real time estimates, and make wins visible. Trigger even on casual messages and even when the user did not ask for brevity.
description: Always use for every message, even if unasked — coding, debugging, research, reports, planning, explanations, and chat. Shape output for an ADHD reader — concise, action-first, numbered when multi-step, one topic, visible state, real time estimates, and no filler. Apply alongside task-specific skills. Correctness, safety, and requested depth override brevity.
---

<!--
Tuning this file? Two parts are load-bearing:
1. The frontmatter description's "ANY user message" phrasing — remove it and the skill stops firing always-on.
1. The frontmatter description's first sentence — hosts may truncate descriptions, so keep the always-use trigger first.
2. The THREAD mode safety exceptions — remove them and the skill will compress away confirmations before destructive actions.
Repo: https://github.com/jjdmev2/adhd
-->
Expand Down Expand Up @@ -111,6 +111,8 @@ Start at the answer. Stop when it's answered.

Four cases break the 280 habit. In THREAD mode the length changes; the filler rules do not — still no intro, no outro, no recap.

If the prompt starts with `ADHD off for this answer:`, suspend the compression rules for that answer only. Re-enable them automatically on the next user message. The opt-out never disables correctness or safety.

1. Destructive action ahead (`rm -rf`, force push, dropping a table, schema migration)? Confirm first. Safety beats brevity.
2. The user said "explain" or "walk me through"? Explain fully, add headers so it skims. Do not second-guess.
3. Third turn of "still broken"? Stop patching. Name the assumption that might be wrong. Ask one diagnostic question.
Expand All @@ -124,6 +126,7 @@ The failure mode of this skill is over-application. Watch for:
2. Terse to cryptic. An answer that forces a "wait, what?" follow-up costs the exact round trip this skill exists to prevent.
3. Thread abuse. One answer split across five 🧵 prompts is worse than one thread.
4. State as filler. "3/5 done" earns its characters only when the numbers change.
5. Confident compression. In research and reports, separate evidence from inference, name unknowns, and never invent missing facts, sources, or measurements.

This style trades length for speed. Never trade away safety or correctness.

Expand Down
35 changes: 35 additions & 0 deletions tests/manifest.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ const plugin = JSON.parse(read('.claude-plugin/plugin.json'))
const marketplace = JSON.parse(read('.claude-plugin/marketplace.json'))
const readme = read('README.md')
const skill = read('skills/adhd/SKILL.md')
const outputStyle = read('output-styles/adhd.md')
const license = read('LICENSE')

test('manifest names agree', () => {
assert.equal(plugin.name, marketplace.name)
Expand All @@ -22,6 +24,25 @@ test('README install commands match the manifests, in both languages', () => {
assert.ok(npx >= 2, `expected npx install line in EN and ES sections, found ${npx}`)
})

test('MIT license metadata and file agree', () => {
assert.equal(plugin.license, 'MIT')
assert.equal(plugin.author.name, 'A dME Inc.')
assert.equal(marketplace.plugins[0].license, 'MIT')
assert.match(license, /^MIT License\n\nCopyright \(c\) 2026 A dME Inc\.\n\nPermission is hereby granted,/)
assert.doesNotMatch(license, /Ayoub|i-have-adhd|tweet-me/i)
})

test('README shows both examples and only the dME MIT footer', () => {
assert.match(readme, /^#### Coding — missing `API_KEY`$/m)
assert.match(readme, /^#### Research \/ report — decide what to do next$/m)
assert.match(readme, /^#### Código — falta `API_KEY`$/m)
assert.match(readme, /^#### Investigación \/ reporte — decidir qué sigue$/m)
assert.match(readme, /Always invoke and apply \$adhd/)
assert.match(readme, /ADHD off for this answer:/)
assert.match(readme, /A dME Inc\. · \[MIT\]\(\.\/LICENSE\)\n$/)
assert.doesNotMatch(readme, /Ayoub|i-have-adhd|Inspired by/i)
})

test('SKILL.md frontmatter stays parseable and within limits', () => {
const m = skill.match(/^---\n([\s\S]*?)\n---\n/)
assert.ok(m, 'frontmatter block missing')
Expand All @@ -32,6 +53,20 @@ test('SKILL.md frontmatter stays parseable and within limits', () => {
// a bare ": " inside an unquoted YAML scalar breaks parsing and silently disables the skill
assert.ok(!desc[1].includes(': '), 'description contains an unquoted ": "')
assert.ok(desc[1].length <= 1024, `description is ${desc[1].length} chars (limit 1024)`)
assert.ok(desc[1].startsWith('Always use for every message, even if unasked'), 'always-on trigger must be first')
assert.match(desc[1].slice(0, 104), /coding.*debugging.*research/, 'key triggers must survive catalog truncation')
assert.match(skill, /ADHD off for this answer:/)
})

test('Claude output style is forced, coding-safe, and supports one-answer opt-out', () => {
const m = outputStyle.match(/^---\n([\s\S]*?)\n---\n/)
assert.ok(m, 'output style frontmatter block missing')
assert.match(m[1], /^keep-coding-instructions:\s*true$/m)
assert.match(m[1], /^force-for-plugin:\s*true$/m)
assert.match(outputStyle, /ADHD off for this answer:/)
assert.match(outputStyle, /Re-enable them automatically on the next user message/)
assert.match(outputStyle, /never invent missing facts, sources, or measurements/)
assert.match(outputStyle, /Correctness, safety, required caveats, and explicitly requested depth always override brevity/)
})

test('SKILL.md "Good:" examples practice rule 1 (≤280 chars)', () => {
Expand Down
Loading