| name | professional-word-output |
| description | Use when producing or quality-checking a polished Microsoft Word document with controlled styles, pagination, tables, figures, and render evidence; use manual-guide for end-user content and python-document-generation for automated multi-format exports. |
| metadata | {"portable":true,"compatible_with":["claude-code","codex"]} |
Professional Word Output
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.
Use When
- Generate world-class, professionally designed Microsoft Word (.docx) documents that look like a designer and communications specialist worked on them together — not AI output. Use when producing any .docx file: reports, proposals, manuals...
- The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.
Do Not Use When
- The task is unrelated to
professional-word-output or would be better handled by a more specific companion skill.
- The request only needs a trivial answer and none of this skill's constraints or references materially help.
Professional Word Output Required Context
- Gather relevant project context, constraints, and the concrete problem to solve; load
references only as needed.
- Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.
Professional Word Output Core Method Notes
- Read this
SKILL.md first, then load only the referenced deep-dive files that are necessary for the task.
- Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
- Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.
Quality Standards
- Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
- Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
- Prefer deterministic, reviewable steps over vague advice or tool-specific magic.
Professional Word Output Existing Failure Notes
- Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
- Loading every reference file by default instead of using progressive disclosure.
Professional Word Output Core Deliverables
- A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
- Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
- References used, companion skills, or follow-up actions when they materially improve execution.
Evidence Produced
| Category | Artifact | Format | Example |
|---|
| Release evidence | Generated Word document | Branded .docx artefact compliant with the professional-word-output design standard | docs/output/report-2026-04-16.docx |
References
- Use the
references/ directory for deep detail after reading the core workflow below.
Inputs
| Artefact | Source or provider | Requirement | If absent |
|---|
| Approved content, brand rules, and delivery format | content owner and design system | required | Return an unrendered source plan when fonts or rendering are unavailable |
Capability contract
Read access to approved content, brand rules, and document constraints is required. DOCX edits need explicit authority; replacing content, installing fonts, or publishing the file requires separate approval.
Degraded mode
Without required fonts or page rendering, return a qualified DOCX source or layout specification and mark pagination, clipping, and visual quality unassessed.
Decision rules
| Choice | Action | Failure avoided |
|---|
| Document will be edited repeatedly | Use styles and fields throughout | Manual formatting drifts |
Outputs
| Artefact | Consumer | Observable acceptance condition |
|---|
| DOCX and render-QA record | named reader and release owner | Styles are controlled and every page is visually inspected for overflow and breaks |
Professional Word Output Evidence Notes 1
- Record style definitions, font substitutions, field updates, structural checks, page-render findings, and unresolved layout defects.
Worked example
Build a report with named heading and table styles, update fields, render all pages, and correct widows, clipped tables, and orphaned headings before delivery.
Two things kill document quality equally: bad design and bad writing. A document must pass both tests. This skill addresses both.
Reference files (read when needed):
references/typography-layout.md — fonts, spacing, margins, colour palettes, visual hierarchyreferences/written-communication.md — structure, clarity, tone, anti-patternsreferences/word-features.md — styles, TOC, tables, images, sections, cover pages, watermarksreferences/quality-checklist.md — pre-delivery checklist (run before every delivery)
The Standard
Every document produced must pass this bar: a professional communications specialist and a document designer would both be satisfied. This means:
- Every typographic decision is intentional and consistent
- The writing is clear, structured, and free of AI-slop vocabulary
- Navigation elements (TOC, headers/footers, page numbers) are complete and correct
- Visual hierarchy guides the reader without effort
- The document looks the same on any machine (styles, not direct formatting)
Production Pipeline
Documents are produced via Pandoc + python-docx + reference.docx template:
Markdown source (structured content)
↓ pandoc --reference-doc=templates/reference.docx
.docx (styles applied from reference.docx)
↓ manual python-docx post-processing (cover page, TOC, header/footer)
Final .docx → PDF export
Build commands
pandoc source.md -o output.docx --reference-doc=templates/reference.docx
pandoc source.md -o output.docx --reference-doc=templates/reference.docx --toc --toc-depth=3
python scripts/create-reference-docx.py
Style System
Pandoc maps Markdown elements to named Word styles in reference.docx. Never bypass this with direct formatting.
| Markdown element | Word style |
|---|
# Heading | Heading 1 |
## Heading | Heading 2 |
### Heading | Heading 3 |
#### Heading | Heading 4 |
| Body paragraph | Normal |
```code block``` | Source Code / Verbatim |
`inline code` | Verbatim Char |
> blockquote | Block Text |
| Table | Table Grid |
YAML title: | Title |
YAML subtitle: | Subtitle |
*Caption* below figure/table | Caption |
If a style needs to change, change it in reference.docx — never in the document directly.
Heading Flow & Page Break Rules
These rules are mandatory. They determine how the document breathes across pages and whether the reader can follow the structure without effort.
Rule 1 — Heading 1 always starts a new page
Every # Heading 1 forces a page break before it. Major sections never share a page with the section that precedes them. This makes the document scannable: readers flipping through pages immediately see where each chapter/section begins.
Word setting: Paragraph → Line and Page Breaks → Page break before = ON
python-docx:
from docx.oxml.ns import qn
from docx.oxml import OxmlElement
h1 = doc.styles['Heading 1']
h1.paragraph_format.page_break_before = True
h1.paragraph_format.keep_with_next = True
Rule 2 — Heading 2 and Heading 3 stay with their first paragraph
If the heading plus its first following paragraph do not entirely fit on the current page, the whole unit moves to the next page. A heading that appears at the bottom of a page with its content on the next page is a design failure.
Word settings on Heading 2 and Heading 3:
- Paragraph → Line and Page Breaks → Keep with next = ON
- Paragraph → Line and Page Breaks → Keep lines together = ON
Word setting on Normal / body paragraphs:
- Paragraph → Line and Page Breaks → Keep lines together = ON
This combination means: the heading is glued to the paragraph that follows it, and that paragraph will not be split across pages. If the pair doesn't fit, both move to the next page.
python-docx:
for style_name in ['Heading 2', 'Heading 3']:
style = doc.styles[style_name]
style.paragraph_format.keep_with_next = True
style.paragraph_format.keep_together = True
doc.styles['Normal'].paragraph_format.keep_together = True
Rule 3 — Widow and orphan control is always on
No paragraph's first line appears alone at the bottom of a page (orphan), and no paragraph's last line appears alone at the top of a page (widow).
Word setting: Paragraph → Line and Page Breaks → Widow/Orphan control = ON (this is the Word default but must be confirmed in reference.docx).
doc.styles['Normal'].paragraph_format.widow_control = True
Summary table — paragraph flow settings per style
| Style | Page break before | Keep with next | Keep lines together | Widow/orphan |
|---|
| Heading 1 | ON | ON | — | — |
| Heading 2 | OFF | ON | ON | — |
| Heading 3 | OFF | ON | ON | — |
| Heading 4 | OFF | ON | ON | — |
| Normal | OFF | OFF | ON | ON |
| Body Text | OFF | OFF | ON | ON |
| Caption | OFF | OFF | OFF | OFF |
What this looks like in the document
- Opening a document and scanning: each major section (H1) occupies its own visual territory — top of a fresh page
- Reading through body content: the eye never arrives at an H2/H3 sitting stranded at the bottom of a page; the heading is always above its content
- Short paragraphs never lose their first or last line to a page break
- The result is a document that reads like it was typeset, not generated
Typography Specification
Read references/typography-layout.md for full font stacks and spacing tables. The standard corporate stack:
| Element | Font | Size | Colour |
|---|
| Title | Calibri Light | 28pt Bold | #1F3864 |
| Heading 1 | Calibri Light | 16pt Bold | #1F3864 |
| Heading 2 | Calibri Light | 13pt Bold | #2E5D8A |
| Heading 3 | Calibri | 11pt Bold | #4472C4 |
| Body / Normal | Calibri | 11pt Regular | #262626 |
| Code | Consolas | 9.5pt Regular | #1A1A1A |
| Caption | Calibri | 9pt Regular | #595959 |
| Header/Footer | Calibri | 9pt Regular | #595959 |
Heading 1 visual anchor: 4.5pt navy left border bar — applied via style paragraph border, not manual formatting.
Spacing Rules
Never press Enter twice to create space. Use style space-after settings.
| Style | Before | After | Line |
|---|
| Heading 1 | 20pt | 6pt | Single |
| Heading 2 | 14pt | 4pt | Single |
| Heading 3 | 10pt | 3pt | Single |
| Normal | 0pt | 6pt | 1.15× |
Document Structure (every document)
1. Cover Page
---
title: "Project Name — Document Title"
subtitle: "Document Type — Category"
date: "YYYY-MM-DD"
version: "1.0"
status: "Draft | Review | Final"
---
Followed immediately by an ownership table:
| | |
|---|---|
| **Project** | Project Name |
| **Owner** | Organisation Name |
| **Author** | Author Name |
| **Version** | 1.0 Draft |
| **Date** | 2026-04-05 |
| **Classification** | Confidential — Internal Use Only |
Cover page has no header/footer (set different_first_page_header_footer = True).
2. Table of Contents
Required for all documents longer than 5 pages. Generated automatically from Heading 1/2/3 styles.
3. Body Content
Three-part structure at every level:
- Introduction — context and purpose (what this section covers)
- Development — main content, evidence, detail
- Conclusion — key takeaway or next action
4. Headers and Footers
Header: Document title (field) right-aligned, thin grey rule below.
Footer: "Page X of Y" centred, confidentiality notice left, print date right.
Table Design
Tables must look designed, not dumped. Read references/word-features.md → Tables section.
| Column A | Column B | Column C |
|---|---|---|
| Data | Data | Data |
Standard table spec:
- Header row: Navy fill (#1F3864), white bold 10pt text
- Banded rows: light blue tint (#F2F7FD) / white alternating
- Outside border: 1pt, #1F3864
- Inside grid: 0.5pt, #BBBBBB
- Caption below every table: "Table N: Description"
- Header row repeats on every page for tables spanning multiple pages
Images and Figures
- Every figure needs a caption below: "Figure N: Description" (Caption style)
- Apply a 1pt grey border (#CCCCCC) to framed figures
- Minimum 150 DPI for print documents
- Use PNG for diagrams; JPEG for photographs
- Never stretch images — use corner handles only
Written Communication Standards
Read references/written-communication.md for full guidance. Core rules:
Structure: Inverted pyramid — most important information first, at every level (document, section, paragraph, sentence).
Sentences: 15–20 words average. One idea per sentence. Active voice.
Never use:
- "Delve into", "leverage", "robust", "seamlessly", "in today's landscape"
- Vague adjectives without metrics ("fast", "powerful", "intuitive")
- Passive voice for instructions ("The button should be clicked" → "Click the button")
- Undefined acronyms on first use
- Numbered lists for non-sequential items
- Bullet lists for sequential steps
Always include:
- Clear topic sentence opening every section
- Logical connectors at paragraph transitions
- Examples to illustrate abstract claims
- Measurable specifics in place of vague adjectives
Cover Page Design Principles
A professional cover page contains:
- Brand bar — full-width colour block (1.5–2 cm height), primary brand colour
- Company logo — top-left or centred within brand bar
- Document title — 28–36pt, Light weight, high contrast against background
- Subtitle and metadata — version, date, status
- Ownership table — structured metadata block
- No header/footer — the cover page IS the identifier
Watermarks
Apply when document status requires it:
- DRAFT — grey diagonal, 50% transparency, 80pt Calibri Semi-Bold
- CONFIDENTIAL — grey diagonal, same spec
- INTERNAL USE ONLY — same spec
Insert: Design → Page Background → Watermark → Custom Watermark.
Markdown Source Quality Rules
These patterns degrade Word output — do not use them:
| Bad pattern | Why | Fix |
|---|
* for bullet lists | Inconsistent in some Pandoc builds | Use - only |
Setext headings (--- underline) | Ambiguous, not parsed correctly | Use # ATX only |
| Code blocks inside table cells | Breaks table rendering | Move code outside tables |
| Raw HTML tags | Does not render in .docx | Use Markdown equivalents |
**bold** + *italic* combined | Inconsistent output | Use one or the other |
| Blank lines instead of spacing | Creates erratic spacing | Let styles handle space |
Pre-Delivery
Before every delivery, run references/quality-checklist.md in full. The minimum final actions:
Ctrl+A → F9 — update all fields (TOC, page numbers, dates)- Review → Spelling & Grammar — fix all issues
- File → Info → Inspect Document — remove comments, tracked changes, metadata
- File → Print → verify print preview (no widows, no blank pages)
- Export PDF with accessibility tags enabled
- Name file:
ProjectName_DocumentType_v1.0_YYYY-MM-DD.docx
Customisation Reference
To change global document styling, edit scripts/create-reference-docx.py:
| What to change | Location in script |
|---|
| Heading colours | NAVY, STEEL, ACCENT constants |
| Body/heading font | FONT_BODY, FONT_HEADING constants |
| Code font | FONT_CODE constant |
| Heading 1 border weight | sz attribute in pBdr block |
| Footer content | footer section |
| Page size and margins | section.left_margin etc. |
Rebuild after changes:
python scripts/create-reference-docx.py
bash scripts/build-doc.sh <doc-dir> <output-name>
Workflow
- Confirm audience, approved content, brand rules, page constraints, and delivery format.
- Build controlled styles, sections, tables, figures, fields, and accessibility properties.
- Stop when content approval, fonts, or required assets are unavailable.
- Generate and render every page; recover from overflow, clipping, or bad breaks by repairing styles or pagination and rendering again.
Professional Word Output Evidence Notes 2
| Evidence | Consumer | Acceptance |
|---|
| DOCX structural and page-render QA record | Release owner | Every page is inspected and defects are resolved or marked not assessed |
Anti-Patterns
- Formatting headings manually. Fix: use named styles.
- Using spaces or blank lines for layout. Fix: use paragraph and section controls.
- Splitting a table row across pages unintentionally. Fix: set row behaviour and render-check it.
- Shipping without updating fields. Fix: refresh and inspect the final document.
- Claiming visual quality without rendering. Fix: mark it not assessed until pages are viewed.
Reference Index
