Skip to content
Skills Library
Documents & office · Writing

markdown-docs

/markdown-docs

Writes or restructures project documentation in Markdown — READMEs, guides, references, runbooks, architecture notes — organised around what the reader is trying to do. Use this whenever the user asks for a README, docs, a guide, a runbook, or says their documentation is out of date, missing, or unhelpful, and also after building something substantial that nobody else could pick up without a written explanation.

Author
OKHP3 ↗
Repository
skillz ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Writes or restructures project documentation in Markdown — READMEs, guides, references, runbooks, architecture notes — organised around what the reader is trying to do. Use this whenever the user asks for a README, docs, a guide, a runbook, or says their documentation is out of date, missing, or unhelpful, and also after building something substantial that nobody else could pick up without a written explanation.

Original author description

Writes or restructures project documentation in Markdown — READMEs, guides, references, runbooks, architecture notes — organised around what the reader is trying to do. Use this whenever the user asks for a README, docs, a guide, a runbook, or says their documentation is out of date, missing, or unhelpful, and also after building something substantial that nobody else could pick up without a written explanation.

How it works

  1. 1. Identify the reader and their moment
  2. 2. Front-load ruthlessly
  3. 3. Make every command actually runnable
  4. 4. Structure for scanning, not reading
  5. 5. Write what cannot be inferred
  6. 6. Fight rot deliberately
  7. Formatting that helps
Original SKILL.md headings · 110 lines, 889 words
SKILL.md preview
---
name: markdown-docs
description: Writes or restructures project documentation in Markdown — READMEs, guides, references, runbooks, architecture notes — organised around what the reader is trying to do. Use this whenever the user asks for a README, docs, a guide, a runbook, or says their documentation is out of date, missing, or unhelpful, and also after building something substantial that nobody else could pick up without a written explanation.
license: MIT
metadata:
  adaptation: "OKHP3 consolidation, 2026-09-19; README methods from create-readme and readme-blueprint-generator."
---

# Markdown docs

Documentation is read by someone mid-task who is slightly annoyed. They do not read from the
top; they scan for the part that matches their situation, take it, and leave. Every structural
decision follows from that.

The most common failure is not absence — it is documentation organised around the system's
structure instead of the reader's task. A page-per-module reference is easy to generate and
answers almost no real question.

For a repository README, also read [the README workflow](references/readme-workflow.md).
It covers repository evidence, optional Copilot documentation blueprints, and project-specific
presentation conventions. This local adaptation preserves the two retired README prompts;
it does not claim a live quality benchmark or change ownership of the upstream methods.

## 1. Identify the reader and their moment

Different moments need different documents, and merging them serves none:

| Moment | They need | Document |
| --- | --- | --- |
| "What is this, should I use it?" | Purpose, fit, constraints | README top section |
| "Get me running" | The shortest working path | Quickstart |
| "Teach me the concepts" | Mental model, why it works this way | Guide |
| "What are the options for X?" | Complete, scannable facts | Reference |
| "It's 3am and it's broken" | Symptom → action, no prose | Runbook |
| "Why is it built this way?" | Context, alternatives, trade-offs | Decision record |

Write one of these at a time. A quickstart that pauses to explain architecture loses the reader
who wanted to be running in two minutes.

**Done when:** you know which document you are writing and who opens it.

## 2. Front-load ruthlessly

Readers scan the first screen and decide whether to stay.

- **First sentence: what it is and what it is for.** Not history, not motivation. "A CLI that
  syncs Postgres tables to BigQuery on a schedule."
- **Then: whether it fits them.** Requirements, constraints, what it does not do. Saving
  someone twenty minutes by telling them early that it will not work for them is a service.
- **Then: the first working thing.** Copy-pasteable, complete, no placeholders they must
  resolve first.

**Done when:** the first screen answers "what is it" and "does it apply to me".

## 3. Make every command actually runnable

The fastest way to lose trust is a command that fails. For each one:

- Give it whole — no `...`, no `<your-value-here>` without saying where to get the value
- Say what success looks like, so they can tell whether it worked
- Note where it must be run, if that matters

