documentation_skill

Overview

This skill reviews documentation changes in pull requests, assessing ease of understanding and technical correctness. It produces a structured report with categorized findings, severity levels, and actionable recommendations tailored for maintainers and contributors. Use it to surface blocking issues, usability problems, and quick improvements before merging.

How this skill works

The skill inspects the PR diff to identify documentation files (Markdown, RST, AsciiDoc, prose-heavy TXT, YAML front matter, and substantially changed inline docs). It evaluates changed lines within each file across four dimensions—Clarity, Technical Accuracy, Structure, and Grammar/Style—and assigns severity (Critical, Warning, Suggestion). The output is a concise, reproducible review that references files and line ranges and ends with an explicit verdict.

When to use it

• When a pull request modifies user-facing guides, API docs, or tutorials.
• When you need a quick check of docs for technical correctness before merging.
• When reviewing PRs that add or update examples, commands, or code snippets.
• When maintainers want a structured report of writing, formatting, and accuracy issues.
• When contributors request feedback on clarity or onboarding flow in docs.

Best practices

• Run the review focused on the PR diff and call out only changed lines unless surrounding context affects meaning.
• Flag uncertain technical claims as needing verification rather than asserting errors.
• Quote exact problematic text and provide concrete replacement suggestions.
• Group related issues to avoid repeating the same pattern across findings.
• Prioritize Critical items that can cause build/runtime errors or security problems.

Example use cases

• A contributor updates the README with new installation steps—validate commands and OS-specific notes.
• A docs PR changes an API example—check parameter names, return values, and error handling.
• A tutorial rewrite reorganizes sections—verify flow, prerequisites, and heading hierarchy.
• Minor copy edits across multiple files—find and unify terminology and style inconsistencies.
• A change adds YAML front matter for a docs site—ensure metadata and links are correct.