OneLinersCommand workbench
AI
Back to skills
SKILL.md

Documentation maintenance skill

Updates technical documentation while preserving verified commands and source boundaries.

Revision
2
Verified
2026-10-20
Save or explore
Save to collectionCreate a collection in the sidebar first.

Compatibility and paths

Codexskills/docs-maintainer/SKILL.md
Claude Code.claude/skills/docs-maintainer/SKILL.md
VS Code.github/skills/docs-maintainer/SKILL.md

Trust 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.

Source evidence

Agent Skills specificationofficialDiátaxis — task-oriented how-to guidesofficial