verify-openspec-docs

Fact-checks OpenSpec documentation by re-running commands and validating claims against source code.

3|1|Updated Apr 29, 2026
One-click install
npx skills add https://github.com/firstsun-dev/skills --skill verify-openspec-docs-firstsun-dev
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: verify-openspec-docs
Source: https://github.com/firstsun-dev/skills/tree/main/plugins/spec-driven-development/skills/verify-openspec-docs
Command: npx skills add https://github.com/firstsun-dev/skills --skill verify-openspec-docs-firstsun-dev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Documentation drifts out of sync with the actual CLI behavior, commands, and examples it describes. This Skill catches factual errors in OpenSpec user docs before they reach readers by having an independent reviewer verify every claim against the repository source. ## Core Features & Use Cases - Fresh-context verification: Spawns a general-purpose subagent per section or claim list, so the reviewer has not watched the prose being written and cannot inherit the author's assumptions. - Command re-execution: Re-runs terminal commands from the docs, checks output blocks against real output, and validates example specs with openspec validate. - Style and structure checks: Flags duplicated canonical content, hype adjectives, vague claims, and violations of the docs tree README invariants and house writing rules. - Use Case: After drafting a new OpenSpec docs page, ask for a verification pass on a specific section; the reviewer reports findings ranked by severity with quoted lines, one-line fixes, and exactly how each fact was verified. ## Quick Start Ask the agent to verify the 'Getting Started' section of the OpenSpec docs page against the repository source.

Frequently Asked Questions about verify-openspec-docs

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

FAQPage Schema
How do I fact-check OpenSpec documentation against the actual CLI?▼

Invoke this skill with a target page, section, or list of changed claims. It spawns a fresh-context subagent that re-runs documented commands, compares output blocks to real output, and checks names against src/ and the CLI's --help.

How to verify code examples in technical documentation?▼

The reviewer runs read-only commands directly and mutating commands only in a scratch directory. Example specs and changes are validated with openspec validate when the example exists on disk, and every verified fact cites the command or file used.

Does this skill run automatically during docs drafting?▼

No. It is manually triggered only when the user asks to verify, fact-check, or accuracy-check documentation. Drafting is owned by the write-openspec-docs skill, and verification should not be invoked from inside a drafting session unless requested.

Can the verification skill also fix the documentation errors it finds?▼

By default it only reports findings ranked by severity with quoted lines and one-line fixes. It applies fixes only when the user requests a verify-and-fix run or approves the findings, and factual fixes trigger a scoped re-verification.

What are the limitations of subagent-based docs verification?▼

Subagents do not inherit skills, so all context must be passed by absolute path in the prompt. Chat-surface commands like /opsx:propose cannot run in a shell and are verified against skill sources instead, and two non-converging passes stop the loop.