# Docs Review

Review documentation changes for compliance with the Metabase writing style guide.

- Repository: https://github.com/foryourhealth111-pixel/Vibe-Skills (3789 stars)
- Category: Writing
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add foryourhealth111-pixel/Vibe-Skills --skill docs-review -g -a claude-code -y`
Codex: `npx skills add foryourhealth111-pixel/Vibe-Skills --skill docs-review -g -a codex -y`
Cursor: `npx skills add foryourhealth111-pixel/Vibe-Skills --skill docs-review -g -a cursor -y`
Gemini CLI: `npx skills add foryourhealth111-pixel/Vibe-Skills --skill docs-review -g -a gemini-cli -y`

## Description

Review documentation changes for compliance with the Metabase writing style guide. Use when reviewing pull requests, files, or diffs containing documentation markdown files.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Documentation Review Skill

@./../_shared/metabase-style-guide.md

## Review mode detection

**IMPORTANT: Before starting the review, determine which mode to use:**

1. **PR review mode**: If the `mcp__github__create_pending_pull_request_review` tool is available, you are reviewing a GitHub PR
   - Use the pending review workflow to post all issues as one cohesive review
   - Follow the workflow steps in "PR review mode format" below

2. **Local review mode**: If the MCP tool is NOT available, output issues in the conversation
   - Format all issues in a numbered markdown list (as described in "Feedback format" below)

## Review process

1. **Detect review mode** - Check if `mcp__github__create_pending_pull_request_review` is available
2. Read the changes through once to understand intent
3. Check all issues that violate style guide or significantly impact readability
4. Only flag issues worth mentioning - if it won't make a material difference to the reader, skip it
5. **REQUIRED: Number ALL feedback sequentially** - Start from Issue 1 and increment for each issue found

## Review checklist

Run through the diff looking for these issues:

**Tone and voice:**

- [ ] Formal/corporate language ("utilize" not "use", "offerings", etc.)
- [ ] "Users" instead of "people" or "companies"
- [ ] Excessive exclamation points or overly peppy tone
- [ ] Telling readers something is cool instead of showing them

**Structure and clarity:**

- [ ] Important information buried instead of leading
- [ ] Verbose text that adds little value
- [ ] Paragraphs without clear purpose
- [ ] Vague headings that don't convey the point
- [ ] Instructions explain "why" before telling "what to do"
- [ ] Tasks described as "easy" or "simple"

**Links and references:**

- [ ] Linking the word "here" instead of descriptive text
- [ ] Links in headings (unless entire heading is a link)

**Formatting:**

- [ ] Ampersands as "and" substitute (except proper nouns)
- [ ] Inconsistent list formatting

The rest: https://github.com/foryourhealth111-pixel/Vibe-Skills/blob/HEAD/bundled/skills/docs-review/SKILL.md