Docs Review
Run Metabase-style documentation reviews on markdown diffs or PRs so product docs stay consistent before merge.
Overview
Docs Review is an agent skill most often used in Build → docs (also Ship → review) that checks documentation markdown changes against the Metabase writing style guide.
Install
npx skills add https://github.com/metabase/metabase --skill docs-reviewWhat is this skill?
- Auto-detects GitHub PR review mode when GitHub MCP pending review tools are available
- Falls back to numbered local review issues when MCP is unavailable
- Sequential Issue numbering required across all feedback items
- Checklist covers tone, readability, and style-guide violations worth flagging
- Loads shared metabase-style-guide.md referenced from skill frontmatter
- All feedback must be numbered sequentially starting from Issue 1
Adoption & trust: 836 installs on skills.sh; 47.6k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your docs PRs drift into corporate tone and style-guide violations because nobody applies the same editorial rules on every diff.
Who is it for?
Metabase contributors or teams mirroring the Metabase style guide who review markdown docs in PRs or local branches.
Skip if: Repos without the shared style guide asset, pure code-only PRs, or teams that want automated lint fixes instead of editorial review.
When should I use this skill?
Reviewing pull requests, files, or diffs containing documentation markdown files for Metabase style guide compliance.
What do I get? / Deliverables
You get sequentially numbered, style-guide-aligned review comments—posted as one GitHub pending review or a local issue list—ready for authors to fix before merge.
- Numbered documentation review issues (GitHub pending review or local markdown list)
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Authoring and maintaining product docs is canonically shelved under Build → docs even when the skill runs during PR review in Ship. The skill enforces the shared Metabase writing style guide on documentation markdown, not application code review.
Where it fits
Before merging a new connector guide, run docs-review on the markdown diff to catch formal language and guide violations.
On a GitHub docs PR, open a pending review and let the skill post all numbered style issues as one cohesive comment thread.
After a doc incident confused customers, re-review patched help pages locally without MCP to standardize tone on hotfix branches.
How it compares
Use this editorial compliance checker instead of a generic linter when voice and reader clarity matter as much as spelling.
Common Questions / FAQ
Who is docs-review for?
Documentation maintainers and agents reviewing Metabase-style markdown in GitHub PRs or local diffs who need consistent style-guide enforcement.
When should I use docs-review?
Use it in Build → docs while drafting or updating guides; also in Ship → review when a PR changes documentation markdown and you want one batched GitHub review or numbered local issues.
Is docs-review safe to install?
It uses read and search tools on your repo; confirm allowed-tools scope in your agent setup and review the Security Audits panel on this Prism page.
SKILL.md
READMESKILL.md - Docs Review
# 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 **Code and examples:** - [ ] Code examples that don't work or would error - [ ] Commands not in execution order - [ ] Full-width screenshots instead of scoped UI elements - [ ] Excessive or unnecessary images **Sentence construction:** - [ ] Overuse of pronouns when introducing new terms ## Quick scan table | Pattern | Issue | | ----------------------------- | --------------------------------------------- | | we can do X, our feature | Should be "Metabase" or "it" | | click here, read more here | Need descriptive link text | | easy, simple, just | Remove condescending qualifiers | | users | Should be "people" or "companies" if possible | ## Feedback format **MANDATORY REQUIREMENT: Every single issue MUST be numbered sequentially starting from Issue 1.** This numbered format is NON-NEGOTIABLE. It allows users to efficiently reference specific issues (e.g., "fix issues 1, 3, and 5") and track which feedback has been addressed. ### Local review mode format When outputting issues in the conversation (local mode), use this format: ```markdown ## Issues **Issue 1: [Brief title]** Line X: Succinct description of the issue [code or example] Suggested fix or succinct explanation **Issue 2: [Brief title]** Line Y: Description of the issue Suggested fix or explanation **Issue 3: [Brief title]** ... ``` **Examples:** > **Issue 1: Formal tone** > Line 15: This could be more conversational. Consider: "You can't..." instead of "You cannot..." > **Issue 2: Vague heading** > Line 8: The heading could be more specific. Try stating the point directly: "Run migrations bef