version: "1.0.0" name: humanify-docs description: > Write Markdown docs that read like a person wrote them, or rewrite AI-generated docs so they do — short sections, lists and tables where they help, minimal formatting, no code unless the doc is genuinely technical. For a broad topic (a codebase overview, how a system works end-to-end) it researches with a small, budgeted set of subagents and writes the doc itself. Updating an existing doc keeps its style by default and only adds what was asked. Use when: "humanify this doc", "/humanify-docs", "make this README readable", "write docs for X", "this doc reads like AI, fix it", "document how Y works", "add X to the docs", "update the docs for Y", "write a README for this project", or the user hands over a Markdown file and wants it human-friendly. Every rule here yields to what the user asks for.

humanify-docs

Produce Markdown that a developer can read top to bottom without effort. Either write a new doc or rewrite an existing one. The output is a file on disk, never a push.

The rules below are defaults. If the user asks for something else in the prompt — more examples, code snippets, a specific structure, a longer style — do what they ask.

Detail that is only needed sometimes lives next to this file. Read a reference when its step says so, not before:

Step 0 — Classify the request

Four shapes. Decide which before doing anything else.

Then settle three things, from the prompt or by asking once in a single message. If no answer comes, use the default and say so in the final report.

• Audience. New contributor, end user, or maintainer. Default: new contributor.
• Where it goes. An existing file is rewritten in place. A new file goes where the user says, otherwise next to related docs, otherwise docs/. Say where it landed.
• Doc kind. One of overview, tutorial, how-to, reference, README. Then read that kind's section in references/doc-kinds.md, or references/readme.md for a README; it decides the shape and whether examples belong. A project's root README.md is always a README.

An overview is a general doc: no code in it. Everything else counts as technical, and even there code stays at the minimum that lets the reader act.

Step 1 — The repo outranks this file

Before writing, look at what the project already has and follow it:

• Existing doc conventions. A docs/ layout, a docs generator with front matter or a sidebar config, a house heading style, an established set of terms. Keep all of it. Front matter is never stripped.
• Written rules. CONTRIBUTING.md, CLAUDE.md, AGENTS.md or a docs style guide.
• Links into the doc. Renaming a heading breaks every link to its anchor. Before renaming or removing a heading, search the repo for links to it and update them, or keep the heading.

Where the repo is silent, the rules below apply. Where it conflicts, the repo wins.

Step 2 — The writing rules

These are the whole point of the skill. Apply them to everything you produce.

Opening

The first paragraph says what this is, who it is for, and when to read it, in two or three sentences. A reader decides in ten seconds whether to keep going. No preamble before it.

Structure

• Divide the content into parts: sections, then short paragraphs within them.
• One idea per section. If a section needs a sub-heading to stay clear, it is two sections.
• Order sections the way the doc kind says. Default: what it is, how it fits, how to use it, details.
• Headings carry the outline. Someone reading only the headings gets the whole story. Descriptive, not clever.
• Examples follow the doc kind. Outside what it allows, leave them out unless the user asks or one is clearly the fastest way to explain.

Content

• Straight to the point. Say the thing, then stop.
• One name per thing. Pick a term and use it in every section. Synonyms for the same concept are the fastest way to confuse a reader.
• No code lines, variable names, flags or paths in an overview. In technical docs, keep them to the minimum that lets the reader act, and put them in code blocks, not in prose.
• Link, do not duplicate. If a fact lives in another doc, point at it. Copies rot.
• No edge cases, no long walkthroughs, no dialogue-style explanations. Cover the normal path.
• Never mention that the doc was generated or rewritten by AI.

Voice

• Active voice, second person, present tense. "You run the build" rather than "the build is run".
• Short sentences. Plain words. Professional, not stiff.
• Drop "simply", "just", "easy", "obviously" and their relatives. If it were easy, the reader would not need the doc.

Lists and tables

• Use a list when items are parallel: steps, options, files, rules.
• Use a table when data has two or more dimensions: options and their trade-offs, commands and what they do, components and their roles.
• Do not turn everything into a list. A doc that is only bullets is as hard to read as a doc that is only prose. Text sections carry the reasoning, lists and tables carry the data.
• When a list sorts things into categories, bold the category, then a hyphen, then the rest. * **Plugin scaffolding** - manifests, contributor notes, and the conventions. Keep the category to a few words and the line after it plain. This is the one place bold is expected rather than rationed, and it only applies when the items really are categories. A list of steps, options or rules takes no bold at all.

