aka-luan/doc-cleanup

doc-cleanup is a skill for AI coding assistants like Claude Code that finds and fixes outdated information in a project's markdown documentation, the kind of files such as CLAUDE.md or AGENTS.md that agents are told to read before writing any code. Over time these files build up finished checklists, plans that already shipped, file paths that no longer exist, and facts the codebase has since outgrown, and an agent reading them wastes both money on unnecessary context and, worse, can be led to wrong conclusions by a stale claim it never thought to double check against the real code. The README describes a real run of the skill on an existing project, where three documents totaling 1,085 lines of required reading were cut down to 266 lines, a 75 percent reduction, while nothing was actually lost, since 919 lines of history were moved into an archive folder where they remain searchable. Along the way the audit caught real problems, such as a pricing document stating the same fact two different ways in one file, a feature marked as still waiting to be merged that had actually been merged days earlier, and a rule pointing to a file path on an operating system the machine no longer used. The skill looks for six specific kinds of documentation rot: finished checklists and status logs, plans that already executed but were never rewritten, facts that contradict each other within the same document, facts that no longer match the actual code, references to files or paths that were moved or deleted, and a document being treated as authoritative long after the code moved past it. Just as deliberately, it refuses to delete hard rules, known gotchas, and warnings, since those tend to be the most valuable parts of an agent's documentation. The process runs in five steps: it inventories every markdown file, reads through and verifies claims against the actual code without changing anything, reports its findings and waits for approval, then rewrites the live documents and archives the removed history only after you say yes, and finally checks that every link still works before handing off a docs-only change for you to review. It is installed as a single skill file and can be added with a one-line command, then triggered with a slash command or by describing the task in plain language. The project is released under the MIT license.