Docs Cleaner
Audit markdown and repo docs section-by-section so you can merge duplicates, shorten verbose guides, and pick a single source of truth before edits.
Overview
docs-cleaner is an agent skill most often used in Build (also Operate, Ship) that scores documentation sections for keep, condense, or delete and produces a consolidation plan.
Install
npx skills add https://github.com/daymade/claude-code-skills --skill docs-cleanerWhat is this skill?
- Per-section value table with Keep, Condense, and Delete verdicts plus line counts
- Three-tier value categories: essential procedures, verbose-but-useful, and redundant or outdated material
- Consolidation checklist before deletions: overlap mapping, unique value, and single source of truth
- Structured deliverables: value analysis table and consolidation plan with reference updates
- Designed to align trims with CLAUDE.md, README, and cross-file references
- Three value categories: Keep, Condense, Delete
- Five-item consolidation checklist before proposing deletions
Adoption & trust: 526 installs on skills.sh; 1.2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your repo has scattered markdown that duplicates CLAUDE.md and README content, and you are afraid to delete something onboarding still needs.
Who is it for?
Solo builders standardizing agent context files and human docs after a fast MVP sprint left redundant guides everywhere.
Skip if: Teams that only need a one-line typo fix or have no overlapping documentation to analyze—skip when you already maintain a single canonical doc set.
When should I use this skill?
You need section-by-section documentation analysis with keep/condense/delete decisions and a consolidation plan before editing or removing files.
What do I get? / Deliverables
You get a keep/condense/delete table per section plus a consolidation plan and reference-update list so the agent can shrink docs without losing unique procedures.
- Value analysis table per section
- Consolidation plan with target structure
- Reference update notes for CLAUDE.md and README
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Documentation hygiene is shelved under Build → docs because that is when solo builders most often consolidate READMEs, CLAUDE.md, and skill docs alongside the product. The skill outputs value tables and consolidation plans aimed at developer-facing documentation, not runtime monitoring or growth content.
Where it fits
After adding skills and CLAUDE.md rules, map which sections duplicate the README before merging.
Before open-sourcing, condense verbose setup docs so reviewers see one clear onboarding path.
When support questions repeat, re-run analysis to delete outdated troubleshooting that code now makes obvious.
How it compares
Use instead of asking the agent to “clean up docs” without criteria; this is a structured audit template, not an auto-formatter.
Common Questions / FAQ
Who is docs-cleaner for?
Indie and solo developers using Claude Code or similar agents who maintain CLAUDE.md, README, and extra markdown that has grown overlapping or stale.
When should I use docs-cleaner?
During Build when structuring project docs; during Ship before external contributors read your repo; during Operate when doc drift makes onboarding painful again.
Is docs-cleaner safe to install?
Review the Security Audits panel on this Prism page before installing; the skill guides analysis and deletion proposals but does not replace your judgment on what to keep.
SKILL.md
READMESKILL.md - Docs Cleaner
# Value Analysis Template Use this template for section-by-section documentation analysis. ## Document Analysis Table | Section | Lines | Value | Reason | |---------|-------|-------|--------| | Example Section | 25 | Keep | Contains unique troubleshooting steps not documented elsewhere | | Another Section | 40 | Delete | Duplicates content in CLAUDE.md | | Technical Details | 60 | Condense | Valuable but verbose; can be reduced to 15 lines | | Setup Instructions | 30 | Keep | Essential for onboarding | ## Value Categories ### Keep (Green) - Unique information not found elsewhere - Essential procedures (setup, troubleshooting, constraints) - Frequently referenced content - Technical debt / roadmap items ### Condense (Yellow) - Valuable but overly verbose - Contains redundant examples - Can be expressed more concisely ### Delete (Red) - Duplicates existing documentation - One-time records (test results, meeting notes) - Self-evident information (code already documents this) - Outdated or superseded content ## Consolidation Checklist Before proposing deletions: - [ ] Identified ALL files containing related content - [ ] Mapped overlap between documents - [ ] Listed unique value in each document - [ ] Proposed single source of truth location - [ ] Planned reference updates (CLAUDE.md, README, etc.) ## Output Format After analysis, produce: 1. **Value Analysis Table** - Per-section breakdown with keep/condense/delete 2. **Consolidation Plan** - Target structure with line count estimates 3. **Before/After Comparison** - Total lines and percentage reduction 4. **Preserved Value Checklist** - Confirm all valuable content retained --- name: docs-cleaner description: Consolidates redundant documentation while preserving all valuable content. This skill should be used when users want to clean up documentation bloat, merge redundant docs, reduce documentation sprawl, or consolidate multiple files covering the same topic. Triggers include "clean up docs", "consolidate documentation", "too many doc files", "merge these docs", or when documentation exceeds 500 lines across multiple files covering similar topics. --- # Documentation Cleaner Consolidate redundant documentation while preserving 100% of valuable content. ## Core Principle **Critical evaluation before deletion.** Never blindly delete. Analyze each section's unique value before proposing removal. The goal is reduction without information loss. ## Workflow ### Phase 1: Discovery 1. Identify all documentation files covering the topic 2. Count total lines across files 3. Map content overlap between documents ### Phase 2: Value Analysis For each document, create a section-by-section analysis table: | Section | Lines | Value | Reason | |---------|-------|-------|--------| | API Reference | 25 | Keep | Unique endpoint documentation | | Setup Steps | 40 | Condense | Verbose but essential | | Test Results | 30 | Delete | One-time record, not reference | Value categories: - **Keep**: Unique, essential, frequently referenced - **Condense**: Valuable but verbose - **Delete**: Duplicate, one-time, self-evident, outdated See `references/value_analysis_template.md` for detailed criteria. ### Phase 3: Consolidation Plan Propose target structure: ``` Before: 726 lines (3 files, high redundancy) After: ~100 lines (1 file + reference in CLAUDE.md) Reduction: 86% Value preserved: 100% ``` ### Phase 4: Execution 1. Create consolidated document with all valuable content 2. Delete redundant source files 3. Update references (CLAUDE.md, README, imports) 4. Verify no broken links ## Value Preservation Checklist Before finalizing, confirm preservation of: - [ ] Essential procedures (setup, configuration) - [ ] Key constraints and gotchas - [ ] Troubleshooting guides - [ ] Technical debt / roadmap items - [ ] External links and references - [ ] Debug tips and code snippets ## Anti-Patterns | Pattern | Problem | Solution | |---------|---------|----------| | Blind deleti