feat: Add claude-md-progressive-disclosurer skill

- Add skill for optimizing user CLAUDE.md files - Apply progressive disclosure principles to reduce context overhead - Include workflow for auditing, classifying, and refactoring sections - Add reference doc for token economics and best practices - Update marketplace to v1.15.0 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-11 20:20:41 +08:00
parent ec3141b8ef
commit d0042ffc7a
4 changed files with 217 additions and 2 deletions
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -5,8 +5,8 @@
    "email": "daymadev89@gmail.com"
  },
  "metadata": {
-    "description": "Professional Claude Code skills for GitHub operations, document conversion, diagram generation, statusline customization, Teams communication, repomix utilities, skill creation, CLI demo generation, LLM icon access, Cloudflare troubleshooting, UI design system extraction, professional presentation creation, YouTube video downloading, secure repomix packaging, ASR transcription correction, video comparison quality analysis, comprehensive QA testing infrastructure, prompt optimization with EARS methodology, session history recovery, documentation cleanup, and PDF generation with Chinese font support",
-    "version": "1.14.0",
+    "description": "Professional Claude Code skills for GitHub operations, document conversion, diagram generation, statusline customization, Teams communication, repomix utilities, skill creation, CLI demo generation, LLM icon access, Cloudflare troubleshooting, UI design system extraction, professional presentation creation, YouTube video downloading, secure repomix packaging, ASR transcription correction, video comparison quality analysis, comprehensive QA testing infrastructure, prompt optimization with EARS methodology, session history recovery, documentation cleanup, PDF generation with Chinese font support, and CLAUDE.md progressive disclosure optimization",
+    "version": "1.15.0",
    "homepage": "https://github.com/daymade/claude-code-skills"
  },
  "plugins": [
@@ -219,6 +219,16 @@
      "category": "document-conversion",
      "keywords": ["pdf", "markdown", "weasyprint", "chinese-fonts", "document-generation", "legal", "reports", "typography"],
      "skills": ["./pdf-creator"]
+    },
+    {
+      "name": "claude-md-progressive-disclosurer",
+      "description": "Optimize user CLAUDE.md files by applying progressive disclosure principles. This skill should be used when users want to reduce CLAUDE.md bloat, move detailed content to references, extract reusable patterns into skills, or improve context efficiency. Triggers include optimize CLAUDE.md, reduce CLAUDE.md size, apply progressive disclosure, or complaints about CLAUDE.md being too long",
+      "source": "./",
+      "strict": false,
+      "version": "1.0.0",
+      "category": "productivity",
+      "keywords": ["claude-md", "progressive-disclosure", "optimization", "context-efficiency", "configuration", "token-savings"],
+      "skills": ["./claude-md-progressive-disclosurer"]
    }
  ]
 }
