documentation-quality

name	documentation-quality
version	2.0
last_updated	2026-08-29T00:00:00.000Z
tags	["documentation","quality","docs","writing","templates"]
description	Documentation quality standards and writing principles. Use when establishing formatting rules, reviewing doc quality metrics, creating writing guidelines, or enforcing consistent documentation style across a project.

Documentation Quality Standards

Use this skill when documentation should be judged against explicit standards instead of subjective preference.

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

• Reviewing docs before merge
• Creating or updating a style guide
• Defining expectations for examples, structure, and terminology
• Auditing a docs set for consistency and readability

Core Standards

• Clear audience and scope
• Stable heading hierarchy
• Runnable or honest examples
• Consistent terminology
• Explicit edge cases, constraints, and failure modes

Documentation Stack Reference

Inherit the shared stack from documentation-patterns: source-of-truth discovery, audience framing, structure selection, verification, and freshness checks. Keep this skill focused on quality gates instead of restating the full stack.

Anti-Patterns

• Writing for the author instead of the reader: It bakes in unstated context and leaves the actual audience unsure what to do next.
• Skipping concrete examples or commands: Abstract guidance is easy to approve and hard to apply correctly.
• Letting links, screenshots, or versions drift: Polished formatting does not help if the instructions are no longer true.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Documentation Quality output identifies audience, purpose, source of truth, and freshness requirements.
2. Pass/fail: Shared documentation-stack guidance is referenced instead of duplicating another documentation skill.
3. Pass/fail: Claims, links, commands, examples, and screenshots are verified or explicitly marked unverified.
4. Pressure-test scenario: Apply the skill to a doc request with a stale command, missing owner, and conflicting audience.
5. Success metric: Zero undocumented assumptions; every reader-facing claim is sourced or scoped.

Quality Checklist

• Title and purpose are clear
• Heading levels do not jump unexpectedly
• Code examples have language tags and realistic inputs
• Commands match current tooling
• Links and file paths are accurate

Cross-Skill Workflow

• Use documentation-authoring when the content itself still needs to be drafted or clarified.
• Use documentation-patterns when the review shows that the problem is document shape rather than wording.
• Use this skill as the final standards check before publish or merge.

Agent Prompt Template

Use the documentation-quality skill to review this document against explicit standards.
Artifact: [file or pasted draft].
Audience: [who will read it].
Check for clarity, completeness, accurate examples, terminology consistency, and stale references.
Report concrete findings first, then suggest the smallest high-value fixes.

References & Resources

Documentation

• Writing Standards - Clarity, example quality, terminology, and formatting guidance

Scripts

• Doc Style Audit - Check Markdown files for heading jumps, long lines, tabs, and trailing whitespace

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.

• GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the workflow in project instructions when folder discovery is unavailable.
• Claude Code: keep the folder in a local skills directory or a compatible plugin source.
• Codex: install or sync the folder into $CODEX_HOME/skills/documentation-quality and restart Codex after major changes.

MCP Availability And Fallback

Preferred MCP Server: None required

• Fallback prompt: "Use the Documentation Quality Standards skill without MCP. Rely on the local SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
• If the current host does not expose a matching server, use the bundled references, scripts, native toolchain, and manual workflow already described in this skill.
• Treat direct local verification, rendered output, logs, tests, or screenshots as the fallback evidence path before completion.

Related Skills

• documentation-authoring: Use it when the workflow also needs drafting structured technical or product documents.
• documentation-patterns: Use it when the workflow also needs reusable documentation structures and templates.
• documentation-verification: Use it when the workflow also needs final documentation validation before publishing.
• notion-docs: Use it when the workflow also needs Notion page and database publishing workflows.