Markdown → Formal Document

Turn a working Markdown draft into a document you can hand to an external reader — a partner, a customer, an executive, a reviewer. The input is usually serviceable but informal: AI-drafted prose, ad-hoc formatting, stray symbols, lists where paragraphs belong. The output is a deliberate, human-sounding, properly typeset document.

This skill orchestrates five passes. Each pass has a focused reference subskill. Run them in order — structure before prose before export, because reshaping content after you've typeset it wastes work.

Operating principles

1. Work on a copy. Never edit the original draft. Duplicate it to a -working (or final-named) file first, so the source survives and you can diff.
2. One change class at a time. Do structure, then format-shape, then prose, then export. Mixing them produces churn and missed items.
3. Propose, then apply for judgment calls. Format-shape and structural cuts are editorial — surface options and let the user decide rather than silently rewriting. Mechanical cleanups (symbols) you can just do, then report counts.
4. Verify every export. A converted file is not done until you've confirmed no raw Markdown, no stray artifacts (e.g. bookmark anchors), and that tables/headings survived.

The pipeline

Pass 1 — Structure & scope

Reshape the document into a formal skeleton before touching wording.

• Give it a clear, formal title; drop draft-y metadata blocks (Audience / Status / Classification / "Last updated") unless the user wants them.
• Remove sections that don't belong in the final audience's copy (internal notes, leak-check logs, appendices, glossaries the reader won't use).
• Decide on section numbering: for a clean formal doc, prefer letting headings carry the structure (Overview) over manual prefixes (1. Overview) — manual numbers drift as sections move. (Pandoc can auto-number at export if you want it; see Pass 5.)
• Consolidate sections that say the same thing; cut low-value subsections. See reference/structure-and-scope.md.

Pass 2 — Format-shape decisions (prose vs bullets vs tables)

Decide, section by section, which form each block should take. A formal document is not "all prose" — it's the right form per content type. Produce a section-by-section recommendation table, mark the clear wins and the borderline calls, and let the user confirm. See reference/format-decision.md.

Pass 3 — Prose cleanup (clarity + de-AI)

Tighten the wording and strip the signals that read as machine-generated.

• Apply Strunk-style concision. If the writing-clearly-and-concisely skill is available, invoke it here; otherwise use reference/symbol-cleanup.md plus general concision.
• Triage and remove AI tells — em-dashes, arrows, section symbols (§), horizontal-rule borders — using varied replacements so the fix itself doesn't look mechanical. See reference/symbol-cleanup.md.

Pass 4 — Convert to the target format

Export the cleaned Markdown to .docx (Google-Docs-ready) or PDF with pandoc, using tech-document defaults and the flags that prevent stray artifacts. If the md-to-docx skill is available you may delegate the raw conversion to it, but still apply the artifact fixes and verification here. See reference/pandoc-export.md.

Pass 5 — Typography & final formatting

Apply formal-document typography in the target tool (Word / Google Docs): font pairing, heading sizes, line spacing, margins. This is where the document stops looking like an imported draft. See reference/typography.md.

Definition of done

• Source preserved; work done on a copy.
• Every section's form is deliberate (Pass 2 confirmed).
• Zero unintended AI-tell symbols (em-dashes in prose, arrows, §, --- borders).
• Exported file verified: no raw Markdown, no stray bookmark/anchor artifacts, tables and headings intact.
• Typography applied; document reads as finished, not imported.

Composes with

• writing-clearly-and-concisely — deeper prose editing (Pass 3).
• md-to-docx — raw pandoc conversion (Pass 4). This skill is the superset workflow: it sequences those, adds the structural/format-shape/typography passes, and enforces the verify-every-export rule.