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.
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 its local instructions, bundled resources, standard shell or editor tools, and direct verification. Show the evidence used before concluding."
- Do not claim an MCP operation was used when the active host does not expose it.
- Treat local files, tests, rendered outputs, logs, or screenshots as the fallback evidence path.
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":
- Pass/fail: The Documentation Quality output identifies audience, purpose, source of truth, and freshness requirements.
- Pass/fail: Shared documentation-stack guidance is referenced instead of duplicating another documentation skill.
- Pass/fail: Claims, links, commands, examples, and screenshots are verified or explicitly marked unverified.
- Pressure-test scenario: Apply the skill to a doc request with a stale command, missing owner, and conflicting audience.
- Success metric: Zero undocumented assumptions; every reader-facing claim is sourced or scoped.
Quality Checklist
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
Scripts
- Doc Style Audit - Check Markdown files for heading jumps, long lines, tabs, and trailing whitespace
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.
1---
2name: documentation-quality
3version: "2.0"
4last_updated: 2026-09-08
5tags: [documentation, quality, docs, writing, templates]
6description: "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."
7metadata:
8 source: https://skillmd.com/skills/practicalswan/documentation-quality
9---
10
11# Documentation Quality Standards
12
13Use this skill when documentation should be judged against explicit standards instead of subjective preference.
14
15- Leverage native parallel subagent dispatch and 200k+ context windows where available.
16
17
18## Activation Conditions
19
20Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.
21
22- Reviewing docs before merge
23- Creating or updating a style guide
24- Defining expectations for examples, structure, and terminology
25- Auditing a docs set for consistency and readability
26
27## Core Standards
28
29- Clear audience and scope
30- Stable heading hierarchy
31- Runnable or honest examples
32- Consistent terminology
33- Explicit edge cases, constraints, and failure modes
34
35## Documentation Stack Reference
36
37Inherit the shared stack from [documentation-patterns](../documentation-patterns/SKILL.md#shared-documentation-stack): 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.
38
39<!-- MCP:START -->
40
41<!-- PORTABILITY:START -->
42## Cross-Client Portability
43
44This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.
45
46- GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the
47 workflow in project instructions when folder discovery is unavailable.
48- Claude Code: keep the folder in a local skills directory or a compatible plugin source.
49- Codex: install or sync the folder into
50 `$CODEX_HOME/skills/documentation-quality` and restart Codex after major changes.
51
52<!-- PORTABILITY:END -->
53
54## MCP Availability And Fallback
55
56Preferred MCP Server: None required
57
58- Fallback prompt: "Use the Documentation Quality Standards skill without MCP. Rely on its local instructions, bundled resources, standard shell or editor tools, and direct verification. Show the evidence used before concluding."
59- Do not claim an MCP operation was used when the active host does not expose it.
60- Treat local files, tests, rendered outputs, logs, or screenshots as the fallback evidence path.
61
62<!-- MCP:END -->
63
64## Anti-Patterns
65
66- Writing for the author instead of the reader: It bakes in unstated context and leaves the actual audience unsure what to do next.
67- Skipping concrete examples or commands: Abstract guidance is easy to approve and hard to apply correctly.
68- Letting links, screenshots, or versions drift: Polished formatting does not help if the instructions are no longer true.
69
70## Verification Protocol
71
72Before claiming "skill applied successfully":
73
741. Pass/fail: The Documentation Quality output identifies audience, purpose, source of truth, and freshness requirements.
752. Pass/fail: Shared documentation-stack guidance is referenced instead of duplicating another documentation skill.
763. Pass/fail: Claims, links, commands, examples, and screenshots are verified or explicitly marked unverified.
774. Pressure-test scenario: Apply the skill to a doc request with a stale command, missing owner, and conflicting audience.
785. Success metric: Zero undocumented assumptions; every reader-facing claim is sourced or scoped.
79
80## Quality Checklist
81
82- [ ] Title and purpose are clear
83- [ ] Heading levels do not jump unexpectedly
84- [ ] Code examples have language tags and realistic inputs
85- [ ] Commands match current tooling
86- [ ] Links and file paths are accurate
87
88## Cross-Skill Workflow
89
90- Use [documentation-authoring](../documentation-authoring/SKILL.md) when the content itself still needs to be drafted or clarified.
91- Use [documentation-patterns](../documentation-patterns/SKILL.md) when the review shows that the problem is document shape rather than wording.
92- Use this skill as the final standards check before publish or merge.
93
94## Agent Prompt Template
95
96```text
97Use the documentation-quality skill to review this document against explicit standards.
98Artifact: [file or pasted draft].
99Audience: [who will read it].
100Check for clarity, completeness, accurate examples, terminology consistency, and stale references.
101Report concrete findings first, then suggest the smallest high-value fixes.
102```
103
104## References & Resources
105
106### Documentation
107- [Writing Standards](./references/writing-standards.md) - Clarity, example quality, terminology, and formatting guidance
108
109### Scripts
110- [Doc Style Audit](./scripts/doc-style-audit.py) - Check Markdown files for heading jumps, long lines, tabs, and trailing whitespace
111
112## Related Skills
113
114- [documentation-authoring](../documentation-authoring/SKILL.md): Use it when the workflow also needs drafting structured technical or product documents.
115- [documentation-patterns](../documentation-patterns/SKILL.md): Use it when the workflow also needs reusable documentation structures and templates.
116- [documentation-verification](../documentation-verification/SKILL.md): Use it when the workflow also needs final documentation validation before publishing.
117- [notion-docs](../notion-docs/SKILL.md): Use it when the workflow also needs Notion page and database publishing workflows.