docs-review
Installation
SKILL.md
Review documentation changes for correctness, style, and structure.
Primary style reference: .agents/references/style-guide.md — read this before reviewing. It contains the canonical rules for MDX syntax, frontmatter, writing style, formatting, links, code blocks, and admonitions. The full style guide lives at src/content/docs/style-guide/ if you need to go deeper on any topic.
When to Suggest vs. When to Edit
Decision logic
- Explicit instruction wins. If the user says "suggest", "only make suggestions", or "do not make changes" — post suggestions via
ghCLI, never push commits. If they say "fix", "address this", or "update" — edit files directly and commit. - Different actor = suggest. If the person invoking the review is not the PR author (and no explicit fix instruction was given), post suggestions so the author retains control.
- Same actor or ambiguous = fix by default. When the invoker is the PR author (or it is unclear), default to editing files directly. MDX syntax errors, broken code, invalid frontmatter, wrong component usage, and other obvious errors should always be fixed, not suggested.