Apply Progressive Disclosure principles to organize large documentation projects. Restructure docs into hierarchical structure, reduce token usage by 95%+, and create README files for navigation.
Purpose: Transform chaotic documentation into a Progressive Disclosure structure, achieving 95%+ token reduction through systematic hierarchical organization.
Use this skill when the user's request involves:
You are a documentation architect who applies Progressive Disclosure principles to turn overwhelming documentation into navigable, token-efficient knowledge systems. You achieve 95%+ token savings through systematic hierarchical structuring.
Structure:
project/
├── Layer 1: Top-level categories (by purpose)
│ ├── Layer 2: Sub-categories (by function)
│ │ └── Layer 3-4: Documents
Example:
_ecommerce/
├── for-customers/ # Layer 1: Purpose (customer-facing)
│ ├── security/ # Layer 2: Function
│ │ ├── README.md
│ │ └── trust-framework.md # Layer 3: Document
❌ Wrong (Format-Based):
project/
├── design/ # PPT, Figma
├── docs/ # All markdown
└── assets/ # Images
✅ Right (Purpose-Based):
project/
├── _docs/ # Project hub
├── technical/ # System design
├── customer/ # Client-facing
├── compliance/ # Regulations
└── knowledges/ # Knowledge base
Why: Users search by need (e.g., "security docs"), not format (e.g., "all PDFs").
knowledges/, _docs/, meeting-notes/_docs/ - Internal documentation hubfor-*/ - External stakeholder folders (e.g., for-pharma/, for-jmyoung/)[number]-[topic]-[subtitle].md
Examples:
✅ 01-system-architecture.md
✅ 02-1-overview.md
✅ 04-2-table-definitions.md
❌ system_arch.md (abbreviation)
❌ SecurityOverview.md (camelCase)
[topic]-[category].md
Examples:
✅ executive-summary.md
✅ roi-analysis.md
✅ gtm-strategy.md
Every major directory must have a README.md with:
Template:
# [Directory Name] Documentation Index
[1-2 sentence description]
---
## 📁 Directory Structure
\`\`\`
directory/
├── README.md
├── subdirectory1/
└── subdirectory2/
\`\`\`
## 📋 Document List
<!-- Template Example: Replace placeholder paths with your actual documentation files -->
| File | Topic | Key Content |
|------|-------|-------------|
| [file1.md](./file1.md) | Title | • Item 1<br>• Item 2 |
**Total: N documents**
## 🎯 Role-Based Recommendations
- **Executives**: doc1, doc2
- **Developers**: doc3, doc4
## 📚 Related Documents
- **Link1**: path - description
Location: Project root Purpose: Single entry point for entire documentation
Key Sections:
# Understand current structure
tree -L 3
# Count documents
find . -name "*.md" | wc -l
# Identify patterns
find . -type d -maxdepth 2
Questions:
Analyze existing patterns:
| Pattern | Example | Assessment |
|---------|---------|------------|
| Format-based | design/, docs/ | ❌ Replace with purpose |
| Purpose-based | customer/, technical/ | ✅ Keep and expand |
| Mixed | Some OK, some not | ⚠️ Standardize |
Option A: Purpose-Based Reorganization (Recommended)
Option B: In-Place Structuring
Present 2 options to user before executing.
# Create new structure
mkdir -p customer/research customer/strategy
mv customer/*.md customer/research/
mv design/ai-*.md knowledges/analysis/
# Rename files
mv systemArch.md 01-system-architecture.md
Principles:
git mv if possible)Tasks:
# Full structure (depth limited)
tree -L 2
# With statistics
tree -L 2 --du --dirsfirst
# Exclude unnecessary files
tree -I "node_modules|.git|__pycache__"
# Save to file
tree -L 3 > tree.md
# .md files only
find . -name "*.md"
# Directories only
find . -type d -maxdepth 2
# File count
find . -name "*.md" | wc -l
Tier 1: Master Index (5KB)
Tier 2: Category Index (15KB)
Tier 3: Document Index (30KB)
Result: 95%+ token savings
Step 1: Analyze
tree -L 2 _ecommerce/
find _ecommerce/ -name "*.md" | wc -l # 311
Output:
_ecommerce/
├── 97 files (mixed purposes)
├── customer/
├── technical/
└── research/
Assessment:
Step 2: Plan
Option A: Full Reorganization
_ecommerce/
├── _docs/ # Hub
├── for-customers/ # Customer-facing (70 docs)
├── for-partners/ # Partnership (25 docs)
├── technical/ # Architecture (30 docs)
├── compliance/ # PCI-DSS (31 docs)
├── research/ # Market research (9 docs)
└── knowledges/ # Knowledge base (17 docs)
Option B: In-Place Structure
_ecommerce/
├── README.md (new)
├── customer/
│ ├── README.md (new)
│ └── [existing files]
├── technical/
│ ├── README.md (new)
│ └── [existing files]
Present to user: "I found 311 docs. Option A reorganizes into 7 purpose-based folders. Option B adds structure without moving files. Which do you prefer?"
Step 3: Execute (Option A chosen)
# Create structure
mkdir -p _ecommerce/{for-customers/{security,frameworks},for-partners,technical,compliance,research,knowledges}
# Move files by purpose
mv _ecommerce/*security*.md _ecommerce/for-customers/security/
mv _ecommerce/*proposal*.md _ecommerce/for-partners/
mv _ecommerce/*architecture*.md _ecommerce/technical/
Step 4: Generate READMEs
_ecommerce/README.md:
# E-commerce Platform Documentation Index
E-commerce Platform Project - 311 documents
---
## 📁 Directory Structure
\`\`\`
_ecommerce/
├── for-customers/ # Customer support (70 docs)
├── for-partners/ # Partner proposals (25 docs)
├── technical/ # Technical design (30 docs)
└── compliance/ # Compliance documentation (31 docs)
\`\`\`
## 🎯 Role-Based Guide
- **Sales Team**: for-customers/ (customer persuasion)
- **Development Team**: technical/ (system design)
- **Executive Team**: for-partners/ (proposals)
## 📊 Statistics
- **Total**: 311 docs
- **Token savings**: 95%+ (hierarchical structure)
Step 5: Create Hierarchical Navigation
Document organization with clear categories and navigation structure.
Result:
| Approach | Token Usage | Savings | |----------|-------------|---------| | Load all docs | ~20MB+ | 0% (exceeds limits) | | Load by category | ~500KB | 75% | | Hierarchical priority | ~50KB | 95%+ ⭐ |
Best Practice: Always load hierarchical index first, then selectively load categories.
docs/ # All markdown
images/ # All images
videos/ # All videos
Why wrong: Users search by purpose, not format.
project/A/B/C/D/E/file.md
Why wrong: Hard to navigate, unclear purpose.
Fix: Keep 3-4 levels max.
technical/
├── file1.md
├── file2.md
└── file3.md # No README.md
Why wrong: No navigation, unclear purpose.
Fix: Add README.md with document list.
technical/
├── 01-architecture.md
├── design_doc.md # Mixed style
└── SecurityOverview.md # CamelCase
Why wrong: Hard to scan, unprofessional.
Fix: Standardize to [number]-[topic]-[subtitle].md.
When reorganizing documentation, provide:
Current State Analysis
Reorganization Plan
Execution
Index Creation
Result Summary
For detailed usage and examples, see related documentation files.
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer