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

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

Final Architecture (19 Skills)

Meta-Skills Created (3)

Skills Kept Separate (16)

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

Specialized (2) - Unique domains requiring dedicated skills:

Meta-Skill 1: microsim-generator

What It Consolidates (13 skills)

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:

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)

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

Meta-Skill 3: microsim-utils

What It Consolidates (4 skills)

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

Implementation Plan

Phase 1: Create Meta-Skill Directories

# 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

# 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

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

After Consolidation

Estimated savings: 40-60% per MicroSim generation request

Rollback Plan

If issues arise after consolidation:

Quick Restore

# 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:

---
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)

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