Optimizing Large Skills

Optimizing Large Skills

Systematic methodology for reducing skill file size while preserving functionality through separation of concerns and strategic code organization.

When to Use

Symptoms that trigger this skill:

• Skills-eval validation shows "[WARN] Large skill file" warnings
• SKILL.md files exceed 300 lines
• Multiple code blocks (10+) with similar functionality
• Heavy Python implementations inline with markdown
• Functions >20 lines embedded in documentation

Quick Analysis:

# Analyze any skill file for optimization opportunities
python skills/optimizing-large-skills/tools/optimization-patterns.py \
  skills/path/SKILL.md --verbose --generate-plan

Core Pattern: Externalize-Consolidate-Progress

Transformation Pattern

Before: 654-line skill with heavy inline Python implementations After: ~150-line skill with external tools and references

Key Changes:

• Externalize heavy implementations (>20 lines) to dedicated tools
• Consolidate similar functions with parameterization
• Replace code blocks with structured data and tool references
• Implement progressive loading for non-essential content

Quick Reference

Size Reduction Strategies

File Organization

skill-name/
  SKILL.md              # Core documentation (~150-200 lines)
  modules/
    examples.md         # Usage examples and anti-patterns
    patterns.md         # Detailed implementation patterns
  tools/
    analyzer.py         # Heavy implementations with CLI
    config.yaml         # Structured data
  examples/
    basic-usage.py      # Minimal working example

Optimization Workflow

Phase 1: Analysis

• Identify files >300 lines
• Count code blocks and functions
• Measure inline code vs documentation ratio
• Find repeated patterns and similar functions

Phase 2: Externalization

• Move heavy implementations (>20 lines) to separate files
• Add CLI interfaces to externalized tools
• Create tool directory structure
• Add usage examples for each tool

Phase 3: Consolidation

• Merge similar functions with parameterization
• Replace code blocks with structured data where appropriate
• Implement progressive loading for non-essential content
• Update skill documentation to reference external tools

Phase 4: Validation

• Verify line count <300 (target: 150-200)
• Test all externalized tools work correctly
• Confirm progressive loading functions
• Run skills-eval validation to verify size reduction

Quick Decision Tree

Is skill >300 lines?
├─ No → Continue as-is (well-organized skills don't need optimization)
└─ Yes → Analyze composition
    ├─ Has heavy code blocks (>20 lines)?
    │  └─ Yes → Externalize to tools/ with CLI (60-70% reduction)
    ├─ Has repeated patterns?
    │  └─ Yes → Consolidate with parameterization (15-20% reduction)
    ├─ Has structured config data embedded?
    │  └─ Yes → Extract to config.yaml (10-15% reduction)
    └─ Has non-essential details?
       └─ Yes → Use progressive loading (5-10% reduction)

Key Success Factors

DO:

• ✅ Always add CLI interfaces to external tools
• ✅ Keep core concepts inline in SKILL.md
• ✅ Consolidate related functionality
• ✅ Include working examples
• ✅ Test all tools have correct references

DON'T:

• ❌ Externalize without CLI (hard to use/test)
• ❌ Create too many small files (increases complexity)
• ❌ Remove essential documentation (reduces discoverability)
• ❌ Add complex dependencies (hard to maintain)
• ❌ Skip usage examples (unclear tool usage)

Next Steps

1. Run automated analysis: Use optimization-patterns.py to generate optimization plan
2. Review modules: Check modules/patterns.md for detailed implementation patterns
3. Learn from examples: Review modules/examples.md for anti-patterns to avoid
4. Apply systematically: Follow the 4-phase workflow above
5. Validate results: Run skills-eval to confirm optimization success

Modules

• Detailed Patterns - Externalization, consolidation, and progressive loading implementation details
• Examples & Anti-Patterns - Real-world impact, common mistakes, and rationalization prevention

Result

Expected Outcome:

• 50-70% line count reduction
• 40-60% token usage reduction
• No skills-eval warnings
• Clear separation of concerns
• Maintainable external tools with CLI interfaces