Skip to main content
command CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow
Open on GitHub

What 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-workflow

2Manually: put the files in place

.claude/commands/skill-optimize.md

Call it with /skill-optimize. For all projects use ~/.claude/commands/

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

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set83

The whole set →
module-map The module-map skill builds a compact map of an unfamiliar codebase area, covering entry points, core modules, data flow, and callers. Use it when you need to get oriented. CX Codex +1 ★ 2,966repo stars parallel Run multiple Claude Code sessions in parallel with isolated git worktrees. Ideal for working on features, testing, and code review simultaneously without file conflicts. CX Codex +1 ★ 2,966repo stars session-handoff session-handoff generates a structured handoff document capturing git state, open tasks, decisions, and a resume prompt for your next session. CX Codex +1 ★ 2,966repo stars replay-learnings The replay-learnings skill searches project memory and similar sessions for lessons tied to a new task. Run it before coding to bring earlier corrections into view. CX Codex +1 ★ 2,966repo stars orchestrate orchestrate coordinates multi-phase feature development with research, planning, gated implementation, and code review in Claude Code. CX Codex +1 ★ 2,966repo stars debugger debugger is a Claude Code subagent that investigates difficult bugs, failed tests, and runtime errors. It traces the cause before proposing a code change. CX Codex ★ 2,966repo stars auto-setup The auto-setup skill detects your project type and automatically configures linters, type checking, tests, and formatting. Use it when starting work on an unfamiliar codebase. CX Codex +1 ★ 2,966repo stars wiki-query wiki-query queries local markdown wikis indexed by wiki-builder using SQLite FTS5 BM25 retrieval. It delivers top passages with citations so the agent builds on existing notes. CX Codex +1 ★ 2,966repo stars

Project sponsors

Companies that keep this analytics open