Require every documentation change to pass two gates: (1) strict doc-schema conformance, and (2) factual/behavioral accuracy against the implementation and shipped artifacts.
Gate 1: Conformance
Follow the required doc template/section structure (e.g., include standard When to Use / Prerequisites sections).
Ensure skill frontmatter/metadata and descriptions meet hard limits (e.g., description must be exactly one short sentence per the team’s agent-skill rules).
Keep platform lists accurate (only claim windows if commands/guidance are cross-platform).
Gate 2: Accuracy & consistency
Commands/steps must match what the product actually does (e.g., don’t suggest hf if prerequisites still install huggingface-cli; don’t present CLI-only commands like /reload as gateway/user-session steps).
Align environment variables, ports, and paths with the shipped behavior (e.g., if the server runs on 8001, link users to 8001 and only mention frontend dashboards when static assets exist).
Avoid overstating templating/rendering behavior (state only what is actually rendered; if nested keys aren’t rendered, document that limitation).
Reflect real tool/capability behavior (capabilities in docs must match implementation dispatch and limitations).
Ensure generated docs reflect the actual source files (if a bundle/source folder is missing, the derived site page must not advertise that installable skill).
Include required safety/approval steps for user-data writes (don’t document write commands without the explicit confirmation rule).
Example checklist (apply to every PR):
Does the doc (or skill SKILL.md) meet all formatting/limit rules (one-sentence/≤60-char description, required sections, required metadata)?
Do all commands match what is installed/configured in the same patch?
Are any steps tool-scope-specific (CLI vs gateway) and documented accordingly?
Are ports/URLs/paths consistent with the actual runtime and build artifacts?
Are templating/rendering claims precise (including nested objects)?
Do capability/mode descriptions match the actual implementation behavior?
Are install/discovery instructions aligned with where the runtime actually scans?
If any item fails, the doc must be corrected (or the claim narrowed) before merge.