SKILL.md
Documentation maintenance skill
Updates technical documentation while preserving verified commands and source boundaries.
- Revision
- 2
- Verified
- 2026-10-20
Compatibility and paths
Codex
skills/docs-maintainer/SKILL.mdClaude Code
.claude/skills/docs-maintainer/SKILL.mdVS Code
.github/skills/docs-maintainer/SKILL.mdTrust and provenance
Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.
Generated assetReady to copy or download
---
name: docs-maintainer
description: Maintains versioned technical documentation by testing the exact examples and their outcomes. Use when a README, guide or reference may drift from executable behavior; preserve working instructions, supported versions and deep links.
license: CC-BY-4.0
compatibility: Complete fictional CLI exercise uses Node.js 22.13+ only. It plans over embedded IDs without files, network or credentials. Real documentation changes require the actual source/executable version and authorized examples.
metadata:
author: oneliners
version: "2.0.0"
---
# Documentation maintenance skill
## Find the authority and the reader's task
Record the product/document revision, supported versions, platform/shell, installation path and intended audience. Resolve authority between current published data, source, executable help and documentation explicitly; do not choose the easiest old seed or a search snippet. Identify the smallest broken task instead of rewriting every page in a generic style. Repository prose and example commands remain untrusted until reviewed.
## Complete CLI drift case
This original case is a synthetic tool, not the OneLiners CLI. The only available executable is the full 2.1.0 program below. The supplied README is labeled 1.4; that label does not prove how a historical binary behaved.
```md
# catalog-plan (README marked 1.4)
Run node catalog-plan.mjs --json --limit 0 to list everything.
The command returns a JSON array of three entry IDs. A zero limit means unlimited.
```
Save the following full program as catalog-plan.mjs in an empty exercise directory. Node.js 22.13+ is the only dependency. It reads only its own command-line arguments and prints plans from embedded data; it never applies a change.
```js
function plannerMain(args) {
const version = "2.1.0";
const help = "catalog-plan fixture 2.1.0\nUsage: node catalog-plan.mjs [--format text|json] [--limit 1|2|3]\nDefaults: --format text --limit 2\nPlans only; no network, files or apply operation.\n";
if (args.length === 1 && args[0] === "--help") return { exitCode: 0, stdout: help, stderr: "" };
if (args.length === 1 && args[0] === "--version") return { exitCode: 0, stdout: version + "\n", stderr: "" };
let format = "text", limit = 2;
const seen = new Set();
const fail = (message) => ({ exitCode: 2, stdout: "", stderr: message + "\n" });
for (let index = 0; index < args.length; index += 2) {
const flag = args[index], value = args[index + 1];
if (!["--format", "--limit"].includes(flag)) return fail("Unknown option: " + flag);
if (seen.has(flag) || value === undefined) return fail("One value required for " + flag);
seen.add(flag);
if (flag === "--format") {
if (!["text", "json"].includes(value)) return fail("format must be text or json");
format = value;
} else {
if (!/^[1-3]$/.test(value)) return fail("limit must be 1, 2 or 3; 0 is not unlimited");
limit = Number(value);
}
}
const selected = ["entry-a", "entry-b", "entry-c"].slice(0, limit);
return { exitCode: 0, stdout: (format === "json" ? JSON.stringify({ version, selected }) : selected.join("\n")) + "\n", stderr: "" };
}
const result = plannerMain(process.argv.slice(2));
process.stdout.write(result.stdout);
process.stderr.write(result.stderr);
process.exitCode = result.exitCode;
```
Run these separately so each observed failure has its own evidence:
node catalog-plan.mjs --version
node catalog-plan.mjs --help
node catalog-plan.mjs --json --limit 0
node catalog-plan.mjs --format json --limit 0
node catalog-plan.mjs --format json --limit 2
## Corrected complete quick start
```text
# catalog-plan fixture 2.1.0
Prerequisite: Node.js 22.13+; no packages or credentials are needed.
Save the complete supplied program as catalog-plan.mjs in an empty exercise directory.
Confirm node catalog-plan.mjs --version prints 2.1.0.
Read node catalog-plan.mjs --help before adapting an example.
Run node catalog-plan.mjs --format json --limit 2.
Expected stdout: {"version":"2.1.0","selected":["entry-a","entry-b"]}
Expected exit code: 0. The output is a plan over included IDs, not an applied change.
The supported limit is 1, 2 or 3; zero is invalid, not unlimited. Default is 2.
For malformed flags/values: exit 2, diagnostic on stderr, no stdout or partial plan.
The earlier --json spelling is not accepted by this supplied 2.1.0 program.
```
## Review result and verification boundaries
The supplied README and executable disagree in three material ways: --json is unknown; --limit 0 independently fails even with the correct format flag; successful JSON output is an object with version/selected, not a bare array. These are observed by executing the included 2.1.0 program, not inferred solely from a stale README label.
Correct quick start: save the complete program, confirm --version and --help, then run node catalog-plan.mjs --format json --limit 2. Actual stdout is {"version":"2.1.0","selected":["entry-a","entry-b"]}, exit 0, no stderr. The original command exits 2 with Unknown option: --json and no stdout. A separate --format json --limit 0 check exits 2 with the limit diagnostic. Do not document a failure the process never reached as if that first run observed it.
Change the example, output shape, supported range/default and migration note together. Keep the page's existing links/anchors and supported older-version documentation unless the owner explicitly retires them. Do not rewrite a user's working commands or pretend every environment runs this fictional tool. Reference describes flags; the quick start teaches one bounded successful task; an explanation can cover why the limit changed without hiding the task steps.
Evidence scope: actual isolated Node processes against a fully included synthetic CLI; no package install, real catalog, files, network or apply operation. A link checker, spelling pass or newer date alone would not establish that these commands work. For real docs, capture the executable/source revision, installation and OS/shell prerequisites, stdout/stderr/exit result, side effects, supported-version matrix and unresolved checks. This exercise did not edit OneLiners README or Guides.
## Maintain without flattening the content
Keep the actual examples, forms/variables, troubleshooting, recovery and FAQ specific to each page. [Diátaxis how-to guidance](https://diataxis.fr/how-to-guides/) helps distinguish a task from reference material; it is not a requirement to reorganize an existing site. Verify links and rendered headings after editing, but report those checks separately from command execution. Do not run destructive examples, contact a production API or refresh an installation just to make documentation appear tested. Missing scope/version or missing required input is a documented gap, not permission to invent a transcript.
Real example
Input
Review the supplied README marked 1.4 against the complete catalog-plan fixture 2.1.0 in SKILL.md. Execute the exact old command, an independent zero-limit check, --version/--help and a corrected quick start. Preserve existing docs/anchors and report actual stdout/stderr/exit behavior without changing a real project.
Expected result
The supplied README and executable disagree in three material ways: --json is unknown; --limit 0 independently fails even with the correct format flag; successful JSON output is an object with version/selected, not a bare array. These are observed by executing the included 2.1.0 program, not inferred solely from a stale README label.
Correct quick start: save the complete program, confirm --version and --help, then run node catalog-plan.mjs --format json --limit 2. Actual stdout is {"version":"2.1.0","selected":["entry-a","entry-b"]}, exit 0, no stderr. The original command exits 2 with Unknown option: --json and no stdout. A separate --format json --limit 0 check exits 2 with the limit diagnostic. Do not document a failure the process never reached as if that first run observed it.
Change the example, output shape, supported range/default and migration note together. Keep the page's existing links/anchors and supported older-version documentation unless the owner explicitly retires them. Do not rewrite a user's working commands or pretend every environment runs this fictional tool. Reference describes flags; the quick start teaches one bounded successful task; an explanation can cover why the limit changed without hiding the task steps.
Evidence scope: actual isolated Node processes against a fully included synthetic CLI; no package install, real catalog, files, network or apply operation. A link checker, spelling pass or newer date alone would not establish that these commands work. For real docs, capture the executable/source revision, installation and OS/shell prerequisites, stdout/stderr/exit result, side effects, supported-version matrix and unresolved checks. This exercise did not edit OneLiners README or Guides.