[Feature]: Automated SKILL.md compaction workflow for progressive disclosure

## Feature Type
Workflow Improvement

## Related Plugin
llmstxt (but applicable to all skills)

## Problem Statement

Claude Code skills face a tension between being comprehensive and staying compact.

**Issue:** Large SKILL.md files (>3,000 words) bloat context unnecessarily, degrading performance.

**Real Example (openclaw-docs):**
- **Before:** 5,036 words in single file
- **After manual compaction:** 1,384 words (72.5% reduction) + 6 extracted files
- **Result:** Faster loading, relevant context only

**Why This Matters:**
1. **Performance** - Smaller SKILL.md = faster loading, less overhead
2. **Relevance** - Load only what's needed when needed
3. **Maintainability** - Modular structure easier to update
4. **Scalability** - Large domains can be properly documented
5. **UX** - Faster, more responsive Claude Code

Manual compaction is tedious and error-prone. Need automation.

---

## Proposed Solution

### Automated Compaction Tool

Create `/compact-skill` command that:
1. Analyzes SKILL.md for compaction opportunities
2. Identifies extractable sections (>400 words each)
3. Generates `SKILL-*.md` files in `references/` directory
4. Updates main SKILL.md with summaries + links
5. Validates file structure and links
6. Preserves original as backup

### Command Interface

```bash
# Interactive mode
/compact-skill

# Analyze without changes
/compact-skill --analyze

# Auto-compact with defaults
/compact-skill --auto

# Custom target size
/compact-skill --target-words 2000
```

### Example Workflow

**Step 1: Analysis**
```
SKILL.md Analysis
─────────────────────────────────────
Total words: 5,036
Target: <2,000 words
Compaction needed: YES (3,036 words to extract)

Extractable Sections:
1. Installation & Setup (892 words) → SKILL-INSTALLATION-SETUP.md
2. Architecture (745 words) → SKILL-ARCHITECTURE.md
3. Workspace Configuration (512 words) → SKILL-WORKSPACE-CONFIGURATION.md
4. Memory System (634 words) → SKILL-MEMORY-SYSTEM.md
5. Skills & Hooks (489 words) → SKILL-SKILLS-AND-HOOKS.md
6. Workflows (380 words) → SKILL-WORKFLOWS.md

Remaining in SKILL.md: 1,384 words ✓

Proceed with compaction? (y/N)
```

**Step 2: Extraction**

For each section:
- Extract content including heading + subsections
- Create `SKILL-*.md` in `references/`
- Add frontmatter with metadata
- Generate filename from section title

**Step 3: SKILL.md Update**

Replace extracted sections with references:

**Before:**
```markdown
## Installation & Setup

Detailed installation instructions spanning 892 words...
[... extensive content ...]
```

**After:**
```markdown
## Installation & Setup

For detailed installation instructions, see [SKILL-INSTALLATION-SETUP.md](references/SKILL-INSTALLATION-SETUP.md).

**Quick overview:**
- Install OpenClaw CLI
- Configure channels
- Set up permissions

> Full walkthrough with troubleshooting in reference file.
```

---

## Implementation Details

### Phase 1: Analysis

**Input:** `SKILL.md` file path

