SkillAgentSearch skills...

docs-cleaner

Consolidates redundant documentation while preserving all valuable content; keeps a doc set truthful after things change. Modes: (1) POST-CHANGE GOVERNANCE — when code, scripts, config, env vars, ports, paths, deployment, auth, tests, or a documented procedure changed; also "which docs are now wrong…

Install / Use

npx skills add daymade/claude-code-skills --skill docs-cleaner

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

84/100

Category

Operations

Supported Platforms

Universal

Our assessment of docs-cleaner

docs-cleaner scores 84/100 on our quality scale, 569th of 745 Operations skills we index.

Its SKILL.md is 48 KB long, well organised into 26 sections with 7 code examples: long enough that it reads more like full documentation than a focused instruction file, which agents can find harder to follow.

With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
21/30
Structure
20/20
Description
15/15
Adoption
13/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so docs-cleaner is actively maintained.
  • Our last check on 2026-11-06 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-03. Automated pattern scan on 2026-10-03. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

docs-cleaner compared with similar skills

All 4 of these similar skills score higher than docs-cleaner; compare them before choosing.

SkillScoreStarsUpdatedFormat
docs-cleaner (this skill)by daymade841.4k53d agoSKILL.md
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md
pptxby anthropics100177.9k55d agoSKILL.md
designby nextlevelbuilder100149.0k6d agoSKILL.md

Frequently asked questions

How do I install docs-cleaner?
Run npx skills add daymade/claude-code-skills --skill docs-cleaner. The install tabs above show the steps for each supported agent.
Which AI agents does docs-cleaner work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is docs-cleaner safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is docs-cleaner still maintained?
The repository was last updated about 2 months ago, so docs-cleaner is actively maintained.

name: docs-cleaner disable-model-invocation: true description: >- Consolidates redundant documentation while preserving all valuable content; keeps a doc set truthful after things change. Modes: (1) POST-CHANGE GOVERNANCE — when code, scripts, config, env vars, ports, paths, deployment, auth, tests, or a documented procedure changed; also "which docs are now wrong", "check docs for inconsistencies", "过时的命令/路径", "文档同步". Use it even when the user mentions only the change and never the docs — updating them is part of the change, not optional cleanup. (2) CONSOLIDATION — "clean up docs", "documentation bloat", "reduce documentation sprawl", "consolidate documentation", "too many doc files", "merge redundant docs", "merge these docs", "文档太多/太乱", multiple files covering the same topic, or documentation exceeding 500 lines across multiple files on similar topics. Finds stale copies of a fact changed in only one place, values that should never have been persisted (counts, totals, "N items", restated summaries), rival definitions that drift apart, and orphaned cross-references.

Docs Cleaner

Documentation goes wrong in recurring ways, and they need different work.

It rots. Something changed — a port, a path, a procedure, a decision — and the docs still describe the old world. The field's name for this is documentation rot or version drift: artifacts fall out of sync one at a time until people stop trusting the set.

It sprawls. The same topic accumulates three files, each partly right, none authoritative.

They trace to one root cause: a fact was written down in more places than it was defined. Everything below follows from fixing that.

Core principle (governs both modes)

Critical evaluation before deletion. Never blindly delete. Analyze each section's unique value before proposing removal. The goal is reduction without information loss.

This governs every deletion-shaped action in this skill, not just consolidation: archiving a document, dropping a derived value, and removing a cross-reference are all deletions and all owe the same analysis first. "It looked redundant" is not that analysis.

Which mode are you in?

| The user said / the situation | Mode | |---|---| | "I changed X" / a diff exists / a procedure was updated | 1 — Post-change governance | | "which docs are now wrong", "check for stale commands/paths" | 1 — Post-change governance | | "clean up the docs", "too many files on this", "merge these" | 2 — Consolidation | | A topic is spread over several files with no clear owner | 2 — Consolidation |

They share the Drift Test below. When both apply, run Mode 1 first: consolidating docs that are also factually stale just produces one confidently wrong document.

A note on CLAUDE.md / AGENTS.md: both modes apply to them like any other document — govern them after a change, consolidate them when they duplicate each other. The one job that belongs elsewhere is restructuring a single oversized one — pushing low-frequency detail down into references while keeping the top level lean. That is what daymade-claude-code's claude-md-progressive-disclosurer skill is built for; prefer it when the problem is size and layering rather than truth or duplication. If it is not available, Mode 2 still handles the file — you just do the value analysis by hand.


The Drift Test (the core of both modes)

Before writing any value into a document — and when deciding whether an existing one earns its place — ask these three questions in order, and stop at the first hit:

1. Can this be computed from details already recorded here or in the authoritative source? → It is a derived value. Do not write it. Compute it when someone asks. Examples: a count ("6 sections", "N groups covered"), a total, a status summarizing rows in a table below it, "last updated on" when the log underneath already says.

When you remove one, repair the sentence rather than leaving a hole: "the four checks below" becomes "the checks below". Deleting the number and leaving dangling grammar is a different defect, not a fix.

Exception — generated navigation. A table of contents restating the headings is a derived value by this test, and hand-maintained ones should indeed go. But leave it alone when it is produced by the docs toolchain at build time, or when the platform requires the marker to render navigation: those are computed on demand, which is what question 1 asks for. Check for a generator before deleting one.

2. Not computable, but the same fact is authoritatively defined somewhere else? → It is a copy. Link to that definition. Do not restate the value.