If a step needs a value from somewhere else, say where. "Set `API_KEY`" is a dead end;
"Set `API_KEY` from Settings → Developer → API Keys" is a step.

**Run the instructions yourself, in order, from a clean state.** Documentation written from
memory of how it works is documentation with a missing step, always.

**Done when:** you have executed the path you wrote.

## 4. Structure for scanning, not reading

- **Headings are navigation.** Write them as the questions readers arrive with — "Deploying to
  production" beats "Deployment"; "The sync fails with a timeout" beats "Troubleshooting".
- **Front-load every paragraph.** The first sentence carries the point; the rest supports it.
- **Use tables for anything with parallel structure.** Options, flags, environment variables,
  error codes. A table is scannable; six paragraphs describing six flags are not.
- **Keep code blocks short and tagged with a language.** A forty-line block is not read.
- **One thing per section.** If a section covers two topics, the second is unfindable.

**Done when:** the table of contents alone tells a reader where to go.

## 5. Write what cannot be inferred

Skip what the code already says. Prioritise what a reader cannot discover on their own:

- **Why**, when the choice was not obvious — the alternatives, and why they lost
- **Failure modes:** what breaks, what it looks like, what to do
- **The gotchas:** ordering requirements, undocumented limits, the thing that silently does
  nothing if you get it wrong
- **Boundaries:** what this does not do and never will, so nobody spends a day finding out

A short document containing these beats a long one that paraphrases the function signatures.

**Done when:** nothing in the document could be trivially derived from reading the source.

## 6. Fight rot deliberately

Wrong documentation is worse than missing documentation — it is believed.

- **Put examples where they can be tested**, and test them in CI if the ecosystem allows it
- **Do not duplicate facts across pages.** Link instead. A number in two places becomes two
  different numbers.
- **Avoid time-relative statements.** "Currently", "soon", "the new API", all wrong later.
  Version-qualify instead: "as of 2.x".
- **Delete rather than deprecate in place.** Old instructions left visible get followed.
- **Date anything that will age:** benchmarks, screenshots, pricing.

**Done when:** every fact has exactly one home, and nothing depends on when it was read.

## Formatting that helps

Use fenced blocks with languages, relative links between docs so they survive moving, real
values in examples rather than `foo`/`bar`, and alt text on images. Keep line length reasonable
in source so diffs stay reviewable — a docs change that shows as one modified 400-character
line cannot be reviewed.
Files in this package (4)
  • LICENSE 1 KB
  • SKILL.md 6 KB
  • references/readme-workflow.md 4 KB
  • references/licenses/awesome-copilot.txt 1 KB

Versions

The database has no other skills named markdown-docs.

Database snapshot: 13.11.2026 · package version cfbef4742bd0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90ns-docs-writer
    (NS) Human-facing project docs — README, docs/ guides, runbooks, contributor markdown. Use whenever the user asks for documentation, README updates, how-to guides, or docs/ content — even if they say \"explain how to use\" instead of \"write docs\". Do NOT use for code comments,…
  • 100technical-writer
    Writes and restructures technical documentation - READMEs, tutorials, how-to guides, user guides, architecture docs, onboarding guides, runbooks and SOPs, troubleshooting guides, release notes, and knowledge base articles - grounded in the actual code or product, with commands…
  • 100technical-documentation
    Write or update technical documentation that helps a reader use, operate, integrate, or maintain a system. Use for READMEs, API guides, setup instructions, runbooks, architecture notes, and migration docs.
  • 100documentation
    Writes documentation for one reader doing one task: READMEs, quickstarts, how-to guides, API reference, runbooks, and changelogs. Use when docs are missing, stale, or unreadable, when a change made existing docs wrong, or when someone new cannot get the project running. Verifies…
  • 100documentation
    Write and maintain technical documentation. Trigger with "write docs for", "document this", "create a README", "write a runbook", "onboarding guide", or when the user needs help with any form of technical writing — API docs, architecture docs, or operational runbooks.
  • 100documentation
    Use this skill when the user asks you to write, update, or fix project documentation — READMEs, API docs, user guides, ADRs, or other Markdown docs. Also use when code changes need user-facing docs updates. Only write Markdown files; do not use for implementation, planning or test work.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.