---
name: markdown-docs-architect
description: "Drafts a complete Markdown document from a section outline, shaped for the audience and purpose you name, with a table of contents, consistent heading levels, and code samples where the reader needs them. Use when a section outline and an audience need turning into a finished Markdown document with a TOC, from onboarding guide to API reference. Do not use for assembling a project README from ready-made sections, or cleaning up an existing file. Related topics: coding, markdown."
---

# Markdown Docs Architect

Drafts a complete Markdown document from a section outline, shaped for the audience and purpose you name, with a table of contents, consistent heading levels, and code samples where the reader needs them.

## When to use

Use this skill when a section outline and an audience need turning into a finished Markdown document with a TOC, from onboarding guide to API reference. Do not use it for assembling a project README from ready-made sections, or cleaning up an existing file.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Map each outline section to what it must answer for the audience and goal, so no section is filler.
3. Write the H1 and a two-sentence purpose statement, then a table of contents whose anchors match every H2.
4. Draft each section in outline order with H2 and H3 only, using lists for options and numbered steps for sequences.
5. Insert a tagged, self-contained code sample wherever the reader would otherwise guess, when samples are enabled.
6. Read the whole document back for tone and heading consistency and deliver it as plain Markdown.

## Inputs

- **Document title** (free text, e.g. "Title of the document")
- **Target audience** (choose one: Developers, QA Engineers, Product Managers, End Users)
- **Primary goal** (choose any: Onboarding, Reference, Troubleshooting, API Guide)
- **Section outline** (longer free text)
- **Include code samples** (choose one: Yes, No)
- **Tone** (choose one: Formal, Conversational, Technical, Friendly)

## Output

A plain Markdown document: H1 title, purpose statement, table of contents, then one H2 per outline section in the given order with H3 subsections and tagged code fences where enabled.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Markdown Docs Architect

Write a full Markdown document from my outline.

- Document title: {{Document title}}
- Target audience: {{Target audience}}
- Primary goal: {{Primary goal}}
- Section outline: {{Section outline}}
- Include code samples: {{Include code samples}}
- Tone: {{Tone}}

Decide what each section must answer for this audience and goal before writing: onboarding sections end with the reader having done something, reference sections are scannable tables and lists, troubleshooting sections pair a symptom with a cause and a fix, API guide sections show the request and the response. Keep the outline order and the section names as given. Use one H1 for the title, H2 for each outline section, and H3 only for sub-steps; never skip a level. Open with a two-sentence purpose statement, then a table of contents linking to every H2 with anchors that match the headings. When code samples are on, put a fenced block with a language tag in every section where the reader would otherwise have to guess, and keep each sample runnable on its own. Bold the terms the reader will search for, use bullet lists for options and numbered lists for sequences, and match the chosen tone throughout. Return the document as plain Markdown starting with the H1.

## Pitfalls

- Generating a table of contents whose anchors do not match the final headings, so every link is dead.
- Writing reference material as flowing prose when the reader needs a scannable table.
- Adding sections the outline did not ask for, which the author then has to remove.
