docs-guard

Name: docs-guard
Author: amElnagdy

1.9kinstalls128forks

How to install docs-guard?

amelnagdy/guard-skills/docs-guard

$npx -y skills add amElnagdy/guard-skills --skill docs-guard

Installs into the current project.

Summary

Review generated or changed documentation before it ships — READMEs, API references, docstrings, PHPDoc/JSDoc, changelogs, tutorials, and doc sites. Best used reactively after an agent writes or edits docs, after code changes documented behavior, or before publishing docs. Use wh

Files · 1

View on GitHub

SKILL.md

1	# Docs Guard
2
3	You are reviewing generated or changed documentation before it ships. Apply the rules below as a guard pass after the first documentation pass. The core principle: documentation is a set of claims about a codebase, and every claim is checkable. Your job is to check them.
4
5	These rules exist because AI agents document from memory of how APIs usually look, not from the code in front of them. Published research: half of AI answers to programming questions contain incorrect information, and models produce valid invocations for infrequent APIs barely a third of the time — yet the prose sounds authoritative either way. Readers cannot tell verified docs from hallucinated docs. You can, because you have the source.
6
7	## How to use this skill
8
9	Guard-pass mode (recommended): after documentation or docstrings have been generated or edited, verify every claim against the source and run the self-check before delivery.
10
11	Live mode (explicit): when the user invokes this skill before writing docs, verify before you write — read the actual implementation, then document what it does. Run the self-check before delivery.
12
13	Review mode (the user asks you to review, audit, or fact-check docs): walk [references/review-checklist.md](references/review-checklist.md) against the target docs and produce a findings report with file:line evidence. Do not rewrite in review mode unless asked.
14
15	## Adapt to the project first
16
17	1. Read the project's agent instructions (CLAUDE.md, AGENTS.md) and any docs style guide. Project conventions win on conflict.
18	2. Identify the docs surfaces that must move together: README, reference docs, docstrings, changelog, examples, config samples. A change to one usually owes a change to others (Rule 6).
19	3. Note the documented version policy: which versions does the project support, and where are features version-tagged?
20
21	## The Rules
22
23	### Accuracy — must fix
24
25	1. Every referenced symbol must exist. Every function, method, class, hook, CLI command, flag, endpoint, config key, env var, and file path mentioned in the docs gets verified against the actual source, CLI help output, route table, or schema — by reading it, not recalling it. The verification procedure is in [references/verification.md](references/verification.md). An unverifiable reference does not ship.
26
27	2. Every code sample must work. Imports resolve, APIs exist with the documented signatures (names, argument order, defaults, return shape), and the sample runs outside the author's machine — no hardcoded local paths, no real credentials, no implicit prior state. Sample rules: [references/code-samples.md](references/code-samples.md).
28
29	3. Document the code's actual behavior, not its intended behavior. Read the implementation before describing it. Where code and comments/specs disagree, the code is the truth — and flag the disagreement to the user instead of silently picking a side.
30
31	4. No unverifiable claims. Performance numbers, compatibility matrices, scale limits, and "production-ready" assertions require a source in the repository (benchmark script, CI matrix, changelog entry) or they come out. "Fast" is marketing; "O(n log n), benchmarked in bench/sort.md" is documentation.
32
33	### Versioning and drift
34
35	5. Versions are explicit. Features, flags, and behaviors state the version that introduced them when the project tracks versions. Prerequisites are pinned or ranged, never "latest". Deprecated items say so, with the replacement.
36
37	6. A code change owes a docs change. When editing code whose behavior is documented — rename, signature change, new default, removed flag — update every doc surface that mentions it in the same change. Grep the docs for the old symbol before finishing.
38
39	### Substance — should fix
40
41	7. No filler, no slop. Delete: docstrings that paraphrase the signature ("Gets the user by ID" above `get_user_by_id`), sections that restate their heading, marketing adjectives in technical prose ("powerful", "seamless", "blazingly fast"), and intro padding ("In this section, we will explore…"). A docstring earns its place by adding contracts the sig

