← ClaudeAtlas

writing-markdown-docslisted

Use whenever writing a standalone markdown document or a note in the Obsidian vault, even when the user only says "write this up", "document what we found", "save your notes", "summarize where we are", "explain X in a doc" or "make me a doc". Covers a learning doc, a design, an implementation plan, a task card for an agent, a status or incident report, a decision analysis, a handoff, a runbook and a reference. Covers every note in the Obsidian vault too: writing, updating, splitting or normalising notes, frontmatter, wikilinks, MOCs, callouts, Canvas or Bases, after second-brain-obsidian has decided whether and where to write. Sets the genre and outline, readable prose (answer first, terms defined, one idea per sentence, a picture where prose would be a wall), where the file goes, and one dialect that renders the same in the terminal (markview) and in Obsidian. Interactive pages, simulations, 3D and prototypes go to visual-artifacts. Does not apply to README, CLAUDE.md, CONTRIBUTING, changelogs or PR bodies.
SeanoChang/seanock · ★ 0 · Data & Documents · score 70
Install: claude install-skill SeanoChang/seanock
# Writing Markdown Docs A document is read by someone who was not there. Every rule here serves that reader: they get the answer first, they never meet an undefined term, and they see a picture where prose would be a wall. ## Non-negotiables 1. **Answer first.** Open with a `> [!tldr]` of at most 60 words, or an opening paragraph of at most three sentences. Nothing comes before it except a one-line `Changed since <date>:` in a handoff. Method, sources and caveats go after the answer (`lead-long`, `lead-late`). 2. **Write to the reader.** Say "you", not "the user" or "the owner". Leave out the story of how the work was done (agents, panels, rounds) unless the reader asked for it (`reader-third`). 3. **Define every term and ID once,** in the reader's words, where it first appears. Prefer a name to an ID: "the retry fix", not "D128". A project's own numbering pairs with a name on first use: "L0 normalize" (`undefined-id`). 4. **One idea per sentence.** Write about 60% of the way to ASD-STE100: active voice and plain words. Aim for 15 to 20 words a sentence, never over 30. An aside gets a sentence of its own (`prose-long`, `paren-dense`, `dash-dense`). 5. **Pick a representation for each idea** from the table below. A section of more than about 250 words with no table, diagram, math or image is a wall (`no-visual`). 6. **Fit the genre's budget, and cut.** The budget counts what the reader reads: prose and tables. Every sentence must change w