adhd-md
Transform Markdown into an ADHD-friendly format: lead with conclusions, break up paragraphs, shorten sentences, use clear actions, and eliminate noise.
Golden Rule: Only rearrange information, never delete it. If the content is too long, fold it or move it to an appendix—do NOT delete it. Violating this rule means failure no matter how well other tasks are done.
When to Use
Use this when the user provides a Markdown file (or a snippet of Markdown) and wants it to be more readable, skimmable, and suitable for people with easily distracted attention.
Unsuitable scenarios:
- Input is not Markdown (convert first, or reject directly)
- The user requests content review (fact-checking, logic proofreading) — this is not the purpose of this skill
- The user requests translation or expansion — neither is within scope
Two Parameters
scope: What to Modify
| Value | Boundaries | User Phrases |
|---|
| The word sequence of the body text remains exactly the same; only modify markers, whitespace, and block order | "只改格式" / "只调样式" / "别动我的字" / "排版优化" |
| Only modify wording and information organization; do not change layout style | "只改内容" / "句子太长" / "帮我改写" |
| (default) | Modify both | "优化一下" / "改成 ADHD 友好" |
Judgment Criterion: Moving existing blocks counts as format modification; writing new sentences counts as content modification.
Moving an entire conclusion block to the beginning = format. Writing a new TL;DR section = content.
level: How Extensive the Modifications Are
| Value | Applicable Scenarios | Actions Taken |
|---|
| Specifications, contracts, API docs where changes are risky | Only perform zero-risk adjustments; do not reorder content |
| (default) | READMEs, tutorials, design docs | Split paragraphs, convert to lists, revise headings, write TL;DR, reorder blocks |
| Meeting minutes, long articles, accumulated notes | Full skeleton restructuring, progressive disclosure, generate checklists |
If the user doesn't specify, use
+
, and state this clearly at the start of the report so the user can revise the choice.
Workflow
Step 0 · Decide Where to Write
bash
git -C <repo-containing-document> status --porcelain <file>
- Clean repo → Modify in-place, user reviews with
- Uncommitted changes, or not in git → Write to and explain why to the user
Never overwrite files with uncommitted changes in-place.
Step 1 · Audit
bash
python3 <skill>/scripts/adhd_md.py audit file.md --level 2
Obtain the script score, itemized findings (with
), and a list of rules requiring your judgment.
Read the output before making changes. Don't modify based on memory — the script has already calculated all quantifiable items.
Step 2 · Fix Formatting Automatically
bash
python3 <skill>/scripts/adhd_md.py fmt --write file.md
Zero-risk, judgment-free fixes: trailing whitespace, ordered list numbering, blank lines between blocks, spacing between Chinese and English text, Chinese punctuation.
Optional flags:
(generate table of contents from existing headings),
(merge soft line breaks in Chinese text),
(remove emojis, note this changes characters).
Step 3 · Manual Modifications
Read
, filter the applicable rule subset based on scope, and modify item by item.
Order: Content first, then format. Only after wording is finalized can layout decisions be stable.
Must read before modifying:
- — complete rule list, including thresholds
references/antipatterns.md
- — read if the document is in Chinese
- — read only when and skeleton restructuring is needed
Step 4 · Verification
bash
python3 <skill>/scripts/adhd_md.py verify original.md new.md --scope=format
python3 <skill>/scripts/adhd_md.py report original.md new.md --scope=<scope>
When
, verification is a
hard gate: the token sequence must be identical. If it fails, roll back changes — do not proceed.
When
or
, verification checks invariants: code blocks, inline code, URLs, identifiers, numbers. Fix any hard failures until verification passes.
When modifying in-place, save a copy of the original file to a temporary location first, otherwise verification is impossible:
bash
cp file.md /tmp/adhd-orig.md # before modification
Step 5 · Report
Must include four items:
- The scope and level used
- Script score before → after, with delta for each dimension
- Verification result (Pass/Fail and reason)
- What you modified, and what you intentionally did not modify
The anti-pattern (Group X) score must be 0 after modification. If not, it means you traded over-formatting for score — roll back and start over.
The number of AI-style (Group M) hits must decrease, not increase. When rewriting content, it's easy to accidentally write phrases like "not A but B" or "it is worth noting that", replacing one problem with another. Compare the human-centric dimension from the
result after modification.
Do / Don't for Three Scopes
scope=format
Allowed: Split paragraphs at existing sentence boundaries · Convert parallel sentences to lists (reuse original words) · Bold existing key terms · Add blank lines/dividers · Add language labels to code blocks · Fix heading hierarchy · Reduce list nesting · Fold content with
(reuse existing heading text for summary) · Generate TOC from existing headings · Reorder blocks · Standardize spacing between Chinese/English and punctuation
Not Allowed: Modify any words · Write new TL;DR · Rewrite heading wording · Add time estimates · Add next steps · Delete filler words
Trap in block reordering: After moving a conclusion block to the beginning, check if the moved block contains dangling references like "this solution", "the above configuration", or "it". Fixing references requires modifying words, which falls under content — so when dangling references are detected with
,
abandon the move and note in the report: "Content permission required to safely frontload this section".
scope=content
Allowed: Split long sentences · Convert passive voice to active · Rewrite to lead with conclusions · Write new TL;DR · Revise headings to be conclusion-based · Add time estimates and next steps · Explain terms on first occurrence · Delete filler words and empty phrases · Split parenthetical insertions · Eliminate phrases like "as mentioned above" · Remove AI-style phrasing (contradictory tone, predictive colons, pretentious language, jargon, nominalization)
Not Allowed: Change layout style (do not add new heading levels, modify list types, or adjust folding structures) · Do not delete constraints, units, version numbers, or exceptions in the name of "streamlining"
scope=both
Process content first, then format, and perform unified verification at the end. This is the default setting.
What to Do Without Shell Access
If Bash / command execution is unavailable:
- Skip audit / fmt / verify, manually review according to
- Use the self-check checklist at the end of
references/antipatterns.md
- Clearly state "No machine verification performed" in the report — never pretend to have run the scripts
Pretending to have run verification is worse than not doing it at all.
Output Contract
Follow this format for the report provided to the user:
markdown
## Done: <filename>
**scope** `both` · **level** `standard` · Modified in-place (git repo clean)
Script score: 62.4 → 88.1 (+25.7)
|---|---|---|
| First-screen conclusion effectiveness | 40 | 100 |
| …… | | |
**verify(both)** Passed — all code blocks, URLs, identifiers, and numbers are preserved
**Modifications Made**
- Moved the entire conclusion block from the end to the beginning (format)
- Split 12 overly long sentences into 28 sentences (content)
- Rewrote 3 instances of "如上所述" in-place (content)
**Intentional Omissions**
- Kept the `## API Parameters` section unchanged: reference content requires jump navigation, reordering would disrupt positioning
- Retained two 92-word long sentences: splitting would break causal relationships
The "Intentional Omissions" section cannot be omitted. It lets the user know you made informed judgments, not missed items.
Reference File Index
| File | When to Read |
|---|
| Read every time. Complete rule list + thresholds + axis/setting markers |
references/antipatterns.md
| Read every time. Eight over-optimization patterns + self-check checklist |
| When explaining scores or manually supplementing judge item scores |
| When the document is in Chinese |
| When and overall skeleton restructuring is needed |
Common Mistakes
| Mistake | Consequence |
|---|
| Presenting the script score as the final score | 33 rules are counted as full marks, leading to inflated scores. Must clarify it is a script score |
| Modifying words when | Verification fails hard. Roll back changes |
| Deleting content in the name of "streamlining" | Violates the golden rule. Fold or move to appendix instead of deleting |
| Writing "not A but B" when rewriting | Triggers M1 contradictory tone. Make direct positive judgments instead |
| Using emojis as anchors | Results in X1 deduction. Use , tables, or dividers instead |
| Splitting into numerous two-line sections | Results in X2 fragmentation deduction |
| Reducing list items to keywords | Results in X3 deduction for incomplete sentences |
| Falsifying verification results | Integrity issue, more serious than not performing verification |