Skip to content
OpenSmartRoute
Skillv1.0.0

doc-code-consistency-check

Before "fixing" a README, verify the actual code behavior — don't trust either in isolation.

by chen3feng(0) 0 installs
Free
Sign in to install

Free account. Installing gives you the manifest plus copy-paste snippets.

See reviews

About

Imported from chen3feng/agent-skills (skills/doc-code-consistency-check/SKILL.md). Install upstream with npx skills add chen3feng/agent-skills --skill doc-code-consistency-check. Copyright stays with the author.

Doc–code consistency check

When to use

The user asks you to review or tidy up documentation (README, tutorials, help text) for a project whose code you can also read. Especially when they say "the docs look wrong" or "check whether the docs match the code".

Problem

Docs drift. Common observed drifts in real repos:

  • A CLI flag was renamed in code but the README still shows the old one.
  • A function described as "returns X" actually returns X-or-None.
  • A "supported versions" list that nobody updated after a bump.
  • Chinese and English versions of the same doc disagreeing with each other (and both possibly disagreeing with the code).

If you edit the docs to be self-consistent without re-reading the code, you often cement the wrong behavior.

Solution

Before changing a single word of a doc, do this loop:

  1. List the concrete claims the doc makes — flags, options, return types, default values, error behavior, supported platforms.
  2. Grep the code for each claim. Cross-reference against tests where possible.
  3. Categorize each discrepancy:
    • (a) Doc wrong, code right → update the doc (this is most common).
    • (b) Code wrong, doc right → ask the user; do not silently "fix" the doc.
    • (c) Both wrong → surface it; don't guess.
  4. For multilingual docs (README.md + README-zh.md), diff them after step 3 so both stay in sync.
  5. Write a short changelog of what you changed in the doc and why, based on the code evidence. This lets the user audit quickly.

Example

Symptom: README says _check_python accepts a version string like "3.11".

Bad fix: silently change the README to "3.11.0" because that's what "looks right".

Good fix:

grep -n "_check_python" -r src/
# read the function, note it calls shutil.which("python3") and parses
# sys.version_info, no version string is accepted

Then update the README to describe what the code actually does, and mention the mismatch in the PR description so the maintainer can decide if the code should change instead.

Pitfalls

  • Don't fix both files in the same PR without flagging it. Separate "doc matches code" from "change behavior" into different commits / PRs.
  • Tests are a better source of truth than the code's docstring.
  • Translated docs often lag the primary one; when in doubt, treat the language the maintainer writes most often as source-of-truth.

See also

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml
targets:
  - https://api.opensmartroute.ai/api/v1/registry/chen3feng-agent-skills-doc-code-consistency-check/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

chen3feng-agent-skills-doc-code-consistency-check.ocm.jsonjson
{
  "ocm": "1",
  "id": "chen3feng-agent-skills-doc-code-consistency-check",
  "kind": "skill",
  "name": "doc-code-consistency-check",
  "description": "Before \"fixing\" a README, verify the actual code behavior — don't trust either in isolation.",
  "publisher": "chen3feng",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "docs",
      "review",
      "workflow",
      "github"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Before \"fixing\" a README, verify the actual code behavior — don't trust either in isolation."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "github",
      "repository": "https://github.com/chen3feng/agent-skills",
      "path": "skills/doc-code-consistency-check/SKILL.md",
      "ref": "9713f8557226be7b1c2bb1194a9a6e8e6a76d9b4",
      "url": "https://github.com/chen3feng/agent-skills/blob/9713f8557226be7b1c2bb1194a9a6e8e6a76d9b4/skills/doc-code-consistency-check/SKILL.md",
      "key": "chen3feng/agent-skills/skills/doc-code-consistency-check/SKILL.md"
    }
  },
  "instructions": "# Doc–code consistency check\n\n## When to use\n\nThe user asks you to review or tidy up documentation (README,\ntutorials, help text) for a project whose code you can also read.\nEspecially when they say \"the docs look wrong\" or \"check whether the\ndocs match the code\".\n\n## Problem\n\nDocs drift. Common observed drifts in real repos:\n\n- A CLI flag was renamed in code but the README still shows the old\n  one.\n- A function described as \"returns X\" actually returns X-or-None.\n- A \"supported versions\" list that nobody updated after a bump.\n- Chinese and English versions of the same doc disagreeing with ea",
  "cost": {
    "context_tokens": 642
  }
}

Fetch it by URL: GET /api/v1/registry/chen3feng-agent-skills-doc-code-consistency-check/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.