**Steps:**
1. Count total words
2. Identify major sections (## headers)
3. Calculate word count per section
4. Determine if compaction needed (>2,500 words threshold)
5. Suggest sections to extract

**Output:** Analysis report

### Phase 2: Extraction

For each extractable section:

1. **Extract content** including heading and subsections
2. **Create file** in `references/` directory
3. **Add frontmatter:**
   ```yaml
   ---
   source: SKILL.md
   section: Installation & Setup
   extracted: 2026-02-01T18:30:00.000Z
   word_count: 892
   ---
   ```
4. **Generate filename:** `SKILL-INSTALLATION-SETUP.md`
   - Convert section title to uppercase
   - Add SKILL- prefix
   - Use kebab-case

### Phase 3: Validation

**Checks:**
- ✅ All SKILL-*.md files created successfully
- ✅ Total words across all files = original total
- ✅ Links in SKILL.md resolve correctly
- ✅ No orphaned content
- ✅ Frontmatter valid YAML
- ✅ File naming convention followed

### Phase 4: Index Generation

Create `SKILL-INDEX.md`:

```markdown
# Skill Reference Files

Quick index of extracted documentation:

## Installation & Setup
[SKILL-INSTALLATION-SETUP.md](SKILL-INSTALLATION-SETUP.md)
- macOS permissions and TCC setup
- Channel configuration (iMessage, Discord, etc.)
- CLI installation and pairing

## Architecture
[SKILL-ARCHITECTURE.md](SKILL-ARCHITECTURE.md)
- Gateway, agents, sessions
- WebSocket protocol
- Memory and vector search

[... etc ...]
```

---

## Naming Convention

### SKILL-*.md Files (Uppercase)

**Format:** `SKILL-{SECTION-NAME}.md`

**Rules:**
1. **Uppercase filename** - Distinguishes from downloaded docs
2. **SKILL- prefix** - Clearly identifies as skill-generated
3. **Kebab-case** - Section name in lowercase with hyphens
4. **Descriptive** - Name reflects section content

**Examples:**
```
Installation & Setup       → SKILL-INSTALLATION-SETUP.md
API Reference             → SKILL-API-REFERENCE.md
Troubleshooting Guide     → SKILL-TROUBLESHOOTING-GUIDE.md
Advanced Configuration    → SKILL-ADVANCED-CONFIGURATION.md
```

### Why Uppercase?

**Clear Visual Distinction:**
```
references/
├── SKILL-ARCHITECTURE.md           # Generated (uppercase)
├── SKILL-INSTALLATION-SETUP.md     # Generated (uppercase)
├── architecture.md                 # Downloaded (lowercase)
├── setup.md                        # Downloaded (lowercase)
```

**Benefits:**
- Instantly recognizable as skill-generated
- Won't conflict with downloaded documentation
- Alphabetically grouped in listings
- Prevents accidental overwrites during updates

---

## When to Compact

**Triggers:**
1. SKILL.md exceeds 2,500 words (warning)
2. SKILL.md exceeds 3,500 words (critical)
3. User explicitly requests compaction
4. Skill performance degrades noticeably

**Detection:**
```bash
# Automated check
cc --plugin-dir . --check-skill-size

Output:
⚠️  SKILL.md is 5,036 words (target: <2,500)
Consider running: /compact-skill
```

---

## Workflow Process

### Step-by-Step

**1. Analyze:**
```bash
/compact-skill --analyze
```
Shows word count analysis, suggests extractable sections, estimates final sizes.

**2. Review Suggestions:**
```
Suggested extractions:
✓ Installation (892 words)
✓ Architecture (745 words)
✓ Configuration (512 words)
⊗ Quick Start (187 words) - too small, keep in SKILL.md
```

**3. Execute:**
```bash
/compact-skill
```
- Creates backup: `SKILL.md.backup`
- Extracts sections
- Updates SKILL.md
- Generates index
- Validates all files

**4. Verify:**
```bash
# Check file structure
ls -lh references/SKILL-*.md

# Verify word counts
wc -w SKILL.md references/SKILL-*.md

# Test skill loading
cc --plugin-dir . --test-skill-load
```

---

## Dependencies & Side Effects

### File System Changes

**Created:**
- `references/SKILL-*.md` files (6+ typically)
- `references/SKILL-INDEX.md` (generated index)
- `SKILL.md.backup` (safety backup)

**Modified:**
- `SKILL.md` (sections replaced with links)

**Never Modified:**
- Downloaded documentation (*.md without SKILL- prefix)
- User-created content
- Original backup

### Update Script Protection

Scripts that auto-update docs must protect SKILL-*.md:

```bash
# In update-docs.sh
if [[ "$filename" =~ ^SKILL- ]]; then
    echo "Skipping $filename (skill-generated, not auto-updatable)"
    continue
fi
```

### Context Loading Changes

**Before:**
- SKILL.md loaded entirely: 5,036 words
- All content in context always

**After:**
- SKILL.md loaded: 1,384 words
- SKILL-*.md loaded on-demand only
- 72.5% context reduction

**Impact:** Faster skill loading, reference files need explicit reads

### Search Changes

**Before:**
```bash
grep "installation" SKILL.md  # Found in main file
```

**After:**
```bash
grep "installation" SKILL.md  # Only finds reference link
grep -r "installation" references/SKILL-*.md  # Finds actual content
```

**Solution:** Update search to include `references/SKILL-*.md`

---

## Integration Points

### 1. llmstxt-to-skill Plugin

```bash
/llmstxt-to-skill https://docs.example.com/llms.txt --compact

# Workflow:
# 1. Download docs from llms.txt
# 2. Generate SKILL.md
# 3. Auto-detect if >2,500 words
# 4. Run /compact-skill automatically
# 5. Result: Clean, compacted skill
```

### 2. Update Scripts

Protect SKILL-*.md files from overwrites:

```bash
# Skip SKILL-* files in all operations
if [[ "$filename" =~ ^SKILL- ]]; then
    continue
fi
```

### 3. CI/CD Validation

Pre-commit hook:

```bash
#!/bin/bash
# Check skill size

for skill in .claude/skills/*/SKILL.md; do
    words=$(wc -w < "$skill")
    if [ "$words" -gt 3500 ]; then
        echo "❌ $skill is $words words (max: 3,500)"
        echo "Run /compact-skill to reduce size"
        exit 1
    fi
done
```

---

## Benefits

### Performance
- **Context reduction:** 60-75% typical
- **Loading speed:** Faster skill initialization
- **Memory:** Reduced footprint
- **Responsiveness:** Better Claude Code performance

### User Experience
- **Progressive disclosure:** Core concepts always available
- **On-demand details:** Deep dives loaded when needed
- **Cleaner files:** More focused main file

### Maintainability
- **Independent updates:** Update sections separately
- **Smaller diffs:** Focused version control changes
- **Clear boundaries:** Well-defined file responsibilities

### Scalability
- **Large domains:** Support comprehensive documentation
- **No limits:** No artificial size constraints
- **Proper depth:** Detail without bloat

---

## Success Criteria

✅ **Functional:**
- Successfully compacts SKILL.md >2,500 words
- Creates valid SKILL-*.md files
- Maintains content integrity
- Updates references correctly

✅ **Performance:**
- 60%+ context reduction typical
- No degradation in skill quality
- Faster loading measurable

✅ **Usability:**
- Simple command interface
- Clear progress indicators
- Helpful error messages
- Reversible operations

✅ **Maintainability:**
- Generated files clearly marked
- Update scripts protect SKILL-*.md
- Documentation kept in sync
- Git-friendly workflow

---

## Alternatives Considered

### 1. Multiple Skill Files
**Idea:** Split into separate skill directories
```
skills/
├── openclaw-core/
├── openclaw-installation/
├── openclaw-architecture/
```

**Rejected:**
- ❌ Breaks skill cohesion
- ❌ Harder to maintain relationships
- ❌ User must enable multiple skills
- ❌ Duplicate frontmatter/metadata

### 2. Lazy Loading Sections
**Idea:** Keep monolithic file, load sections on-demand

**Rejected:**
- ❌ Requires Claude Code core changes
- ❌ Complex caching logic
- ❌ Doesn't reduce file size
- ❌ Still bloated in version control

### 3. External Documentation Only
**Idea:** Keep SKILL.md tiny, link to external docs

**Rejected:**
- ❌ Requires network access
- ❌ External docs may change
- ❌ No offline access
- ❌ Defeats self-contained purpose

### 4. Dynamic Generation
**Idea:** Generate SKILL.md from templates on load

**Rejected:**
- ❌ Too complex
- ❌ Hard to debug
- ❌ Obscures actual content
- ❌ Build step dependencies

**Chosen approach (file extraction) is simplest and most maintainable.**

---

## Real-World Reference

**openclaw-docs skill demonstrates this pattern:**

**Results:**
- Original: 5,036 words
- Compacted: 1,384 words (72.5% reduction)
- Extracted: 6 SKILL-*.md files totaling 3,652 words

**Files created:**
```
references/
├── SKILL-INSTALLATION-SETUP.md      # Installation walkthrough
├── SKILL-ARCHITECTURE.md            # System architecture
├── SKILL-WORKSPACE-CONFIGURATION.md # Config templates
├── SKILL-MEMORY-SYSTEM.md           # Memory & vector search
├── SKILL-SKILLS-AND-HOOKS.md        # Development patterns
└── SKILL-WORKFLOWS.md               # Operational workflows
```

**Impact:**
- Faster skill loading
- Relevant context only
- Easier maintenance
- Better organization

---

## Implementation Priority

**Phase 1: Core Compaction (High Priority)**
- Analysis tool
- Section extraction
- SKILL.md update
- Basic validation

**Phase 2: Automation (Medium Priority)**
- Auto-detect threshold
- Suggest compaction
- Interactive mode
- Re-compaction support

**Phase 3: Integration (Lower Priority)**
- llmstxt-to-skill integration
- CI/CD hooks
- IDE extensions
- Advanced indexing

---

**Submitted:** 2026-02-01
**Category:** Developer Experience, Performance
**Complexity:** Medium (tooling required, well-scoped)
**Impact:** High (affects all large skills, improves performance significantly)


[Feature]: Automated SKILL.md compaction workflow for progressive disclosure #6

Description

Feature Type

Related Plugin

Problem Statement

Proposed Solution

Automated Compaction Tool

Command Interface

Example Workflow

Implementation Details

Phase 1: Analysis

Phase 2: Extraction

Phase 3: Validation

Phase 4: Index Generation

Naming Convention

SKILL-*.md Files (Uppercase)

Why Uppercase?

When to Compact

Workflow Process

Step-by-Step

Dependencies & Side Effects

File System Changes

Update Script Protection

Context Loading Changes

Search Changes

Integration Points

1. llmstxt-to-skill Plugin

2. Update Scripts

3. CI/CD Validation

Benefits

Performance

User Experience

Maintainability

Scalability

Success Criteria

Alternatives Considered

1. Multiple Skill Files

2. Lazy Loading Sections

3. External Documentation Only

4. Dynamic Generation

Real-World Reference

Implementation Priority

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions