Md maximalist

Markdown Maximalist — The Full Toolbox, Used Deliberately

When this skill is invoked, use markdown's whole formatting range to make a document faster to scan. If invoked with an argument (e.g., /md-maximalist STATUS.md), restructure that file. If invoked without arguments, apply the standard to the markdown you are currently writing.

Maximalist means the full toolbox is on the table — not that every tool goes in every document. A plain paragraph is the right answer often. The discipline is choosing the form that fits the content's shape, and reaching past the default bullet list when the content is really a table, a sequence, or a tangent.

This skill is both user-invocable and agent-granted:

• User-invoked — run /md-maximalist <path> to restructure an existing doc's formatting.
• Agent-granted — agents that list md-maximalist in their skills: frontmatter reach for these forms while writing, without an explicit invocation.

1. The one test

Every formatting choice must speed up a reader who is scanning.

If a table reads worse than a sentence, write the sentence. If a callout would say the same thing as the paragraph above it, cut it. Formatting that exists to look rich is decoration — the thing this skill forbids.

2. Choose the form from the shape of the content

Content shape	Right form
3+ parallel items with the same attributes	Table — one row each, attributes as columns
A sequence where order matters	Ordered list
Non-parallel points, one idea each	Bullet list with bold leads
Completion / progress state	Task list (- [ ] / - [x])
A warning, caveat, or "read this first"	Callout (see §3)
Long tangent, sample output, edge-case detail	<details> collapsible
Code, commands, signatures, file trees	Fenced block with a language tag
A term and its definition	Bold-lead bullet — - **term** — definition
A hard topic break in a long doc	Horizontal rule (---)

3. The toolbox

• Tables — for registries, comparisons, and enumerations. Keep cells short; a table crammed with paragraphs is worse than a list.
• Callouts — GitHub alerts when the target renders them. The marker sits alone on its line; put text beside it (> [!NOTE] Useful context.) and GitHub renders a plain blockquote with a literal [!NOTE] in it — the alert never fires:

  > [!NOTE]
  > Useful context that is not essential.
  
  > [!WARNING]
  > A footgun the reader will otherwise hit.
  

  Plain > **Note:** … blockquotes are the portable fallback.
• Task lists — - [x] Done / - [ ] Pending for anything with completion state; they render as checkboxes and scan instantly.
• Collapsibles — hide length, never substance:

  <details><summary>Full output of the failing run</summary>
  
  …
  
  </details>
  

  The <summary> must say what is inside, and a blank line after it is required or the markdown inside won't render.
• Fenced code blocks — always language-tagged (```ts, ```bash, ```yaml) so syntax highlighting fires.
• Bold-lead bullets — the workhorse. - **What it is** — what it does. Lets the eye pick the list apart without reading it.
• Horizontal rules — sparingly, to separate major movements in a long document.
• Emoji / badges — as anchors only (a status column, a build badge), never as punctuation. Zero is a fine number.

4. Anti-patterns

• Emphasis soup — bold and italics everywhere. When everything is emphasized, nothing is. Bold the lead; leave the rest plain.
• One-row tables — a table with a single row is a sentence wearing a costume.
• Nested-list pileups — three levels deep means the structure is wrong. Promote the sub-list to its own section or table.
• Collapsibles hiding must-read content — if the reader needs it, it does not go behind a <details>. Collapse tangents, not the point.
• Untagged code fences — no language tag, no highlighting, no reason.
• Decorative headers — headings that carry no information ("Overview", "Notes", "More") waste the single strongest scanning signal in the document.

5. Workflow

1. Read the content's shape — is it parallel, sequential, stateful, or a tangent?
2. Pick the form from §2 — do not default to a bullet list for everything.
3. Apply the one test (§1) — would a scanning reader be faster with this, or is it decoration? Revert what fails.
4. Sweep for anti-patterns (§4) — emphasis soup, one-row tables, deep nesting, untagged fences.

When called by agents

An agent granted md-maximalist picks the fitting form while drafting, rather than writing a flat bullet list and prettifying it afterward. Match the host document's existing conventions — if a repo's docs never use collapsibles or emoji, do not introduce them unasked. Portability caveat: GitHub > [!NOTE] alerts and <details> blocks render only in HTML-aware targets, so fall back to plain blockquotes where the output may be read as raw text.