Skip to content

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
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

1
2
3
4
5
6
7
8
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

1
2
3
4
5
6
7
8
9
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

1
2
3
4
5
6
# 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:
  2. Frontmatter (name, description)
  3. Routing table with trigger keywords

  4. Instructions to load specific guide

  5. Create routing-criteria.md from microsim-matcher:

  6. Detailed scoring methodology
  7. Ambiguity resolution rules

  8. Library capability matrix

  9. Extract guide files from original skills:

  10. Copy workflow content from each SKILL.md
  11. Preserve all step-by-step instructions

  12. Include template references

  13. 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/
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
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:
  4. "Create a timeline for US presidents" -> timeline-guide.md
  5. "Make a bar chart of sales data" -> chartjs-guide.md
  6. "Build a network diagram of dependencies" -> vis-network-guide.md
  7. 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# 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:

1
2
3
4
5
---
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