optimizing-large-skills

通过外化、整合与渐进式加载模式，系统化地缩减技能文件的大小。适用于技能代码行数超过300行、包含多个功能相似的代码块（10个以上）、Python代码大量嵌入Markdown、函数长度超过20行并被嵌入其中时使用。切勿在技能代码行数低于300行、且代码结构清晰有序时使用此技能。若需创建新技能，请改用模块化技能。当技能评估显示“技能文件过大”的警告时，请参考此技能。

SKILL.md

--- frontmatter

name: optimizing-large-skills
description: Systematic methodology to reduce skill file size through externalization,
  consolidation, and progressive loading patterns. Use when skills exceed 300 lines,
  multiple code blocks (10+) with similar functionality, heavy Python inline with
  markdown, functions >20 lines embedded. Do not use when skill is under 300 lines
  and well-organized. creating new skills - use modular-skills instead. Consult this
  skill when skills-eval shows "Large skill file" warnings.
token_budget: 25
progressive_loading: true
version: 1.4.0

•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:

bash

# 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

code

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

code

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

Table of Contents