# Claude Code Skill Consolidation Plan

> Claude Code has a hard-coded limit of 30 skills. With 36+ skills currently in use, some are being silently ignored.

- Skill: `tools-only/claude-code-skill-consolidation-plan` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/claude-code-skill-consolidation-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/claude-code-skill-consolidation-plan/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/claude-code-skill-consolidation-plan

---

# Claude Code Skill Consolidation Plan

## Executive Summary

Claude Code has a hard-coded limit of **30 skills**. With 36+ skills currently in use, some are being silently ignored. This plan consolidates related skills into **3 meta-skill dispatchers**, reducing the total from 36 to **19 skills** while preserving full functionality and optimizing token usage.

## The Problem

### Hard Limit Discovery

Claude Code enforces a maximum of 30 skills. When you exceed this limit:

- Extra skills are silently ignored (no error message)
- Which skills get ignored is non-deterministic
- Restarting Claude Code may change which skills are available

### Current State

| Metric | Value |
|--------|-------|
| Total skills | 36+ |
| Limit | 30 |
| Skills being ignored | 6+ |

## The Solution: Meta-Skill Dispatchers

A **meta-skill dispatcher** is a single skill that:

1. Has a concise SKILL.md entry point with routing logic
2. Stores sub-skill details in a `references/` subdirectory
3. Loads only the relevant guide file when invoked
4. Preserves 100% of original functionality

### Benefits

| Benefit | Description |
|---------|-------------|
| **Under limit** | 19 skills (11 headroom for future growth) |
| **Token savings** | 40-60% reduction per MicroSim request |
| **No lost functionality** | All original capabilities preserved |
| **Rollback ready** | Originals archived, easy to restore |

---

## Final Architecture (19 Skills)

### Meta-Skills Created (3)

| Meta-Skill | Consolidates | Skills Merged |
|------------|--------------|---------------|
| `microsim-generator` | MicroSim visualization generators | 13 |
| `installer` | Installation/setup skills | 3 |
| `microsim-utils` | MicroSim utility skills | 4 |

### Skills Kept Separate (16)

**Content Generators (14)** - Complex workflows that benefit from dedicated skills:

| Skill | Purpose | Size |
|-------|---------|------|
| chapter-content-generator | Generate chapter content from outlines | 64K |
| book-chapter-generator | Design chapter structure | 16K |
| quiz-generator | Create assessments with distractors | 52K |
| glossary-generator | ISO 11179 compliant definitions | 40K |
| faq-generator | FAQ generation from course content | 52K |
| reference-generator | Curate academic references | 12K |
| book-metrics-generator | Book statistics reporting | 40K |
| readme-generator | GitHub README creation | 68K |
| linkedin-announcement-generator | Social media announcements | 20K |
| course-description-analyzer | Course description validation | 12K |
| learning-graph-generator | Concept dependency graphs | 112K |
| diagram-reports-generator | Diagram status reports | 36K |
| concept-classifier | Classification quiz MicroSims | 44K |
| skill-creator | Guide for creating new skills | 48K |

**Specialized (2)** - Unique domains requiring dedicated skills:

| Skill | Purpose | Size |
|-------|---------|------|
| moving-rainbow | MicroPython for Raspberry Pi LEDs | 28K |

---

## Meta-Skill 1: microsim-generator

### What It Consolidates (13 skills)

| Original Skill | Library | Use Case |
|----------------|---------|----------|
| microsim-p5 | p5.js | Custom simulations, physics, animations |
| chartjs-generator | Chart.js | Bar, line, pie, doughnut, radar charts |
| bubble-chart-generator | Chart.js | Priority matrices, multi-dimensional data |
| timeline-generator | vis-timeline | Chronological events, history |
| map-generator | Leaflet.js | Geographic visualizations |
| venn-diagram-generator | Custom | Set relationships (2-4 sets) |
| mermaid-generator | Mermaid.js | Flowcharts, workflows, UML |
| math-function-plotter-plotly | Plotly.js | Mathematical function plots |
| vis-network | vis-network | Network graphs, node-edge diagrams |
| causal-loop-microsim-generator | vis-network | Systems thinking, feedback loops |
| comparison-table-generator | Custom | Side-by-side comparisons with ratings |
| celebration-animation-generator | p5.js | Particle effects, visual feedback |
| microsim-matcher | N/A | Routing logic (becomes the core) |

### Directory Structure

```
microsim-generator/
 SKILL.md                        # Entry point with routing table
 references/
    routing-criteria.md         # Detailed matching criteria
    p5-guide.md                 # p5.js simulation guide
    chartjs-guide.md            # Chart.js visualization guide
    timeline-guide.md           # Timeline creation guide
    map-guide.md                # Map visualization guide
    vis-network-guide.md        # Network graph guide
    mermaid-guide.md            # Flowchart/diagram guide
    venn-guide.md               # Venn diagram guide
    bubble-guide.md             # Bubble chart guide
    plotly-guide.md             # Math function plotting guide
    causal-loop-guide.md        # Causal loop diagram guide
    comparison-table-guide.md   # Comparison table guide
    celebration-guide.md        # Celebration animation guide
 assets/
     templates/                  # Shared HTML/JS/CSS templates
```

### Routing Table

The SKILL.md will use keyword matching to route requests:

| Trigger Keywords | Guide File | Library |
|------------------|------------|---------|
| timeline, dates, chronological, events, history | timeline-guide.md | vis-timeline |
| map, geographic, coordinates, latitude, longitude | map-guide.md | Leaflet.js |
| function, f(x), equation, plot, calculus, sine | plotly-guide.md | Plotly.js |
| network, nodes, edges, graph, dependencies | vis-network-guide.md | vis-network |
| flowchart, workflow, process, state machine, UML | mermaid-guide.md | Mermaid.js |
| venn, sets, overlap, intersection, union | venn-guide.md | Custom |
| chart, bar, line, pie, statistics, data | chartjs-guide.md | Chart.js |
| bubble, priority, matrix, quadrant, impact, effort | bubble-guide.md | Chart.js |
| causal, feedback, loop, systems, reinforcing, balancing | causal-loop-guide.md | vis-network |
| comparison, table, ratings, stars, side-by-side | comparison-table-guide.md | Custom |
| animation, celebration, particles, confetti | celebration-guide.md | p5.js |
| custom, simulation, physics, interactive, p5.js | p5-guide.md | p5.js |

### Workflow

1. **Analyze Request**: Scan user request for trigger keywords
2. **Match Generator**: Score against routing table (use routing-criteria.md for ambiguous cases)
3. **Load Guide**: Read the matched `references/*-guide.md` file
4. **Execute Workflow**: Follow the guide's step-by-step process
5. **Generate MicroSim**: Create files in `docs/sims/<name>/` directory

---

## Meta-Skill 2: installer

### What It Consolidates (3 skills)

| Original Skill | Purpose |
|----------------|---------|
| install-mkdocs-template | Bootstrap new MkDocs Material intelligent textbook project |
| install-learning-graph-viewer | Add interactive graph viewer to existing project |
| install-skill-tracker | Set up skill usage tracking with hooks |

### Directory Structure

```
installer/
 SKILL.md                        # Entry point with routing
 references/
    mkdocs-template.md          # Full MkDocs setup guide
    learning-graph-viewer.md    # Graph viewer installation
    skill-tracker.md            # Activity tracking setup
 assets/
     templates/                  # Installation templates
```

### Routing Logic

| Trigger Keywords | Guide File |
|------------------|------------|
| new project, mkdocs, textbook, bootstrap, setup | mkdocs-template.md |
| graph viewer, learning graph, visualization, interactive graph | learning-graph-viewer.md |
| track skills, skill usage, activity tracking, hooks | skill-tracker.md |

---

## Meta-Skill 3: microsim-utils

### What It Consolidates (4 skills)

| Original Skill | Purpose |
|----------------|---------|
| microsim-standardization | Quality scoring and validation |
| microsim-screen-capture | Automated screenshot generation |
| microsim-add-icons | Icon management for MicroSims |
| microsims-index-generator | Generate index page with grid cards |

### Directory Structure

```
microsim-utils/
 SKILL.md                        # Entry point with routing
 references/
    standardization.md          # Quality validation guide
    screen-capture.md           # Screenshot automation guide
    add-icons.md                # Icon management guide
    index-generator.md          # Index page generation guide
 assets/
     schemas/                    # JSON schemas for validation
```

### Routing Logic

| Trigger Keywords | Guide File |
|------------------|------------|
| standardize, quality, validate, score, check | standardization.md |
| screenshot, capture, preview, image | screen-capture.md |
| icons, add icons, favicon | add-icons.md |
| index page, microsim list, grid, directory | index-generator.md |

---

## Implementation Plan

### Phase 1: Create Meta-Skill Directories

```bash
# In claude-skills repo
cd /Users/dan/Documents/ws/claude-skills/skills

mkdir -p microsim-generator/references microsim-generator/assets/templates
mkdir -p installer/references installer/assets
mkdir -p microsim-utils/references microsim-utils/assets
```

### Phase 2: Build microsim-generator

1. **Create SKILL.md entry point** with:
   - Frontmatter (name, description)
   - Routing table with trigger keywords
   - Instructions to load specific guide

2. **Create routing-criteria.md** from microsim-matcher:
   - Detailed scoring methodology
   - Ambiguity resolution rules
   - Library capability matrix

3. **Extract guide files** from original skills:
   - Copy workflow content from each SKILL.md
   - Preserve all step-by-step instructions
   - Include template references

4. **Consolidate templates** into shared assets folder

### Phase 3: Build installer

1. Create SKILL.md with routing logic
2. Extract content from each install-* skill into references/

### Phase 4: Build microsim-utils

1. Create SKILL.md with routing logic
2. Extract content from utility skills into references/

### Phase 5: Update Symlinks

```bash
# Remove old symlinks
cd ~/.claude/skills

# MicroSim generators (13)
rm microsim-p5 chartjs-generator bubble-chart-generator timeline-generator
rm map-generator venn-diagram-generator mermaid-generator math-function-plotter-plotly
rm vis-network causal-loop-microsim-generator comparison-table-generator
rm celebration-animation-generator microsim-matcher

# Installers (3)
rm install-mkdocs-template install-learning-graph-viewer install-skill-tracker

# Utilities (4)
rm microsim-standardization microsim-screen-capture microsim-add-icons microsims-index-generator

# Create new symlinks
ln -s /Users/dan/Documents/ws/claude-skills/skills/microsim-generator microsim-generator
ln -s /Users/dan/Documents/ws/claude-skills/skills/installer installer
ln -s /Users/dan/Documents/ws/claude-skills/skills/microsim-utils microsim-utils
```

### Phase 6: Archive Originals

```bash
cd /Users/dan/Documents/ws/claude-skills/skills
mkdir -p archived

# Move original skills (not delete - keep for reference)
mv microsim-p5 chartjs-generator bubble-chart-generator archived/
mv timeline-generator map-generator venn-diagram-generator archived/
mv mermaid-generator math-function-plotter-plotly vis-network archived/
mv causal-loop-microsim-generator comparison-table-generator archived/
mv celebration-animation-generator microsim-matcher archived/
mv install-mkdocs-template install-learning-graph-viewer install-skill-tracker archived/
mv microsim-standardization microsim-screen-capture microsim-add-icons archived/
mv microsims-index-generator archived/
```

### Phase 7: Test

