| name | skillopt |
| description | Bounded text-space gradient optimization for SKILL.md prompts using execution traces.
Loads low-reward traces (reward < 0.8) from .agent/traces/, groups them by skill, and applies
bounded edits (max 15% word change) with a Validation Gate to prevent destructive rewrites.
Use when you want to run the SkillOpt algorithm to automatically improve skill prompts,
or when a skill repeatedly underperforms and you want a systematic text-space optimization pass.
Triggers: skillopt, skill optimization, bounded edits, prompt gradient, validation gate, improve skill
|
SkillOpt — Bounded Text-Space Skill Optimization
Runs the SkillOpt algorithm: loads low-reward execution traces, proposes bounded edits to the
responsible SKILL.md, and checks those edits through a Validation Gate before committing.
[!IMPORTANT]
Traces must already exist in .agent/traces/ (collected via /native-trace or trace-manager).
Without traces there is nothing to analyze.
1. Run the Optimizer
# From the project root (WSL2 or PowerShell)
python -B scripts/prompt_optimization/skillopt_optimizer.py
The script:
- Reads all
*.json files from .agent/traces/
- Filters traces where
reward < 0.8
- Groups low-reward traces by
skill_used
- For each underperforming skill: proposes a bounded edit, runs the Validation Gate, and saves the
result to
outputs/skillopt/best_<skill_name>.md if the gate passes
2. Bounded Edit Budget
The optimizer enforces a learning-rate budget of max 15% word change (minimum 20 words).
If the proposed edit exceeds this budget the Validation Gate rejects it automatically.
This prevents catastrophic rewrites — only targeted, surgical improvements survive.
3. Validation Gate
After each candidate edit the gate checks:
- Edit size: rejects if word-change count > budget
- Issue resolution: verifies that feedback keywords from failed traces now appear in the
candidate (simulated pass/fail — real deployments replace this with an actual agent re-run)
A [✓] Validation Gate PASSED message means the artifact is deployable.
4. Apply the Optimized Skill
When the gate passes, the deployable artifact is at:
outputs/skillopt/best_<skill_name>.md
Review the diff, then overwrite the original:
Copy-Item "outputs/skillopt/best_<skill_name>.md" ".agent/skills/<skill_name>/SKILL.md"
5. Verify
Re-run the task that previously scored low and collect a new trace. The new reward should be ≥ 0.8.
If not, repeat the optimization loop.
Related Skills
- [[trace-manager]] — record traces and assign reward scores
- [[native-trace]] —
/native-trace workflow for capturing execution data
- [[aioptimize]] — AI-assisted prompt optimization using the same trace data
- [[skill-creator]] — create or fully rewrite a skill from scratch
⚡ Optimization Integration
When using this skill for critical tasks, run it within a /native-trace context to capture
performance data for self-improvement via /aioptimize.