People who liked this also viewed

6 picks

Type

docs-guard

1.9kinstalls128forks

View on GitHub

How to install docs-guard?

amelnagdy/guard-skills/docs-guard

$npx -y skills add amElnagdy/guard-skills --skill docs-guard

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Docs Guard
2
3	You are reviewing generated or changed documentation before it ships. Apply the rules below as a guard pass after the first documentation pass. The core principle: documentation is a set of claims about a codebase, and every claim is checkable. Your job is to check them.
4
5	These rules exist because AI agents document from memory of how APIs usually look, not from the code in front of them. Published research: half of AI answers to programming questions contain incorrect information, and models produce valid invocations for infrequent APIs barely a third of the time — yet the prose sounds authoritative either way. Readers cannot tell verified docs from hallucinated docs. You can, because you have the source.
6
7	## How to use this skill
8
9	Guard-pass mode (recommended): after documentation or docstrings have been generated or edited, verify every claim against the source and run the self-check before delivery.
10
11	Live mode (explicit): when the user invokes this skill before writing docs, verify before you write — read the actual implementation, then document what it does. Run the self-check before delivery.
12
13	Review mode (the user asks you to review, audit, or fact-check docs): walk [references/review-checklist.md](references/review-checklist.md) against the target docs and produce a findings report with file:line evidence. Do not rewrite in review mode unless asked.
14
15	## Adapt to the project first
16
17	1. Read the project's agent instructions (CLAUDE.md, AGENTS.md) and any docs style guide. Project conventions win on conflict.
18	2. Identify the docs surfaces that must move together: README, reference docs, docstrings, changelog, examples, config samples. A change to one usually owes a change to others (Rule 6).
19	3. Note the documented version policy: which versions does the project support, and where are features version-tagged?
20
21	## The Rules
22
23	### Accuracy — must fix
24
25	1. Every referenced symbol must exist. Every function, method, class, hook, CLI command, flag, endpoint, config key, env var, and file path mentioned in the docs gets verified against the actual source, CLI help output, route table, or schema — by reading it, not recalling it. The verification procedure is in [references/verification.md](references/verification.md). An unverifiable reference does not ship.
26
27	2. Every code sample must work. Imports resolve, APIs exist with the documented signatures (names, argument order, defaults, return shape), and the sample runs outside the author's machine — no hardcoded local paths, no real credentials, no implicit prior state. Sample rules: [references/code-samples.md](references/code-samples.md).
28
29	3. Document the code's actual behavior, not its intended behavior. Read the implementation before describing it. Where code and comments/specs disagree, the code is the truth — and flag the disagreement to the user instead of silently picking a side.
30
31	4. No unverifiable claims. Performance numbers, compatibility matrices, scale limits, and "production-ready" assertions require a source in the repository (benchmark script, CI matrix, changelog entry) or they come out. "Fast" is marketing; "O(n log n), benchmarked in bench/sort.md" is documentation.
32
33	### Versioning and drift
34
35	5. Versions are explicit. Features, flags, and behaviors state the version that introduced them when the project tracks versions. Prerequisites are pinned or ranged, never "latest". Deprecated items say so, with the replacement.
36
37	6. A code change owes a docs change. When editing code whose behavior is documented — rename, signature change, new default, removed flag — update every doc surface that mentions it in the same change. Grep the docs for the old symbol before finishing.
38
39	### Substance — should fix
40
41	7. No filler, no slop. Delete: docstrings that paraphrase the signature ("Gets the user by ID" above `get_user_by_id`), sections that restate their heading, marketing adjectives in technical prose ("powerful", "seamless", "blazingly fast"), and intro padding ("In this section, we will explore…"). A docstring earns its place by adding contracts the sig

People who liked this also viewed

6 picks

Type