docs-hygiene
Audits CLAUDE.md/AGENTS.md/SKILL.md instruction files against current repo state, catches claims that have gone stale (a renamed path, a dropped command, a policy that changed) before they get trusted or acted on, and resolves contradictions between layered instruction files (root vs nested, SKILL.md vs its parent AGENTS.md) down to one explicit kept version instead of leaving both to stand. Use before trusting or propagating any instruction-file claim you haven't personally re-checked, whenever onboarding a repo's docs for the first time, right after a refactor/rename/policy change that could invalidate what's documented, or whenever two instruction files (or an instruction file and the actual repo) say different things about the same fact. Trigger phrases: 'audit the docs', 'is AGENTS.md still accurate', 'clean up CLAUDE.md', 'these instructions contradict each other', 'refactor the AGENTS.md files'.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- docs-hygiene
- description
- Audits CLAUDE.md/AGENTS.md/SKILL.md instruction files against current repo state, catches claims that have gone stale (a renamed path, a dropped command, a policy that changed) before they get trusted or acted on, and resolves contradictions between layered instruction files (root vs nested, SKILL.md vs its parent AGENTS.md) down to one explicit kept version instead of leaving both to stand. Use before trusting or propagating any instruction-file claim you haven't personally re-checked, whenever onboarding a repo's docs for the first time, right after a refactor/rename/policy change that could invalidate what's documented, or whenever two instruction files (or an instruction file and the actual repo) say different things about the same fact. Trigger phrases: 'audit the docs', 'is AGENTS.md still accurate', 'clean up CLAUDE.md', 'these instructions contradict each other', 'refactor the AGENTS.md files'.
02 资源文件 1
- 参考文档references/refactoring-workflow.md5.6 KB
03 SKILL.md 正文
docs-hygiene
Invariant
A claim in an instruction file (CLAUDE.md/AGENTS.md/SKILL.md) is NEVER trusted or propagated forward without being re-verified against current repo state first. When a checked claim is UNAMBIGUOUS — source and doc plainly disagree on a checkable fact — the instruction file is FIXED IN PLACE, in the same pass: edit the file itself. Do not merely flag it, and do not convert it into a question for the user to answer instead of acting. Flagging instead of fixing is reserved for the genuinely ambiguous case (see "Fixing what you find" below) — it is a fallback, not an equal alternative. When two or more layered instruction files disagree with each other, the audit ALWAYS resolves the disagreement to one explicit kept version — it NEVER leaves the contradiction standing for the next reader (human or agent) to trip over and silently pick a side.
<!-- MEASURED, one-armed probe (the control agent errored out, so this is not a controlled A/B — treat it as a strong signal, not a proof): given a repo whose CLAUDE.md contradicted its own source on two clearly checkable facts (claimed x-api-key auth / no integration suite; the source used JWT bearer / an integration suite existed), the unaided model read the source, caught BOTH contradictions, and tabled them for the user in the same pass — genuinely good triage. What it did NOT do is edit CLAUDE.md. It held a principled prior against touching an instruction file during a docs task and said so explicitly. So "flagging" a contradiction is already the base-model default — a future contributor does not need to add more prose telling the model to flag things; it already will. What earns this plugin its slot is the opposite instruction: FIX unambiguous contradictions in place, don't just flag them. Don't re-inflate the "or explicitly flag" half back to parity with fixing — that regresses toward what the unaided model already does for free. -->
Everything below exists to keep that true.
Why this matters
For an AI agent that reads instruction files on every request, stale information doesn't just mislead once the way a stale doc misleads a skimming human — it actively poisons the context, because the agent has no built-in skepticism toward a file that's checked into the repo and formatted like every other doc. A human skimming CLAUDE.md brings background doubt ("is this still true?"); an agent treats every claim in an instruction file as authoritative on every single read, so one stale sentence misleads on every subsequent turn until something forces a re-check.
This is the exact same failure shape as a GitOps controller that stays green — Ready: True — while quietly reconciling against a stale artifact, because the controller never re-diffs its own claim of freshness against what's actually live. An instruction file fails the same way: it sits there looking authoritative — present, well-formatted, checked in — while the fact it asserts has silently diverged from reality. Present and well-formatted is not evidence of current. That gap is exactly why this audit exists as its own repeatable step instead of a one-time write nobody revisits.
Two real, in-repo instances of this exact failure, not hypotheticals — one of them git-verifiable history rather than present-tense (a present-tense claim about a table that gets rebuilt every time a plugin ships is exactly the kind of claim guaranteed to go stale again, so this cites the fixed incident, not the live table):
- This marketplace's own root
README.md, historically: right before the fix commit1d6d73f, its plugin table named only 2 of the 11 plugins then registered inmarketplace.json(graveyardandtailscale-wif) — present, well-formatted, and quietly wrong since roughly the third plugin was added, with nothing re-checking the README's claim against the manifest it was describing. The fix commit1d6d73fcaught it, rebuilt the table frommarketplace.json, and added a permanent regression guard (evals/cheap/run.sh, the "README documents every registered plugin" check) so every plugin registered inmarketplace.jsonmust be named inREADME.mdor the cheap tier fails closed. That fix landed before this plugin existed — verify it yourself withgit show 1d6d73f^:README.mdvsgit show 1d6d73f^:.claude-plugin/marketplace.json. - The retired fleet-playbook-curator's README at
0f0eb6frecords an earlier "Freshly scaffolded... intentionally RED" status that persisted after its evals were implemented. The correction remains a historical example; the package is no longer a current instruction-file target.
When to use this
- Before trusting or acting on any instruction-file claim you have not personally re-checked this session — a path, a command, a policy statement.
- Reading a repo's instruction files for the first time (onboarding).
- Right after any refactor, rename, move, or policy change that could invalidate something documented.
- Whenever two instruction files in the same repo could plausibly disagree — a root
AGENTS.mdvs a nested per-package/per-pluginAGENTS.md, aSKILL.mdvs theAGENTS.mdabove it, orCLAUDE.md/GEMINI.mdsymlink targets that have drifted from what they point at. - On explicit request: "audit," "clean up," "refactor," or "is this still true" applied to any instruction file.
Staleness-detection heuristic
This is a per-claim checklist applied the moment a claim is about to be trusted or propagated — a fast triage, not a multi-step workflow.
-
Does the claim have a checkable target at all? A pure policy/judgment statement ("PRs require review") or an invariant ("X must never happen") isn't "stale" in this sense unless it asserts a fact about current repo state — "PRs require review, enforced by branch protection" IS checkable, because of that enforcement clause. Skip verification for claims with no checkable target; staleness detection is for factual/structural claims, not policy or judgment.
-
Tier by drift risk, check in this order, stop once satisfied:
- Paths (highest risk — a rename or move breaks these silently and completely): does the named file/directory exist, right now, at that exact path? One
ls/rg/findcall. If a claim says "X lives inpath/to/file," confirm the path resolves before trusting anything built on top of it. - Commands (second-highest): does the named command actually exist and do what's claimed — check the real script/Makefile target/CLI entry, not just whether the words sound plausible.
grep '"scriptname"' package.json,which, or reading the actual script. - Behavior/architecture claims ("X always happens when Y"): spot-check against the real code path with one grep/read — verify against the code, never against the doc's own restatement of itself.
- Domain-concept/vocabulary claims ("we call it a 'workspace,' not an 'org'"): lowest drift risk, but check when something else already smells off — e.g. the code visibly uses different terminology than the doc.
- Paths (highest risk — a rename or move breaks these silently and completely): does the named file/directory exist, right now, at that exact path? One
-
Freshness cross-check: when available cheaply, compare the instruction file's last-touched date/commit against the code path it describes —
git log -1 --format=%ai -- <doc>vsgit log -1 --format=%ai -- <path it names>. If the code changed more recently than the paragraph describing it, treat that paragraph as suspect by default — verify it explicitly rather than extending it good faith.
Fixing what you find
This ties directly back to the invariant's "fix it in place" clause. The two cases below are NOT equal alternatives — unambiguous is the default outcome for most claims this audit finds; ambiguous is the narrow exception.
- Unambiguous fix (the default) — source and doc plainly disagree on a checkable fact, and there's one obvious current replacement: the old path/command literally doesn't exist, or the actual code states the real behavior (the real auth scheme, the real test suite that exists) in a way that flatly contradicts the doc. Edit the instruction file in place, in the same pass — this includes CLAUDE.md/AGENTS.md/SKILL.md themselves. Editing those files is this plugin's whole job, not something to route around by writing the correction somewhere else instead. Do not merely flag it in a table, a comment, or a "known issues" note. Do not convert it into a question for the user ("should I fix this?") — that's a way of deferring an unambiguous fix, not surfacing a real ambiguity, and a flagged-but-unfixed stale claim is still a stale claim on the next read.
- Ambiguous fix (the narrow exception — flagging instead of fixing is appropriate ONLY here) — unclear which of several candidates is correct, or it's a genuine judgment call about intent that no grep or read settles: do not guess, and do not edit. Surface it explicitly — name the specific claim, the specific contradiction with observed reality, and ask which is correct — rather than silently picking one or leaving it untouched "for later."
Resolving contradictions across layered instruction files
This is a separate, heavier procedure from the single-claim staleness-checking above, because it means comparing multiple files against each other, not just one file against the repo. Load references/refactoring-workflow.md only when this audit finds — or is asked to find — two or more instruction files that could conflict: a root AGENTS.md plus one or more nested AGENTS.md/SKILL.md files, or CLAUDE.md/GEMINI.md that have drifted apart from what they symlink to. For a single-file, single-claim staleness check, the inline heuristic above is sufficient — don't load the reference file for that case.
What this isn't
- Not a scheduled cross-repo index. Such an index routes readers to source repositories and may declare
source-of-truth: false; it does not repair the instruction files it indexes. docs-hygiene audits and edits existing instruction files inside a target repo, in place and on demand. Across many repos it runs as independent per-repo passes; it does not provide fleet discovery, cron, or citation-ledger automation. The retired fleet-playbook-curator was an example of that separate capability, not a currently available recommendation. - Not plugin-factory. plugin-factory generates a brand-new plugin's
SKILL.md/AGENTS.mdskeleton at scaffold time, scoped to this one marketplace repo. docs-hygiene audits existing instruction files, at any later time, in any repo — general-purpose, not authoring-time, not marketplace-specific. It is not "the thing that fixes what plugin-factory generated" — it fixes any instruction file, generated by anything, any time after it's written.
Keep it portable
The procedure above is prose, grep, and git log judgment — no harness-specific mechanism. It works identically whether invoked as a Claude Code skill, run by hand, or run under any other agent harness that can read a repo and run shell commands.
04 同仓库更多 Skills
wayfinder
Chart a multi-session effort as a labeled map of typed decision tickets (grilling / prototype / research / task) with explicit dependencies and an open frontier agents self-assign into. Plans; never executes. Use this skill whenever the user is working with wayfinder, and on phrases like "chart this effort", "break this into tickets", "what's the frontier", "plan across sessions", or "map out the dependencies for this work".
wave-research
Staged, adversarial research that tries to break a thesis before believing it: waves, checkpoints, falsifiable sub-claims, rival hypotheses, an ACH matrix, source-incentive tags and a verified final thesis. Also carries Workflow templates for a one-pass research-and-verify fan-out. Use to stress-test or vet a contested claim; not for quick lookups.
second-opinion
Offer-only validation pipeline for a verdict or recommendation. Use when the user asks to validate, verify, fact-check, or get a second opinion on a claim or recommendation — "are you sure", "double-check this", "second opinion". Batches fact-checking against sources, adds scoped advisor personas for the angles that need judgment, then re-emits the response grouped into verified, flagged, and conflict, with a mandatory validation delta. Requires a subagent-spawning tool; without one it must decline rather than simulate.
machine-voice
Compression rules for standalone machine-read artifacts the reader scans — agent traces, tool-call logs, status lines, progress updates, handoff notes, state dumps, config, schemas, reference cards, and structured data another agent parses. Applies three layers: lexical compression, markdown structure as navigation, and emojis as typed status markers. Reach for it when emitting one of those artifacts on its own. Companion to human-voice, which governs prose a human reads and also owns any table or block that serves surrounding explanation. Neither skill applies to code or file contents the user will save, commit messages, creative writing, or turns that are only a clarifying question — those ship unstyled and uncompressed.
human-voice
Style for prose a human reads — answers, recommendations, explanations, research summaries, comparisons. Use on every conversational reply that contains prose for a person to read: triage intent, lead with the verdict, keep it scannable, tag claim confidence. Reach for it whenever answering a technical question, comparing options, or making a recommendation, even when the user says nothing about style. Companion to machine-voice, which instead governs standalone machine-read artifacts — agent traces, tool-call logs, status lines, progress updates, handoff notes, state dumps, config, schemas, reference cards, and structured data another agent parses. Neither skill applies to code or file contents, commit messages, creative writing, or turns that are only a clarifying question — those ship unstyled.
ai-writing-mistakes
Catch and repair the tells that mark prose as machine-written — the negation-flip ("it's not X, it's Y"), rule-of-three padding, hedge stacking, unearned intensifiers, filler verbs like delve and leverage, participle trailers ("...ensuring seamless integration"), sycophantic openers, empty closing summaries, and uniform em-dash/sentence rhythm. Use when drafting or revising any prose a human will read, including documents you were asked to author — READMEs, docs, PR bodies, release notes, emails — and when the user asks whether something "sounds like AI" or wants writing tightened. This is a wording pass, not a voice: human-voice still decides layout and confidence tags, machine-voice still owns traces and logs, and neither this skill nor those two touch code, commit messages, or quoted text.