Pruning Your AI Agent Skills Library - AIXplore

# Pruning Your AI Agent Skills Library: A Practical Guide to Skill Consolidation Your AI agent's skills library grew organically. Now it's sprawling. Sound familiar? I just finished consolidating 87 Claude Code skills down to 70, and the improvements go far beyond the numbers. Here's what I learned about when to consolidate, when to archive, and when to leave things alone. --- ## The Problem: Skill Sprawl Between November 2025 and January 2026, my Claude Code skills library grew 163%—from 33 skills to 87. The growth wasn't intentional. Each skill solved a real problem. But collectively, they created new ones: - **Overlapping triggers**: Six meeting-related skills competing for the same phrases - **Redundant functionality**: Three different Gemini skills doing similar things - **Unused baggage**: CLI wrappers I'd forgotten existed - **Inconsistent quality**: Some skills following best practices, others not Anthropic's own research is clear: *"Fewer, non-conflicting skills outperform sprawling libraries."* --- ## The Audit Framework Before touching anything, I needed to understand what I had. Here's the framework I used: ### 1. Overlap Analysis Map which skills compete for similar triggers: | Category | Skill Count | Overlap Percentage | |----------|-------------|-------------------| | Meeting processing | 6 skills | 70% or higher | | Image generation | 3 skills | 80% or higher | | Email handling | 2 skills | 40% overlap | ### 2. Usage Audit Which skills actually get used? I identified three categories: - **Core workflow**: Used daily (keep and improve) - **Occasional**: Used monthly (keep, maybe consolidate) - **Unused**: Not touched in 3+ months (archive) ### 3. Quality Check For each skill: - Line count (target: under 500) - Trigger clarity (explicit `triggers:` field) - Language quality (no aggressive CAPS) - Progressive disclosure (reference files for details) --- ## Consolidation Patterns That Worked ### Pattern 1: Mode-Based Consolidation When skills do similar things with different parameters, consolidate into modes. **Before:** - `meeting-notes-processor` - Process meetings - `extracting-meeting-insights` - Analyze meetings - `action-items-tracker` - Extract action items **After:** ```yaml name: meeting-processor modes: - summary (default) - insights - action-items ``` Three skills became one, with clear mode selection based on user intent. ### Pattern 2: Feature Consolidation When skills represent features of a larger capability, merge them. **Before:** - `gemini` - Basic CLI wrapper - `generating-gemini-images` - Image generation with presets - `creating-gemini-presentations` - PowerPoint creation **After:** ```yaml name: gemini-images capabilities: - Quick image generation - Preset-based generation (blog, social, diagram) - Full presentation creation ``` The user doesn't care about the underlying distinction—they want images. ### Pattern 3: Audience-Based Consolidation When skills differ only by output audience, parameterize instead. **Before:** - `creating-manager-briefs` - Weekly brief for executives - `creating-team-updates` - Weekly digest for team **After:** ```yaml name: weekly-comms modes: - executive (manager brief) - team (team digest) ``` Same input data, different output format. One skill handles both. --- ## Language Cleanup: The Subtler Win Consolidation grabbed the headlines, but language cleanup had an outsized impact on skill reliability. ### Problematic Language Claude responds differently to aggressive language. These patterns caused issues: ```markdown # Before (problematic) CRITICAL: You MUST use this tool when... NEVER do X under any circumstances ALWAYS follow this exact pattern ``` ### Improved Language Softer phrasing, same intent: ```markdown # After (better) Use this tool when... Avoid X because... Follow this pattern for best results ``` ### The "Think" Problem Claude Opus 4.5 responds poorly to instructions containing "think"—it triggers extended reasoning when you just want action. Replace with: | Problematic Phrase | Recommended Alternative | |-------------------|------------------------| | "think about" | "consider" | | "think through" | "work through" | | "think carefully" | "evaluate" | I cleaned 8 skills of aggressive language and "think" patterns. The result: more consistent, predictable behavior. --- ## What I Left Alone Not everything needs consolidation. I kept these separate: **Document processors** (`docx`, `pdf`, `pptx`, `xlsx`): Large, specialized skills that would become unwieldy if merged. **Platform-specific tools** (`slack`, `discord`, `imsg`): Different APIs, different mental models. No benefit to merging. **CLI wrappers**: Thin skills wrapping specific tools. Added triggers but kept them separate. --- ## The Results | Metric | Before Cleanup | After Cleanup | |--------|----------------|---------------| | Total skills | 87 | 70 | | Meeting skills | 7 | 3 | | Gemini skills | 3 | 1 | | Email skills | 2 | 1 | | Skills with triggers | ~10 | 70 | | Aggressive language issues | 50+ | 0 | More importantly: skills trigger more reliably, overlap conflicts are eliminated, and the library is maintainable. --- ## Lessons Learned ### 1. Consolidate by User Intent, Not Implementation Users don't think "I need the meeting-notes-processor skill." They think "process this meeting." Design skills around what users ask for, not how you built them. ### 2. Archive Don't Delete I archived 24 skills into `_archived/`. They're still there if I need them. No data lost, clean library gained. ### 3. Triggers Matter More Than Descriptions A skill with great triggers and a mediocre description will activate correctly. A skill with a great description and no triggers will be ignored. ### 4. Progressive Disclosure Scales Large skills get unwieldy. Split them: - `skill.md` - Core workflow (under 500 lines) - `reference.md` - Detailed documentation - `templates.md` - Output templates ### 5. Audit Regularly I'm setting a quarterly reminder to audit skills. Growth happens gradually; maintenance should too. --- ## Your Turn If your agent's skill library has grown organically, try this: 1. **Count**: How many skills do you have? 2. **Categorize**: Which overlap? Which are unused? 3. **Consolidate**: Apply the patterns above 4. **Clean**: Remove aggressive language 5. **Document**: Update your improvement plan The goal isn't minimal skills—it's the right skills, well-organized, reliably triggered. --- *This consolidation was performed on Claude Code's skill library. The same principles apply to any AI agent system with modular capabilities.* --- ### Related Articles - [[mastering-clinerules-configuration|Mastering .clinerules: Advanced Configuration for AI-Assisted Development]] - [[claude-code-best-practices|Claude Code: Best Practices for Agentic Coding]] - [[making-claude-code-more-agentic|Making Claude Code More Agentic: Parallel Execution, Model Routing, and Custom Agents]] --- About the Author: Justin Johnson builds AI systems and writes about practical AI development. <a href="https://justinhjohnson.com">justinhjohnson.com</a> | <a href="https://twitter.com/bioinfo">Twitter</a> | <a href="https://www.linkedin.com/in/justinhaywardjohnson/">LinkedIn</a> | <a href="https://rundatarun.io">Run Data Run</a> | <a href="https://subscribe.rundatarun.io">Subscribe</a>