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