Skip to main content
skill CX Codex

skill-optimizer · rohitg00 — Claude Code skill: features and installation

The skill-optimizer skill proposes edits to a SKILL.md based on stored corrections, then checks candidates against held-out examples before accepting changes.

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-optimizer does

skill-optimizer turns corrections stored in pro-workflow’s SQLite database into examples for refining a skill. An optimizer model proposes bounded edits; an evaluator scores each candidate against a separate validation set. A candidate is accepted only when it meets the score threshold. The process changes Markdown, not model weights.

A skill needs at least 8 learn-rule entries before this loop has material to work with. The selected provider must have an explicitly configured API key: set it in the plugin configuration dialog, or use PRO_WORKFLOW_*_API_KEY variables for a standalone CLI installation. The default spend cap is 0.50 USD, and candidate content is capped at 2000 tokens. Without a configured provider key, the loop cannot run.

The validation set stays fixed for the duration of a run, and rejected edits are saved so they can inform later proposals. Create ~/.pro-workflow/STOP to halt the loop between steps. An accepted candidate overwrites SKILL.md; run and validation records remain in SQLite.

What it helps with

  • refine a skill using corrections collected over time
  • reject edits that fail to improve the validation score
  • cap the number of additions, deletions, and replacements per step
  • halt an optimization run between steps

Example prompts for the agent

  • Run /skill-optimize <slug> for a skill with accumulated corrections.
  • Optimize review-helper with a 0.50 USD budget.
  • Stop the optimization loop before its next step.

How to install skill-optimizer

1Plugin marketplace

/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow

This installs the whole pro-workflow plugin with all its skills

2Skills CLI (Vercel)

npx skills add rohitg00/pro-workflow --skill skill-optimizer -a claude-code

3Manually: put the files in place

~/.claude/skills/skill-optimizer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/skill-optimizer/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about skill-optimizer

How do I install skill-optimizer in Claude Code?

In a Claude Code session, run /plugin marketplace add rohitg00/pro-workflow first, then /plugin install pro-workflow@pro-workflow.

What does skill-optimizer do?

It proposes SKILL.md edits based on stored corrections and scores them against a separate validation set. Only candidates that meet the acceptance threshold are applied.

What does skill-optimizer need before it can run?

The skill needs at least 8 learn-rule entries, and the selected provider needs an explicitly configured API key.

Source text

SKILL.md · MIT
---
name: skill-optimizer
description: SkillOpt-flavored offline training loop for any SKILL.md. Treats accumulated learn-rule corrections as training trajectories, proposes bounded patches via an optimizer LLM, gates each candidate against a held-out validation set built from the user's own past corrections, and ships only candidates that demonstrably improve the score. Inspired by Microsoft SkillOpt's ReflACT pipeline (rollout → reflect → aggregate → select → update → evaluate) adapted to pro-workflow's SQLite store. Use when a skill has accumulated 8+ learn-rule rows and the user wants the skill itself to get better, not just longer.
user-invocable: true
---

# Skill Optimizer

Train an existing SKILL.md the way a deep-learning optimizer trains weights: via rollouts, gradient-like reflections, validation-gated acceptance. No model retraining; only the skill markdown changes.

## When to use

Use this skill when:
- A pro-workflow skill has accumulated 8+ learn-rule rows for it
- The user reports the skill is "getting bloated" or "rules keep being repeated"
- The user wants offline, budget-capped improvement over multiple sessions

Do not use when:
- Skill has fewer than 8 trajectories (nothing to learn from)
- The user wants real-time edits (this is offline, single-shot)
- No key has been explicitly configured for the selected provider

## Architecture (mirrors SkillOpt's six-stage loop)

```text
rollout      pull recent learnings from SQLite (existing learn-rule rows)
reflect      optimizer LLM analyzes a minibatch, proposes add/delete/replace patches
aggregate    vote-merge patches across minibatches
select       clip by LR budget (default: 3 adds, 2 deletes, 3 replaces per step)
update       apply selected patches to a candidate skill content
evaluate     evaluator LLM scores candidate against held-out validation items
gate         accept candidate only if weighted score >= current + acceptThreshold
slow update  at epoch boundary, consolidate accepted edits into a coherent rewrite
```

Failed candidates are stored in a rejection buffer and fed back to the next reflect step so the optimizer doesn't propose the same patch twice.

## Run it

In a plugin session, use the `providers` MCP server's `run_provider_task` tool with `task: "optimizer"` and `args: ["--slug", "<slug>", "--budget-usd", "0.50"]`. Keys come from the plugin configuration dialog. Standalone CLI installations use explicit `PRO_WORKFLOW_*_API_KEY` variables. See [provider configuration](../../references/provider-configuration.md); never request keys in chat or retrieve existing machine credentials.

```bash
/skill-optimize <slug> [options]
```

Options (all optional; sensible defaults shown):

| Flag | Default | Notes |
|---|---|---|
| `--epochs N` | 3 | Outer loop count |
| `--batch-size N` | 8 | Trajectories per minibatch |
| `--minibatches N` | 2 | Minibatches per epoch |
| `--holdout N` | 6 | Validation items reserved (max ~25% of trajectories) |
| `--budget-usd X` | 0.50 | Hard cap; loop aborts when spent |
| `--optimizer-model M` | `claude-sonnet-5` | Reflect + slow-update model |
| `--evaluator-model M` | `claude-haiku-4-5` | Gate model (cheaper) |
| `--max-adds N` | 3 | LR budget per step |
| `--max-deletes N` | 2 | |
| `--max-replaces N` | 3 | |
| `--accept-threshold X` | 0.0 | Minimum score delta to accept candidate |
| `--max-skill-tokens N` | 2000 | Hard cap on candidate length |
| `--slow-every N` | 2 | Epochs between consolidation passes |
| `--json` | off | Machine-readable output |

