docs-style
Automatically applies when drafting or revising documentation to enforce repository voice, clarity, and navigation patterns.
When & Why to Use This Skill
This Claude skill automates the enforcement of documentation standards, ensuring consistent voice, clarity, and navigation across technical repositories. It streamlines the writing process for READMEs, tutorials, and design docs by applying predefined style guides and quality checklists automatically, significantly improving documentation readability and maintainability.
Use Cases
- Standardizing the tone and voice across all repository documentation to ensure a professional and cohesive project identity.
- Automatically auditing and revising technical tutorials to follow specific navigation patterns and formatting rules for better user experience.
- Enforcing active voice and concise sentence structures in complex design documents and ADRs to improve clarity for stakeholders.
- Validating documentation quality against a checklist to ensure audience identification, clear outcomes, and consistent terminology across the workspace.
| name | docs-style |
|---|---|
| description | Automatically applies when drafting or revising documentation to enforce repository voice, clarity, and navigation patterns. |
| category | documentation |
Documentation Style Guide
Trigger Keywords: documentation, doc update, README, guide, tutorial, changelog, ADR, design doc, style, tone, voice, copy edit
Agent Integration: Used by spec-writer, technical-writer, and requirements-analyst when delivering reader-facing content.
Voice and Clarity
- Prefer concise, direct sentences; remove filler and marketing language.
- Use active voice and parallel sentence structures.
- Lead with outcomes, then supporting details.
- Keep language project-agnostic so the plugin works in any Python project.
Structure and Navigation
- Start with a short purpose/summary before detailed sections.
- Use consistent heading levels and ordered sections; avoid nested lists where possible.
- Include quick-scannable bullets and tables for comparisons or options.
- Add cross-references to related specs, tasks, and reference docs.
Formatting Patterns
- Use fenced code blocks with language tags for examples.
- Keep line wrapping consistent; avoid trailing whitespace.
- Use bold keywords sparingly for emphasis; prefer headings + bullets.
- For checklists, use ordered steps when sequence matters, unordered when it does not.
Quality Checklist
- ✅ Audience and scope identified at the top.
- ✅ Clear outcomes and verification steps included.
- ✅ Terminology consistent across the document.
- ✅ Links/paths are workspace-relative (no IDE/URL schemes).
- ❌ Avoid passive voice that hides ownership or action.
- ❌ Avoid giant paragraphs; break into digestible chunks.