optimize-skill

Workflow

Follow these 5 steps in order. Copy this checklist into your response and check off each step as you complete it:

Task Progress:
- [ ] Step 1: Read the target skill
- [ ] Step 2: Run the quality checklist
- [ ] Step 3: Identify optimization opportunities
- [ ] Step 4: Apply optimizations
- [ ] Step 5: Validate improvements

Step 1: Read the Target Skill

Read the target skill's SKILL.md and all files in its reference/ directory (if any).

Collect these metrics:

• Total line count of SKILL.md
• Total line count across all reference files
• Frontmatter fields present vs. missing
• Number of reference files and whether all are linked from SKILL.md

Report these metrics to the user before proceeding.

Step 2: Run the Quality Checklist

Score each item in the quality checklist as PASS, FAIL, or N/A: -> See quality-checklist

Present the full scorecard to the user before making any changes. Ask for confirmation to proceed with optimizations.

Step 3: Identify Optimization Opportunities

Review all FAIL items from the checklist. Prioritize by impact (highest first):

1. Description quality — Most common cause of skill not being invoked. Fix first.
2. Content compression — Remove knowledge the agent already has. Reduces token cost and noise.
3. Progressive disclosure — Split oversized SKILL.md into reference files, or merge tiny reference files back.
4. Structure clarity — Improve headers, cross-references, and flow. Numbered steps for workflows.
5. Consistency — Fix terminology, formatting, and style inconsistencies.
6. Triggering precision — Under-triggering: add keywords, trigger phrases, concrete use cases. Over-triggering: add negative triggers ("Do NOT use for X"), narrow the scope.

List each optimization opportunity with:

• What is wrong
• Why it matters
• What the fix will be

Step 4: Apply Optimizations

For each issue identified in Step 3, apply the fix. Use compression techniques where applicable: -> See compression-techniques