Kill switch: `touch ~/.pro-workflow/STOP` aborts the loop between steps.

## Output

- Candidate accepted → SKILL.md overwritten, hash stamp appended in HTML comment
- Run details persist in `optimization_runs`, `optimization_candidates`, `optimization_patches`, `optimization_rejections`
- Validation set persists in `optimization_validation` (reusable across runs)

Inspect after:

```bash
sqlite3 ~/.pro-workflow/data.db "SELECT id, skill_slug, initial_score, best_score, accepted_steps, rejected_steps, spent_usd FROM optimization_runs ORDER BY id DESC LIMIT 5"
```

## Rules

- Validation set is frozen at run start. Never re-derive from new corrections mid-run.
- One candidate per step. No parallel branches.
- Slow-update output is itself a candidate; it must pass the gate to replace the best.
- The optimizer LLM and evaluator LLM may be different models. Mixing a strong optimizer with a cheap evaluator is the SkillOpt-recommended config.
- If `spent_usd >= budget_usd` at any step boundary, the loop ends with `stopped_reason="budget exhausted"`.
- Patches whose anchor is no longer present in the skill (because a prior patch in the same step removed it) are recorded as rejected with reason `anchor_missing`.

## Provenance

Inspired by Microsoft SkillOpt (arXiv:2605.23904). The six-stage rollout/reflect/aggregate/select/update/evaluate pipeline, LR budget, rejection buffer, and slow / meta update mechanics are adapted to pro-workflow's existing SQLite + learn-rule data plane. No SkillOpt code is reused. "ReflACT" is not a SkillOpt term and is not used here; the loop is referred to by stage names only.

© Rohit Ghumare · MIT · rohitg00/pro-workflow

Similar skills

All skills for Agent setup: memory, context, orchestration →

skill-optimizer by other authors comes first.

skill-optimizer mcollina skill-optimizer is a Claude Code skill for refining other skills and testing how models follow their instructions. Use it while editing skill packs, investigating regressions, or setting release checks. CX Codex +1 1,400installs token-optimizer D4kooo token-optimizer — a procedure set for OpenClaw agents: isolate background tasks, run local RAG, and consolidate context with Reset & Summarize before it balloons. CX Codex +1 507installs skill-miner hqhq1025 skill-miner is a Claude Code skill that scans session history for recurring workflows and drafts skill candidates. It builds a backlog from actual usage rather than guesswork. CX Codex +1 ★ 195repo stars prompt-optimizer getsentry prompt-optimizer — a skill that rewrites system and agent prompts against a set of eval cases instead of gut feeling. Useful when a prompt exists but behaves inconsistently. CX Codex +1 2,500installs hyperloom-workload-optimizer amd hyperloom-workload-optimizer bootstraps Hyperloom on an AMD Instinct host and kicks off multi-agent throughput optimization for LLM serving. Useful when a model on MI300X, MI325X or MI355X needs to push more tokens per second. CX Codex +1 1,200installs cost-optimizer curiositech cost-optimizer monitors cumulative LLM expenses across DAG execution and downgrades model tiers or skips optional nodes to prevent budget overruns. CX Codex +1 143installs agent-topology-optimizer ngophatneknha The agent-topology-optimizer Claude Code skill optimizes swarm layouts and communication between agents. It evaluates topology options, routing, and agent placement. CX Codex +1 ★ 189repo stars

From the same set83

The whole set →
batch-orchestration batch-orchestration decomposes large codebase changes into independent units and runs parallel agents in isolated git worktrees. CX Codex +1 ★ 2,966repo stars insights insights turns your pro-workflow history into numbers: edits per session, rules you actually apply, mistakes that keep coming back. Useful when you want to see where the agent keeps slipping. CX Codex +1 ★ 2,966repo stars doctor doctor scans your pro-workflow and Claude Code setup: checks hooks, database, context usage, MCP servers, and git state. Spots broken hook scripts and settings conflicts before they cause problems. CX Codex +1 ★ 2,966repo stars thoroughness-scoring thoroughness-scoring rates implementation choices from 1 to 10 and prompts the agent to pick thorough solutions with tests and typing over brittle shortcuts. CX Codex +1 ★ 2,966repo stars agent-teams agent-teams is a Claude Code skill that coordinates multiple sessions through shared tasks, messaging, and file locks. Teammates work in parallel on separate parts of the codebase. CX Codex +1 ★ 2,966repo stars sprint-status sprint-status tracks parallel Claude Code sessions and prevents confusion by enforcing session headers and standardized status lines. CX Codex +1 ★ 2,966repo stars skill-router The skill-router skill maps pro-workflow skills and commands to jobs, with guidance on when to use each and whether a person or the agent starts it. Use it when you’re unsure what fits. CX Codex +1 ★ 2,966repo stars permission-analyst permission-analyst analyzes permission prompts and auto mode denials, recommends permissions rules and autoMode entries. Use it when prompts slow you down or auto mode keeps falling back to confirmations. CX Codex ★ 2,966repo stars

Project sponsors

Companies that keep this analytics open