docs-consolidator
Skill1 starsChanged 9 months agoMITView on GitHub
Audit and consolidate project documentation in the docs/ folder. Use when the user wants to clean up docs, check docs are up to date, deduplicate information across docs, ensure information lives in the right doc, or reorganize documentation. Triggers on requests like "consolidate docs", "clean up documentation", "audit docs", "organize docs", "sync docs with code".
In this repository9 other files it gives its agents.
- bug-bash-updateSkill
- ci-cd-pipelineSkill
- claudemd-auditorSkill
- ralphSkill
- refactor-auditSkill
- reflectSkill
- setup-workflowSkill
- skill-reviewerSkill
- smoke-testSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. About 0 are common, 16 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈16
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 14
Check if .claude/doc-registry.md exists in the project root.
- Distinctive: line 15
If it exists: read it and use it as the authoritative registry.
- Distinctive: line 22
If no registry existed, build one: assign each doc a purpose and ownership domain.
- Very specific: line 31
If the registry was generated (not loaded from file), write it to .claude/doc-registry.md in the project root using this format:
- Distinctive: line 51
Read every doc (if not already read in Phase 1) and compare against the registry.
- Distinctive: line 80
Ask the user to approve the plan before making any changes.
- Distinctive: line 84
After approval, apply changes doc by doc:
- Distinctive: line 88
Remove or update stale content
- Distinctive: line 90
Update any cross-references that broke due to moves
- Distinctive: line 91
Document new features across relevant docs:
- Distinctive: line 98
Only update docs where the feature introduces something new for that doc's domain.
- Distinctive: line 99
All existing guidelines apply: prefer cross-references over duplication, keep CLAUDE.md lean, preserve writing style, one source of truth …
- Distinctive: line 103
Check that every doc has the content it should own and nothing else
- Distinctive: line 105
If CLAUDE.md has a "Reference Documents" section, confirm it matches the actual docs
- Distinctive: line 111
Prefer cross-references over duplication.
- Distinctive: line 112
Don't merge docs unless the user explicitly asks.
- Distinctive: line 114
When uncertain whether content is stale, flag it for the user rather than deleting.
- Very specific: line 115
If an archive/ directory exists, move superseded docs there rather than deleting.
- Distinctive: line 116
Keep CLAUDE.md lean: orientation, commands, conventions, gotchas.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Docs Consolidator
Audit, deduplicate, and reorganize project documentation so every piece of information has one home and all docs stay current.
Workflow
Phase 1: Build the inventory
- Check if
.claude/doc-registry.mdexists in the project root.- If it exists: read it and use it as the authoritative registry. Skip to step 4.
- If it doesn't exist: continue to step 2 to discover and generate one.
- Find all documentation files: scan
docs/, rootCLAUDE.md(ordocs/CLAUDE.mdif symlinked),README.md, and any other.mdfiles referenced by CLAUDE.md. - For each doc, read it and note:
- What information it currently contains (section-level summary)
- Its apparent purpose (infer from filename, headers, and content)
- Its line count
- If no registry existed, build one: assign each doc a purpose and ownership domain. Use these common categories as a guide:
- CLAUDE.md — Orientation for Claude Code sessions: conventions, gotchas, pointers. NOT a wiki.
- PRD / product doc — Product logic, user stories, feature specs, business rules
- Architecture doc — System design, data flow, database schema, API endpoints
- Tasks / progress doc — Current tasks, completed work, backlog
- Deployment / CI-CD docs — Deployment config, pipelines, environment setup
- Security docs — Threat models, trust assumptions, audit scope
- Testing docs — Test checklists, QA guides
- Setup / infra docs — Database setup, service config, hosting details
- If the registry was generated (not loaded from file), write it to
.claude/doc-registry.mdin the project root using this format:
# Document Registry
Each doc has ONE purpose. Information belongs in the doc that owns that domain.
| File | Purpose | Owns |
|------|---------|------|
| `path/to/doc.md` | Brief purpose | What information this doc is the canonical source for |
## Overlap Rules
- [category] → `canonical-doc.md`, not [other doc]Present the generated registry to the user and ask for approval before continuing. The user may want to adjust purposes or ownership boundaries.
Phase 2: Identify problems
Read every doc (if not already read in Phase 1) and compare against the registry. Flag:
- Misplaced information: content that belongs in a different doc per ownership rules (e.g., architecture details in CLAUDE.md, progress updates in an architecture doc)
- Duplication: the same information restated in multiple docs. Identify the canonical home and where the duplicates are.
- Stale content: references to removed code, outdated addresses, old instructions, TODOs that are done, etc. Cross-check against actual code when uncertain.
- Missing information: important topics not documented anywhere, or docs that reference sections that don't exist.
- Poor organization: docs where sections are out of logical order, or where related information is scattered across unrelated sections.
- Undocumented feature: Examine the current branch name, recent commits, and changed files to determine if a significant new feature was implemented. Check each doc in the registry to see if it needs updating for this feature. For example: does the tasks/progress doc need a new milestone? Does the architecture doc need new components or APIs? Does a security doc need new threat analysis? Flag each doc that needs additions.
Phase 3: Present the plan
Present findings as a structured report to the user:
## Doc Audit Report
### Misplaced Information
- [ ] [source doc] → [target doc]: [what to move]
### Duplications
- [ ] [info]: found in [doc A] and [doc B]. Keep in [canonical doc], remove from [other].
### Stale Content
- [ ] [doc]: [what's stale and why]
### Organization Issues
- [ ] [doc]: [what to reorder/restructure]Ask the user to approve the plan before making any changes.
Phase 4: Execute changes
After approval, apply changes doc by doc:
- Move misplaced content to the correct doc
- Deduplicate — keep the best version in the canonical location, replace duplicates with a brief cross-reference (e.g., "See
ARCHITECTURE.mdfor database schema") - Remove or update stale content
- Reorder sections for logical flow
- Update any cross-references that broke due to moves
- Document new features across relevant docs:
- For each doc flagged as needing feature documentation, add content to the appropriate existing sections following the doc's style.
- Tasks/progress docs: create a new milestone or section tracking the completed work. Mark items as done. Include PR references if available.
- Architecture docs: add new components, endpoints, schemas, or data flows.
- Product/PRD docs: add new feature specs or user flows.
- Security docs: add new trust assumptions or threat analysis.
- CLAUDE.md: add key hooks, architectural notes, or gotchas (keep lean).
- Only update docs where the feature introduces something new for that doc's domain. Don't force updates.
- All existing guidelines apply: prefer cross-references over duplication, keep CLAUDE.md lean, preserve writing style, one source of truth per topic.
Phase 5: Verify
- Check that every doc has the content it should own and nothing else
- Grep for broken cross-references (doc paths, section links)
- If CLAUDE.md has a "Reference Documents" section, confirm it matches the actual docs
- For any new feature detected, confirm each flagged doc was updated and new content is in the correct section per the registry.
- Present a brief summary of all changes made
Guidelines
- Prefer cross-references over duplication. A one-line pointer is better than a restated paragraph.
- Don't merge docs unless the user explicitly asks. The goal is to put information in the right place, not reduce the number of files.
- Preserve the user's writing style and voice. Clean up structure, not prose.
- When uncertain whether content is stale, flag it for the user rather than deleting.
- If an
archive/directory exists, move superseded docs there rather than deleting. - Keep CLAUDE.md lean: orientation, commands, conventions, gotchas. Everything else belongs in a specific doc.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