1. **Restart Claude Code** to reload skills
2. **Verify skill count**: Should show 19 skills (or fewer if some content generators weren't symlinked)
3. **Test each routing path**:
   - "Create a timeline for US presidents" -> timeline-guide.md
   - "Make a bar chart of sales data" -> chartjs-guide.md
   - "Build a network diagram of dependencies" -> vis-network-guide.md
   - etc.

---

## Token Optimization Analysis

### Before Consolidation

| Scenario | Token Usage |
|----------|-------------|
| Skill listing (30 skills) | ~1,500K potential |
| MicroSim request | Full SKILL.md loaded (~50-100K) |
| Wrong skill selected | Wasted context |

### After Consolidation

| Scenario | Token Usage |
|----------|-------------|
| Skill listing (19 skills) | ~800K |
| MicroSim request | Routing (~15K) + Guide (~20-30K) = ~35-45K |
| On-demand loading | Only relevant guide loaded |

**Estimated savings: 40-60% per MicroSim generation request**

---

## Rollback Plan

If issues arise after consolidation:

### Quick Restore

```bash
# Restore original symlinks
cd ~/.claude/skills

# Remove meta-skills
rm microsim-generator installer microsim-utils

# Restore original symlinks from archived/
cd /Users/dan/Documents/ws/claude-skills/skills
mv archived/* .

# Recreate symlinks
cd ~/.claude/skills
for skill in /Users/dan/Documents/ws/claude-skills/skills/*/; do
  name=$(basename "$skill")
  ln -sf "$skill" "$name"
done
```

### Gradual Migration

Alternatively, you can migrate one category at a time:

1. Start with microsim-utils (lowest risk, fewest skills)
2. If successful, migrate installer
3. Finally, migrate microsim-generator

---

## Future Considerations

### Dynamic Skill Loading

A future enhancement could implement a skill prediction system that:

1. Analyzes the current project type
2. Predicts which skills are most likely needed
3. Dynamically manages symlinks before Claude Code starts

### Skill Categories

Consider adding category metadata to SKILL.md frontmatter:

```yaml
---
name: skill-name
description: ...
category: visualization  # or: content, installation, utility
---
```

This could enable category-based filtering in the future.

---

## Appendix: Complete Skill Inventory

### Skills to Consolidate (20)

| Original Skill | Meta-Skill | Guide File |
|----------------|------------|------------|
| microsim-p5 | microsim-generator | p5-guide.md |
| chartjs-generator | microsim-generator | chartjs-guide.md |
| bubble-chart-generator | microsim-generator | bubble-guide.md |
| timeline-generator | microsim-generator | timeline-guide.md |
| map-generator | microsim-generator | map-guide.md |
| venn-diagram-generator | microsim-generator | venn-guide.md |
| mermaid-generator | microsim-generator | mermaid-guide.md |
| math-function-plotter-plotly | microsim-generator | plotly-guide.md |
| vis-network | microsim-generator | vis-network-guide.md |
| causal-loop-microsim-generator | microsim-generator | causal-loop-guide.md |
| comparison-table-generator | microsim-generator | comparison-table-guide.md |
| celebration-animation-generator | microsim-generator | celebration-guide.md |
| microsim-matcher | microsim-generator | routing-criteria.md |
| install-mkdocs-template | installer | mkdocs-template.md |
| install-learning-graph-viewer | installer | learning-graph-viewer.md |
| install-skill-tracker | installer | skill-tracker.md |
| microsim-standardization | microsim-utils | standardization.md |
| microsim-screen-capture | microsim-utils | screen-capture.md |
| microsim-add-icons | microsim-utils | add-icons.md |
| microsims-index-generator | microsim-utils | index-generator.md |

### Skills to Keep Separate (16)

1. chapter-content-generator
2. book-chapter-generator
3. quiz-generator
4. glossary-generator
5. faq-generator
6. reference-generator
7. book-metrics-generator
8. readme-generator
9. linkedin-announcement-generator
10. course-description-analyzer
11. learning-graph-generator
12. diagram-reports-generator
13. concept-classifier
14. skill-creator
15. moving-rainbow