Doc Organizer
Reorganize scattered documentation into a clear, maintainable structure with a single source of truth for every topic.
Workflow
- Audit -- Inventory all docs and classify their topics.
- Plan -- Propose restructuring (moves, merges, deletions). Present the plan for confirmation.
- Execute -- Apply the changes.
- Verify -- Cross-check links, terminology, and completeness.
1) Documentation Audit
Scan the repository for documentation files:
**/*.md, **/*.rst, **/*.txt in root, docs/, guides/, references/- Inline doc comments in config files (YAML, TOML, JSON)
For each file, record:
- Primary topic and subtopics covered
- Last meaningful update (git log)
- Overlap with other files (flag duplicates)
- References to code that may have changed (staleness candidates)
Output: a summary table of all docs with topic, location, staleness risk, and duplicate flag.
2) Structure Optimization
Canonical locations:
| Content type |
Location |
| Project overview, quickstart |
README.md |
| How-to guides, tutorials |
guides/ |
| Architecture, deep-dives |
docs/ |
| API/CLI reference specs |
references/ or docs/reference/ |
| Per-feature notes |
colocated with feature code |
Propose a move plan as a table: current path -> target path -> action (move/merge/delete/keep). Present the plan and wait for user confirmation before executing.
3) Deduplication
- Identify content repeated across multiple files.
- Choose one canonical location; replace duplicates with a short summary and a link.
- Prefer the more detailed version as the canonical source.
4) Terminology Normalization
- Extract key terms from docs (project name variants, feature names, abbreviations).
- Flag inconsistencies (e.g., "config" vs "configuration", "setup" vs "set up").
- Apply the project's preferred terminology uniformly.
5) Navigation Improvement
- Add or update a table of contents in long documents (>100 lines).
- Add cross-links between related docs.
- Ensure
README.md links to all top-level guide and reference docs.
- Create an index page (
docs/README.md or docs/index.md) if multiple docs exist without one.
6) Staleness Detection
Compare documentation claims against the current implementation:
- CLI flags/options mentioned in docs vs actual
--help output or arg parser code.
- Config keys documented vs keys in schema/defaults.
- API endpoints documented vs route definitions.
Flag mismatches as "needs update" with the specific discrepancy.
Verification Checklist
1---2name: doc-organizer3description: Audit, restructure, and consolidate project documentation for clarity and maintainability. Use this skill when docs have grown organically and need reorganization, when duplicate content exists across files, or when documentation structure needs standardization.4license: MIT5---6
7# Doc Organizer
8
9Reorganize scattered documentation into a clear, maintainable structure with a single source of truth for every topic.
10
11## Workflow
12
131. **Audit** -- Inventory all docs and classify their topics.
142. **Plan** -- Propose restructuring (moves, merges, deletions). Present the plan for confirmation.
153. **Execute** -- Apply the changes.
164. **Verify** -- Cross-check links, terminology, and completeness.
17
18## 1) Documentation Audit
19
20Scan the repository for documentation files:
21
22- `**/*.md`, `**/*.rst`, `**/*.txt` in root, `docs/`, `guides/`, `references/`
23- Inline doc comments in config files (YAML, TOML, JSON)
24
25For each file, record:
26- Primary topic and subtopics covered
27- Last meaningful update (git log)
28- Overlap with other files (flag duplicates)
29- References to code that may have changed (staleness candidates)
30
31Output: a summary table of all docs with topic, location, staleness risk, and duplicate flag.
32
33## 2) Structure Optimization
34
35Canonical locations:
36
37| Content type | Location |
38|---|---|
39| Project overview, quickstart | `README.md` |
40| How-to guides, tutorials | `guides/` |
41| Architecture, deep-dives | `docs/` |
42| API/CLI reference specs | `references/` or `docs/reference/` |
43| Per-feature notes | colocated with feature code |
44
45Propose a move plan as a table: `current path -> target path -> action (move/merge/delete/keep)`. Present the plan and wait for user confirmation before executing.
46
47## 3) Deduplication
48
49- Identify content repeated across multiple files.
50- Choose one canonical location; replace duplicates with a short summary and a link.
51- Prefer the more detailed version as the canonical source.
52
53## 4) Terminology Normalization
54
55- Extract key terms from docs (project name variants, feature names, abbreviations).
56- Flag inconsistencies (e.g., "config" vs "configuration", "setup" vs "set up").
57- Apply the project's preferred terminology uniformly.
58
59## 5) Navigation Improvement
60
61- Add or update a table of contents in long documents (>100 lines).
62- Add cross-links between related docs.
63- Ensure `README.md` links to all top-level guide and reference docs.
64- Create an index page (`docs/README.md` or `docs/index.md`) if multiple docs exist without one.
65
66## 6) Staleness Detection
67
68Compare documentation claims against the current implementation:
69
70- CLI flags/options mentioned in docs vs actual `--help` output or arg parser code.
71- Config keys documented vs keys in schema/defaults.
72- API endpoints documented vs route definitions.
73
74Flag mismatches as "needs update" with the specific discrepancy.
75
76## Verification Checklist
77
78- [ ] No broken internal links (relative paths resolve correctly)
79- [ ] No orphaned docs (every doc reachable from README or index)
80- [ ] Terminology consistent across all files
81- [ ] Examples match current CLI/API behavior
82- [ ] Duplicate content eliminated (single source of truth per topic)
s-hiraoku