skill-optimize — Claude Code command for training skills
skill-optimize runs an offline optimization loop over a skill's accumulated examples, proposes improvements to its description file, validates candidates, and updates only when performance strictly improves.
MIT ★ 2,966 updated 2026-09-29
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflowWhat skill-optimize does
The command collects stored examples (learnings rows) for a given skill, splits them into training and held-out validation sets, then iterates through reflection, aggregation, and scoring. Each candidate improvement is tested against validation examples; if it beats the baseline weighted score, the command updates SKILL.md and records the new hash.
You need at least 8 existing examples in learnings for the skill to start. An API key must be configured—either through the plugin's setup dialog or via environment variables (PRO_WORKFLOW_ANTHROPIC_API_KEY, PRO_WORKFLOW_OPENAI_API_KEY). The plugin directory requires at least one successful npm run build run.
Flags control spending (--budget-usd), iteration count (--epochs), and model selection for generation and evaluation. The loop exits when budget runs out, no improvement occurs, a kill switch file (~/.pro-workflow/STOP) is created, or all epochs complete.
What it helps with
- improve a skill's description based on real usage patterns
- validate proposed changes before writing SKILL.md
- limit optimization costs with USD budget caps
- stop training immediately via a signal file
Example prompts for the agent
- Train pro-workflow with default settings
- Retrain wiki-research-loop with 1 USD budget and 5 epochs
- Optimize wrap-up using Claude Opus for suggestions and GPT-4o-mini for validation
How to install skill-optimize
1Plugin marketplace
/plugin marketplace add rohitg00/pro-workflow/plugin install pro-workflow@pro-workflow2Manually: put the files in place
.claude/commands/skill-optimize.mdCall it with /skill-optimize. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/skill-optimize.mdCall it with /prompts:skill-optimize. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/skill-optimize.prompt.mdManually: put the files in place
.gemini/commands/skill-optimize.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about skill-optimize
How do I install skill-optimize in Claude Code?
Run /plugin marketplace add rohitg00/pro-workflow, then /plugin install pro-workflow@pro-workflow. The command will be available as /skill-optimize.
What does skill-optimize do?
It collects stored examples of a skill in use, automatically proposes refinements to its description, validates them against held-out data, and updates the file only if the new version scores higher.
What do I need to run skill-optimize?
At least 8 examples must exist in learnings for the skill. You need a configured API key (Anthropic or OpenAI) and one successful npm run build in the plugin directory.
Source text
skill-optimize.md · MIT
--- description: Train a skill's SKILL.md by running a SkillOpt-flavored offline loop over accumulated learn-rule corrections --- # /skill-optimize - SkillOpt-flavored offline training Run an offline, budget-capped optimization loop over a skill's accumulated `learn-rule` trajectories. Proposes bounded patches via an optimizer LLM, validates each candidate against a held-out portion of the same trajectories, and overwrites SKILL.md only when the candidate strictly improves the weighted score. ## Quick Start ```text /skill-optimize <slug> [--epochs 3] [--budget-usd 0.50] ``` ## What it does 1. Pulls recent `learnings` rows scoped to the skill slug (or global) 2. Splits them into train + validation (~25% holdout, freezes validation set) 3. Runs `epochs` x `minibatches` rounds of: reflect → aggregate → clip → apply → evaluate → gate 4. Stops on: budget exhausted, kill switch (`~/.pro-workflow/STOP`), no improvement, or epochs done 5. If any candidate beat the baseline, overwrites SKILL.md and stamps the new hash ## Requirements - 8 or more existing `learnings` rows for the slug - A key configured for the selected provider in the plugin configuration dialog, or a corresponding `PRO_WORKFLOW_*_API_KEY` variable for standalone CLI use - `npm run build` has been run in the pro-workflow plugin directory at least once In a plugin session, invoke `run_provider_task` on the `providers` MCP server with `task: "optimizer"` and the requested runner arguments. See [provider configuration](../references/provider-configuration.md). ## Examples ```text /skill-optimize pro-workflow /skill-optimize wiki-research-loop --budget-usd 1.0 --epochs 5 /skill-optimize wrap-up --optimizer-model claude-opus-5-5 --evaluator-model gpt-4o-mini ``` The third example mixes providers. The CLI infers the provider from the model id (`claude-*` → anthropic, `gpt-*` / `o*` → openai), so you do not need `--evaluator-provider openai` for `gpt-4o-mini`. Pass an explicit `--optimizer-provider` / `--evaluator-provider` to override inference. See [skills/skill-optimizer/SKILL.md](../skills/skill-optimizer/SKILL.md) for full mechanics, defaults, and the SkillOpt provenance.
© Rohit Ghumare · MIT · rohitg00/pro-workflow