Documentation Formatting

Documentation Formatting

Use this skill for deterministic Markdown structure and validation.

This skill owns:

• heading numbering
• prose wrap validation
• Markdown table formatting
• spacing cleanup
• Markdown link checks

Do not use this skill to decide documentation topology or canonical topic ownership. Use the documentation-topology skill for that.

1. Workflow

1.1. Validate before writing

Run the bundled formatter in check mode first:

• python scripts/format_markdown.py --check [flags] <file.md> [...]

Use the narrowest flags that match the requested change:

• --headings
• --tables
• --wrap
• --spacing
• --all

Show all formatter drift and warnings to the user before any write action.

When --headings or --all are used with --check, review any warnings about missing or mis-numbered headings before asking to write.

1.2. Use cheap validators

Use these helpers before manual inspection when relevant:

• python scripts/check_heading_style.py --json <file.md> [...]
• python scripts/check_line_wrap.py --json <file.md> [...]
• python scripts/check_doc_links.py --json <file.md> [...]

Prefer validator output over manual scanning for structural issues.

1.3. Write mode

Only after the user approves, run:

• python scripts/format_markdown.py [flags] <file.md> [...]

2. Rules

• Only use the bundled formatter at scripts/format_markdown.py.
• Do not substitute repository-local or third-party formatters unless the user explicitly asks.
• Preserve fenced code blocks.
• Flag documents with more than one H1 (#) and strongly recommend rearranging them to use one title heading with later headings demoted to sections.
• Do not wrap tables as prose.
• Warn about wide table rows instead of force-wrapping them.
• Keep heading numbering deterministic and hierarchical.

3. Script contract

Prefer JSON output from validator scripts.

Exit codes:

• 0 = success, no issues
• 1 = success, issues found
• 2 = config or usage error
• 3 = runtime failure

4. Bundled scripts

This sub-skill includes local bundled scripts:

• scripts/format_markdown.py
• scripts/check_heading_style.py
• scripts/check_line_wrap.py
• scripts/check_doc_links.py
• scripts/doc_support.py

Use these local scripts instead of reaching outside the skill folder.