Skill Context Refactor

Skill Context Refactoring (skill-context-refactor)

Refactor existing Agent Skills to dramatically reduce context window overhead, eliminate restrictive micro-management instructions (unhobble), and establish typed semantic interfaces.

Refactoring Workflow

Follow this 4-stage pipeline when refactoring any skill:

[1. Audit & Benchmark] ──> [2. Unhobble] ──> [3. Design Interfaces] ──> [4. Progressive Disclosure]

Stage 1: Audit & Benchmark

1. Measure initial metrics: line count, line count of SKILL.md, estimated token size, and count of restrictive keywords (MUST, NEVER, ALWAYS, DO NOT).
2. Identify core capability vs. auxiliary details:
   • Core Spine: Workflow steps, triggering logic, essential parameters.
   • Auxiliary: Deep domain knowledge, edge-case handling rules, long output templates, verbose examples.

Stage 2: Unhobble (Strip Micro-Regulations)

1. Eliminate micro-management rules that restrict reasoning without adding quality.
   • Before: "NEVER write more than 3 bullet points. ALWAYS use present tense. DO NOT use adjectives."
   • After: State the goal clearly and explain the rationale: "Keep summary bullet points concise and focused on actionable technical decisions so the reader can digest changes rapidly."
2. Remove redundant, duplicate, or contradictory constraints across sections.
3. Replace rigid MUST/NEVER directives with intent descriptions and boundary conditions.

Stage 3: Design Interfaces (Semantic Interface Refactoring)

1. Replace free-text example blocks with typed JSON/YAML Schemas or TypeScript/Pydantic interface specs.
2. Define explicit Enums for categorical fields (e.g. status, severity, category).
3. Specify strict contract formats for inputs, outputs, and intermediate data structures.
4. Read references/context_engineering_principles.md for schema templates and design patterns.

Stage 4: Progressive Disclosure (Lean Spine Architecture)

1. Restructure SKILL.md into a Lean Spine (<200 lines target).
2. Move auxiliary content into dedicated reference files:
   • references/schema.md or references/<topic>.md for schemas and templates.
   • scripts/ for deterministic tasks, scripts, or parsers.
3. Add explicit triggers in SKILL.md specifying when to load reference files on-demand.
4. Verify using references/refactor_checklist.md.

Verification & Metrics

After refactoring, verify against target benchmarks:

• Token / Line Reduction: Target >= 40-50% reduction in SKILL.md line count.
• Strict Interfaces: All structured outputs must have explicit schemas or Enums.
• Spine Budget: SKILL.md should be under 200 lines (hard max 300 lines).