3. Neither — it records what was true at a particular moment? → Now you may write it down. Price history rows, decision log entries, "as of 2026-03 the vendor required X" — these are the legitimate case, and deleting them destroys an audit trail.

Question 3 needs care, because every stale value was true at some moment — that is what made it stale. But note what question 3 does and does not decide.

It decides one thing: this passage is not a drift problem. It is not a derived value and not a copy, so none of the drift remedies apply to it — do not recompute it, do not link it away, do not "update" it to the current value. Whether the passage is worth keeping at all is a content-value question, and it is answered in Mode 2's value analysis with the document's owner, not here.

Three earlier drafts of this section tried to decide keep-vs-delete right here, and each one failed review. The reason is worth stating so nobody rebuilds it: every version needed the agent to know something it does not have — whether the content could be regenerated, at what cost, by whom, or whether the other copy someone believes exists actually does. A delete authorized on an unverifiable belief is the self-certifying shape this skill exists to remove, and it would be the only evidence-free deletion in the file.

So the test is just the classification:

Is this passage describing how things are now? Then a dated old value in it is a question 1 or 2 case wearing a date, and the date does not rescue it.

Or is it recording what was true at a moment — a changelog line, a decision log entry, a price history row, an incident timeline, a dated measurement, a postmortem? Then it is question 3. Leave the value alone.

Apply this to the passage, not the file — where passage means the unit that would be read as one thing: the entry, the table row, the dated note, the section under one heading. A how-to guide can contain one genuinely historical block, and a changelog can carry a current-state summary at the top; a file-level verdict gets both wrong. But do not run it below the passage either — a postmortem's timeline and its root-cause section are one record, and splitting them so the timeline can be deleted as "reproducible from logs" destroys the thing whose parts they are.

Question 3 takes precedence over questions 1 and 2 for these passages, even though it is asked later. A changelog line "2026-01-04: raised the upload limit to 50 MB" does hit question 2 — the upload limit is authoritatively defined in config — and stopping there would replace it with a link and destroy the record. Question 1 does the same damage by a different route: "2026-01-04: added eu-west-3, bringing us to 12 regions" contains a count, and a count is question 1's own example — but recomputing it yields today's region count and rewrites what that day recorded. The stop-at-first-hit rule is about efficiency, not about routing history into a link or into a recomputation.

When you cannot tell whether a passage is history or current-state, ask — do not resolve it by deleting. The asymmetry is the reason: deleting a record you mistook for a current-state restatement destroys the only copy, while keeping a restatement you mistook for a record costs a few lines. If you are running unattended and cannot ask, leave the passage untouched and report it.

Linking only solves case 2. Pointing a link at a derived value is a category error: there is no single authoritative cell to point at, so the link becomes scaffolding that goes stale on its own and creates a false impression that the two places are aligned.

Why this ordering matters: the mature answer to drift in API documentation is "generate it from the source, don't hand-copy it" (OpenAPI/Swagger exist for exactly this reason). Question 1 is that same instinct applied to prose — the surest way to keep a number correct is for it not to be written down twice.

Position gives no exemption

A fact is a fact wherever it sits. All of these are body text for the purposes of the test above, and all of them are where stale values actually survive audits:

frontmatter · YAML/JSON metadata · parenthetical asides · a description column in an index table · checkbox state · introductory framing before the real content · cross-document footnotes · an extra column added to a table · commit-message-shaped notes left in prose

What counts as a fact

Anything that changes over time and has an authoritative definition somewhere: numbers, status, ownership, relationships, classifications, rules, decision sources, dates, counts. Business rules count too — "all quotes route through the finance lead" is defined once and referenced, never restated in each downstream doc.


Mode 1 — Post-change governance

Run these in order. The order is the point: fixing derived docs before establishing what is authoritative just multiplies the work.

1. Scope it from the change, not from the repo. Enumerate the facts this change altered — this port, this path, this procedure name, this default. That list is what bounds the work. The list is bounded; the search for each item on it is not — a fact's quiet copies live precisely in files the change never touched, so each fact gets searched repo-wide in step 5. What is forbidden is the other thing: opening files to look for unrelated problems. An unbounded sweep is how a doc task turns into an unreviewable refactor.

2. Identify the authoritative source (SSOT) for each affected fact. Which file defines this port / path / procedure — as opposed to mentioning it? Update that first. Everything downstream either points at it or is derived from it.

The practical test for "defines" is where a change has to be made for reality to change: the file the deployment actually reads, the schema the code loads, the runbook a human follows step by step. A file that recites the value while explaining something else is mentioning it. When two files both look declarative, prefer, in order: the one a machine consumes over one only humans read; the one nearest the thing it describes; the one other docs already cite. Then say in your report which you picked and on which of those grounds — an arbitrary pick becomes permanent once step 2 points everything else at it, so it should be a stated decision rather than an accident of which file you opened first.

3. Resolve implementation disagreements from established intent and authorization. Treat code, scripts, config, and observed runs as evidence of current behavior, not as automatic authority over intended behavior. When a requirement, authoritative source, or test establishes the intended behavior and the user has already authorized the scoped implementation fix, repair and verify the implementation first, then update the docs to match. Keep that repair within the facts and files already authorized by the task.

When intended behavior is ambiguous or the implementation change is not already authorized, report the disagreement and obtain the missing decision or authority before editing code. Do not make the documentation describe wished-for behavior, and do not silently turn a documentation pass into an implementat

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars1.4k
CategoryOperations
Updated1mo ago
Forks219

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions