Optimizing Large Skills

Overview

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

Use analysis tool: python tools/optimization-patterns.py SKILL.md --generate-plan

File Organization

skill-name/
  SKILL.md              # Core documentation (~150-200 lines)
  tools/
    analyzer.py         # Heavy implementations
    controller.py       # Control logic
    config.yaml         # Structured data
  examples/
    basic-usage.py      # Minimal working example

Implementation

Analysis & Planning

# Generate comprehensive optimization plan
python skills/optimizing-large-skills/tools/optimization-patterns.py \
  your-skill.md --verbose --generate-plan

# JSON output for automation
python skills/optimizing-large-skills/tools/optimization-patterns.py your-skill.md --output-json

Externalization Pattern

Move heavy implementations to tools with CLI interfaces:

• Functions >20 lines → dedicated tool files
• Always include argparse CLI interface
• Add if __name__ == "__main__" execution block
• Provide help documentation and JSON output options

Consolidation Pattern

Merge similar functions with parameterization:

• Identify repeated logic patterns
• Create unified functions with method parameters
• Replace multiple code blocks with single configurable function

Progressive Loading Pattern

Use frontmatter for focused context loading:

• Set token_budget: 25 for optimized skills
• Enable progressive_loading: true for conditional content
• Use <!-- progressive: feature --> blocks for optional sections

Common Mistakes

Rationalization Prevention

Violating the letter of the rules is violating the spirit of the rules.

Red Flags - STOP and Start Over

• "I'll optimize this one file manually"
• "Let me just extract the big functions"
• "The methodology doesn't apply here"
• "I'll come back and fix it properly"
• "The existing structure is fine"
• "No time for proper tools"

All of these mean: Stop. Re-read the skill. Apply the full methodology.

Optimization Checklist

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

Real-World Impact

Before optimization:

• growth-management skill: 654 lines (6 code blocks, 12 Python functions)
• Skills-eval: [WARN] Large skill file warning
• Loading time: High (full context usage)
• Maintainability: Poor (everything mixed together)

After optimization:

• growth-management skill: 178 lines (3 tool references, 0 inline functions)
• Skills-eval: OK No warnings
• Loading time: Low (focused context)
• Maintainability: Excellent (separation of concerns)

Result: 73% size reduction while preserving all functionality through external tools and progressive loading patterns.

Anti-Patterns to Avoid

Narrative Documentation

"During the session on 2025-11-27, we discovered that context growth was problematic..."

Template Code

Don't create fill-in-the-blank templates in the skill itself - put them in examples/

Multiple Languages

One excellent Python example beats mediocre JavaScript and Go examples.

Tool References

"For advanced pattern analysis, use tools/analyzer.py with appropriate context data."

Focused Scope

Each tool should do one thing well with clear parameters and outputs.