--- a/claude-md-progressive-disclosurer/.security-scan-passed
+++ b/claude-md-progressive-disclosurer/.security-scan-passed
@@ -0,0 +1,4 @@
+Security scan passed
+Scanned at: 2025-12-11T20:19:33.266025
+Tool: gitleaks + pattern-based validation
+Content hash: 864b1b4fa2851e26012b06cd3bcb5eb8810ab2cfd3240ba5b48af1895ad182ce
--- a/claude-md-progressive-disclosurer/SKILL.md
+++ b/claude-md-progressive-disclosurer/SKILL.md
@@ -0,0 +1,113 @@
+---
+name: claude-md-progressive-disclosurer
+description: Optimize user CLAUDE.md files by applying progressive disclosure principles. This skill should be used when users want to reduce CLAUDE.md bloat, move detailed content to references, extract reusable patterns into skills, or improve context efficiency. Triggers include "optimize CLAUDE.md", "reduce CLAUDE.md size", "apply progressive disclosure", or complaints about CLAUDE.md being too long.
+---
+
+# CLAUDE.md Progressive Disclosure Optimizer
+
+Analyze and optimize user CLAUDE.md files to reduce context overhead while preserving functionality.
+
+## Quick Start
+
+1. Read the user's `~/.claude/CLAUDE.md`
+2. Analyze each section using the classification criteria below
+3. Propose optimizations with before/after line counts
+4. Execute approved changes
+
+## Section Classification
+
+Analyze each section and classify:
+
+| Category | Criteria | Action |
+|----------|----------|--------|
+| **Keep in CLAUDE.md** | Core principles, short rules (<10 lines), frequently needed | Keep as-is |
+| **Move to references/** | Detailed procedures, code examples, troubleshooting guides | Create `~/.claude/references/<name>.md` |
+| **Extract to skill** | Reusable workflows, scripts, domain-specific knowledge | Create skill in skills repository |
+| **Remove** | Duplicates existing skills, outdated, or unnecessary | Delete after confirmation |
+
+## Optimization Workflow
+
+### Step 1: Audit Current State
+
+```
+Task Progress:
+- [ ] Read ~/.claude/CLAUDE.md
+- [ ] Count total lines
+- [ ] List all ## sections with line counts
+- [ ] Identify sections >20 lines
+```
+
+### Step 2: Classify Each Section
+
+For each section >20 lines, determine:
+
+1. **Frequency**: How often is this information needed?
+2. **Complexity**: Does it contain code blocks, tables, or detailed steps?
+3. **Reusability**: Could other users benefit from this as a skill?
+
+### Step 3: Propose Changes
+
+Present optimization plan in this format:
+
+```markdown
+## Optimization Proposal
+
+**Current**: X lines
+**After**: Y lines (Z% reduction)
+
+| Section | Lines | Action | Destination |
+|---------|-------|--------|-------------|
+| Section A | 50 | Move to references | ~/.claude/references/section_a.md |
+| Section B | 80 | Extract to skill | skill-name/ |
+| Section C | 5 | Keep | - |
+```
+
+### Step 4: Execute Changes
+
+After user approval:
+
+1. Create reference files in `~/.claude/references/`
+2. Update CLAUDE.md with pointers to moved content
+3. Create skills if applicable
+4. Report final line count
+
+## Reference File Format
+
+When moving content to `~/.claude/references/`:
+
+```markdown
+# [Section Title]
+
+[Full original content, possibly enhanced with additional examples]
+```
+
+## CLAUDE.md Pointer Format
+
+Replace moved sections with:
+
+```markdown
+## [Section Title]
+
+[One-line summary]. See `~/.claude/references/[filename].md`
+```
+
+## Best Practices
+
+- **Keep core principles visible**: Rules like "never do X" should stay in CLAUDE.md
+- **Group related references**: Combine small related sections into one reference file
+- **Preserve quick commands**: Keep frequently-used command snippets in CLAUDE.md
+- **Test after optimization**: Ensure Claude can still find moved information
+
+## Common Patterns
+
+### Pattern: Infrastructure/Credentials
+**Before**: Full API examples, deployment scripts, server lists
+**After**: One-line pointer to `~/.claude/references/infrastructure.md`
+
+### Pattern: Code Generation Rules
+**Before**: 50+ lines of coding standards with examples
+**After**: Keep bullet-point rules, move examples to references
+
+### Pattern: Reusable Workflows
+**Before**: Complete scripts embedded in CLAUDE.md
+**After**: Extract to skill with scripts/ directory
--- a/claude-md-progressive-disclosurer/references/progressive_disclosure_principles.md
+++ b/claude-md-progressive-disclosurer/references/progressive_disclosure_principles.md
@@ -0,0 +1,88 @@
+# Progressive Disclosure Principles for CLAUDE.md
+
+## Core Concept
+
+Progressive disclosure is a design pattern that sequences information based on need. For CLAUDE.md:
+
+- **Level 1 (Always loaded)**: CLAUDE.md core content (~100-200 lines ideal)
+- **Level 2 (On-demand)**: `~/.claude/references/` files
+- **Level 3 (Skill-triggered)**: Skills with their own SKILL.md and resources
+
+## Token Economics
+
+Every line in CLAUDE.md consumes context tokens on EVERY conversation. Moving 100 lines to references saves tokens on conversations that don't need that information.
+
+**Example calculation**:
+- CLAUDE.md with 500 lines ≈ 2000 tokens per conversation
+- Optimized 150 lines ≈ 600 tokens per conversation
+- 10 conversations/day = 14,000 tokens saved daily
+
+## What Belongs in CLAUDE.md
+
+### Must Include
+- Identity/persona instructions
+- Critical safety rules ("never do X")
+- Frequently-referenced short rules
+- Tool preferences (ast-grep, difft, uv)
+- Directory/path conventions
+
+### Should Move to References
+- Detailed API examples (>5 lines of code)
+- Troubleshooting guides with multiple steps
+- Infrastructure credentials and procedures
+- Deployment workflows
+- Database schemas
+
+### Should Become Skills
+- Reusable workflows with scripts
+- Domain-specific knowledge bases
+- Complex multi-step procedures
+- Anything another user might benefit from
+
+## Section Size Guidelines
+
+| Lines | Recommendation |
+|-------|----------------|
+| 1-10 | Keep in CLAUDE.md |
+| 11-30 | Consider consolidating or moving |
+| 31-50 | Strongly consider moving to references |
+| 50+ | Must move to references or extract to skill |
+
+## Reference File Organization
+
+```
+~/.claude/
+├── CLAUDE.md                    # Core principles only
+└── references/
+    ├── infrastructure.md        # Servers, APIs, credentials paths
+    ├── coding_standards.md      # Detailed code examples
+    ├── troubleshooting.md       # Common issues and solutions
+    └── domain_knowledge.md      # Project-specific information
+```
+
+## Anti-Patterns
+
+### 1. Embedded Scripts
+**Bad**: 100-line Python script in CLAUDE.md
+**Good**: Script in skill's `scripts/` directory
+
+### 2. Duplicate Documentation
+**Bad**: Same info in CLAUDE.md and a skill
+**Good**: Single source of truth with pointers
+
+### 3. Rarely-Used Details
+**Bad**: Edge-case procedures in CLAUDE.md
+**Good**: Edge cases in references, linked when relevant
+
+### 4. Version-Specific Instructions
+**Bad**: "If using v2.3, do X; if v2.4, do Y"
+**Good**: Current version only, archive old versions
+
+## Measuring Success
+
+After optimization, verify:
+
+1. **Line count reduction**: Target 50%+ reduction
+2. **Information preserved**: All functionality still accessible
+3. **Discoverability**: Claude finds moved content when needed
+4. **Maintenance**: Easier to update individual reference files