reviewing-user-guide

Reviews end-user product guides against a 12-condition usability and accuracy bar and emits an approve or revise verdict.

1|1|Updated May 24, 2026
One-click install
npx skills add https://github.com/bm629/agent-skills --skill reviewing-user-guide-bm629
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: reviewing-user-guide
Source: https://github.com/bm629/agent-skills/tree/main/skills/reviewing-user-guide
Command: npx skills add https://github.com/bm629/agent-skills --skill reviewing-user-guide-bm629

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? End-user guides often ship with coverage holes, mistyped documentation modes, inaccurate steps, or jargon that blocks non-technical readers, and self-review by the author rarely catches these gaps. This Skill acts as an independent acceptance gate that judges a finished guide against a fixed 12-condition bar and returns a machine-parseable verdict with actionable findings. ## Core Features & Use Cases - 12-condition usability and accuracy checklist: Judges goal coverage, Diataxis mode typing, reference completeness, step accuracy with exact UI labels, procedure mechanics, troubleshooting, plain language, accessibility, and findability. - Machine-parseable verdict output: Emits exactly VERDICT: approve or VERDICT: revise plus findings that name the failed condition, location, and concrete fix. - Amend-mode review: Judges versioned deltas on published guides with a staleness sweep across all modes when handed an existing guide plus changed upstreams. - Use Case: After authoring a user guide from a feature-spec and user-flows, run this Skill as the review gate; it flags a missing how-to for the "Reset password" goal and an unexplained acronym, returning findings the author resolves in one revision pass. ## Quick Start Use reviewing-user-guide on the finished end-user guide at docs/guide.md and give me the verdict with actionable findings.

Frequently Asked Questions about reviewing-user-guide

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review an end-user guide before publishing it?

Hand the finished guide to this Skill along with its upstream documents such as the feature-spec or user-flows. It judges the guide against a 12-condition usability and accuracy bar and returns a VERDICT: approve or VERDICT: revise line with actionable findings for each gap.

What does the 12-condition user guide review checklist cover?

The checklist covers goal coverage with one how-to per goal, correct Diataxis mode typing, end-user reference completeness, step accuracy with exact UI labels, procedure mechanics, symptom-keyed troubleshooting, audience usability, surfaced assumptions, amend sweeps, plain language, accessibility, and findability.

Can this Skill review a developer guide or API reference?

No, it is scoped to end-user product guides for typically non-technical readers. Developer adoption guides, HTTP API endpoint catalogs, and engineering design documents are explicitly out of scope and should be handled by their own dedicated review skills.

Does the review skill rewrite or fix the guide it reviews?

No, it only judges and returns findings; it never authors, fixes, or rewrites content. Each revise finding names the failed condition, the exact location, and a concrete fix so the producer can resolve it in one revision pass.

When does the guide review return revise instead of approve?

It returns revise only on a real, named gap that blocks or misleads a user, such as a goal with no how-to, a fabricated step, or unexplained jargon. Proportionally sized thin guides that meet every applicable condition are approved, avoiding false-revise.