docs-style

majiayu000 的头像作者 majiayu000

自动应用于起草或修订文档时,以强制执行存储库语气、清晰度和导航模式。

📖 中文导读:自动应用于起草或修订文档时,以强制执行存储库语气、清晰度和导航模式。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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.