# Docs Style

> Automatically applies when drafting or revising documentation to enforce repository voice, clarity, and navigation patterns.

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

---


# 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.