# Documentation Style

> Enforces project documentation style guide compliance for tone, voice, terminology, punctuation, and formatting. Use when checking documentation style or validating MyST/reST syntax. Cites specific style guide violations.

- Skill: `canonical/documentation-style` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add canonical/documentation-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/canonical/documentation-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: canonical (https://skillmd.com/u/canonical)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/canonical/documentation-style

---


# Documentation Style Review

## Scope

Style conformance only: tone, voice, terminology, punctuation, Oxford comma, active versus passive voice, prohibited phrases, and formatting conventions.

## Inputs

- Documentation file(s) under review.
- Normative style asset: `references/doc-style-guide.md`.
- Syntax-specific style guides (fetched at runtime):
  - MyST: `https://raw.githubusercontent.com/canonical/sphinx-stack-docs/refs/heads/main/docs/reference/myst-syntax.md`
  - reST: `https://raw.githubusercontent.com/canonical/sphinx-stack-docs/refs/heads/main/docs/reference/rst-syntax.rst`

## Actions

1. **Load style guides**: Read `references/doc-style-guide.md`.
   Fetch the syntax-specific guide matching the file type (MyST for `.md`, reST for `.rst`).

2. **Syntax compliance**: Check headings, lists, code blocks, inline literals, and directives against the applicable syntax guide.
   Treat every instruction in the guide as mandatory; do not rely on a subset of rules.

3. **Full style guide compliance**: Read and apply all rules defined in `references/doc-style-guide.md`.
   Treat every instruction in the guide as mandatory; do not rely on a subset of rules.

4. **Style guide citation**: For every violation found, locate and quote the specific passage in `references/doc-style-guide.md` or the syntax-specific guide that supports the finding.

5. **Fallback behavior**: If syntax guides cannot be fetched (offline or network blocked), continue the review using `references/doc-style-guide.md` and the syntax patterns already present in the documentation set.
   
   If `references/doc-style-guide.md` is unavailable, STOP the review and report that the style guide cannot be accessed.

6. **Verification**:

   Confirm the style review completed:

   - Style guides loaded (doc-style-guide.md and syntax-specific guide if available)
   - Syntax compliance checked against applicable guide
   - Style guide compliance checked against all rules in doc-style-guide.md
   - All violations cited with quoted passages from style guides

   State the completion status:
   - `✓ Style review complete: [N] violations found`
   - OR `✓ Style review complete: No violations found`

## Constraints

- Quote style guides when making style suggestions.
- Do not suggest style or markup changes without quoting the style guides.

## Output

A list of style violations, each accompanied by:

- The specific passage quoted from the style guide or syntax reference.
- The observation or suggested change.