Table of Contents

• When to Use

• Core Pattern: Externalize-Consolidate-Progress

• Quick Reference

• Optimization Workflow

• Key Success Factors

• Modules

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

When NOT To Use

• Skill is under 300 lines and well-organized

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

Strategy Impact When to Use

Externalize Python modules 60-70% reduction Heavy implementations (>20 lines)

Consolidate similar functions 15-20% reduction Repeated patterns with minor variations

Replace code with structured data 10-15% reduction Configuration-driven logic

Progressive loading patterns 5-10% reduction Multi-stage workflows

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

• Run automated analysis: Use optimization-patterns.py to generate optimization plan

• Review modules: Check modules/patterns.md for detailed implementation patterns

• Learn from examples: Review modules/examples.md for anti-patterns to avoid

• Apply systematically: Follow the 4-phase workflow above

• 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