Formatting

• Keep it sparse. Bold at most a few words per section, usually none. The exception is a categorised list, which bolds its categories as above.
• Headings for sections only. No headings on single paragraphs.
• No nested bullets deeper than one level.
• No emoji, no horizontal rules, no callout boxes.
• No em dashes or en dashes. Use a plain hyphen. Where a dash is doing the work of a comma, a colon or a full stop, use that instead and let the sentence end.
• Do not break a sentence across lines. Let a paragraph run as one line and let it wrap on its own. Split with a blank line, never a single one, and only when the paragraph has grown long or the subject changes. A blank line is a change of thought, so it should read like one. One bullet is one line too. This governs the doc you write, whatever column the files around it wrap at. Only a written rule that names docs, or a lint config that enforces a line length on them, overrides it. Matching existing files, or a wrap rule meant for other files such as source or skill content, does not.
• Text-heavy sections stay short and use almost no formatting at all.

Step 3 — Rewriting an existing doc

Read the whole file first, then decide the structure once for the whole doc. Then work through it in this order:

1. Keep every fact the reader needs. Rewriting is not a licence to drop information.
2. Check facts that are cheap to check. A stale doc rewritten nicely is a nicely wrong doc. When a claim names a file, command, option or behaviour you can confirm in a minute, confirm it, and fix or flag what no longer holds.
3. Cut repetition, filler, hedging, and any sentence that explains what the next sentence says.
4. Regroup the remaining content into sections that follow Step 2 and the doc kind.
5. Convert prose that lists things into a list or table. Convert lists of full sentences that argue a point back into prose.
6. Strip formatting down to what Step 2 allows, and join every hard-wrapped paragraph and bullet back into one line.
7. Remove code and identifiers from overviews. In technical docs, keep only what is needed to act.
8. Re-check links and anchors (Step 1).

Write the result over the original file unless the user asked for a copy. Do not commit.

Step 4 — Updating an existing doc

The user wants new information in a doc that already exists. The doc's current style is not the task.

• Ask once, at the start, whether they also want the doc brought up to the rules in Step 2. Batch it with the Step 0 questions. No answer means keep the style as it is: match its headings, tone, formatting and term choices, and only add what was asked.
• Untouched sections stay untouched. Do not reflow, reword or reformat them unless the user said yes to a style pass. A reviewer of the diff should see only the new material.
• Confirm what is there before adding to it. New information often changes or contradicts old claims. The agents that check the existing doc report what no longer holds, and you fix those spots alongside the addition.

Agents split into two jobs: some confirm the existing doc still matches the code, the rest research the new material. How many of each scales with the doc; the rule is in references/subagent-research.md. A short doc with one new fact you can look up yourself needs no agents at all.

Write the addition in the doc's own style, in the place a reader would look for it. Do not commit.

Step 5 — Writing a broad doc

Read references/subagent-research.md and follow it. In short: outline first, one research agent per section that needs reading you have not done, at most four in flight, agents return facts and you write every section yourself so the doc has one voice.

Step 6 — Final pass

Before reporting done, read the whole doc once as the intended reader and check:

• The first paragraph alone tells a reader whether this doc is for them.
• The headings alone tell the story.
• Each section says one thing and no section is a wall of text or only bullets.
• One term per concept, everywhere.
• Formatting is minimal. Remove any bold or heading that does not earn its place.
• No sentence is broken across lines. Every paragraph and every bullet outside a code block is a single line. Check the file itself, not how it renders.
• Overviews contain no code or identifiers. Technical docs contain the minimum.
• The doc kind's own checklist in references/doc-kinds.md or references/readme.md passes.
• For an update: untouched sections are byte-for-byte as before unless a style pass was agreed, and every old claim the agents flagged as stale was fixed or reported.
• Nothing was invented and nothing known to be stale was kept. Every fact came from the source doc, the repo, or the user.
• Every link and anchor still resolves.

Report the file path and a two-line summary of what changed or what the doc covers.

Guardrails

• Never push, commit, or open anything. The file on disk is the deliverable.
• Never delete facts the reader needs in the name of brevity.
• Never strip front matter or break an anchor without fixing what points at it.
• Subagents research only. They never write the doc, never edit files, never spawn agents.
• The user's prompt overrides any rule in this file.