Skip to content
Development
Skill

/preference-optimization

Align a fine-tuned model with preference data using DPO, ORPO, KTO, or SimPO. Use when preference pairs or thumbs-up/down feedback exist, when choosing between preference-optimization methods, or when a DPO run needs hyperparameters or debugging.

From plugin
agents
42k185 skills137 agents93 commands

Claude Code

$ npx -y skills add wshobson/agents --skill preference-optimization --agent claude-code

SKILL.md

preference-optimization.SKILL.md
name: preference-optimization
description: Align a fine-tuned model with preference data using DPO, ORPO, KTO, or SimPO. Use when preference pairs or thumbs-up/down feedback exist, when choosing between preference-optimization methods, or when a DPO run needs hyperparameters or debugging.

Preference Optimization

This skill assumes `finetuning-method-selection` already routed here because the data shape is preference pairs or unpaired thumbs-up/down feedback, not demonstrations (that's `lora-qlora-recipes`) or a verifiable reward signal (that's `grpo-rlvr-training`). What follows is method selection among the DPO family, the evidence for how much that selection actually matters, the production training pattern, and how to build the pairs in the first place.

**Input:** a routing decision (preference optimization) plus preference pairs or unpaired feedback, usually from an SFT checkpoint. **Output format:** a validated method choice plus a config — the kwarg values in `references/method-configs.md`, not free-form advice — that `llm-finetuning-training-engineer` consumes directly.

Method Selection

| Data shape | Method | Key parameters | |---|---|---| | Preference pairs, default case | **DPO** | β=0.1, LR 5e-7–1e-6, 1–2 epochs | | Memory-bound or no SFT checkpoint | **ORPO** | reference-free, fused SFT+preference in one loss | | Unpaired thumbs-up/down | **KTO** | binary label per example, no pairing needed | | Length bias observed, sweep budget available | **SimPO** | reference-free; see sweep grid below |

  • **DPO is the safe default.** Use β=0.1 and a

learning rate of 5e-7 to 1e-6 for 1–2 epochs. This LR is *lower* than the SFT LR that produced the checkpoint being aligned — porting an SFT- scale LR into a DPO run is the most common misconfiguration here, not an edge case.

  • **ORPO** routes in when memory is the

constraint, or when there's no separate SFT checkpoint to start from — it's reference-free and fuses the SFT and preference objectives into one loss, skipping the separate SFT pass and the reference-model memory cost DPO carries.

  • **KTO** routes in when feedback is unpaired

binary signal (thumbs-up/down) rather than matched preference pairs — don't force unpaired feedback into synthetic pairs to use DPO instead.

  • **SimPO** fixes DPO's length bias but only pays

off with disciplined sweeping — its published gains are a ceiling reported under a tuned sweep, not a baseline any single config will reproduce. Route here only when there's sweep budget; use DPO instead if there isn't.

  • **Classic RLHF (reward model + PPO) is retired**

outside frontier labs. Don't reach for it in a production pipeline — every method above is cheaper and better-supported for the same data shapes.

Worked Examples

  • *"We have an SFT checkpoint and clean paired

preference data, no length-bias complaints yet."* → default case → **DPO** at β=0.1.

  • *"Reviewers click thumbs-up/down per response;

nothing is paired."* → unpaired signal → **KTO**, not DPO — don't synthesize pairs to force DPO onto unpaired data.

  • *"GPU budget doesn't cover a separate SFT pass

plus a DPO reference model."* → memory-bound, no separate checkpoint → **ORPO**.

  • *"DPO output favors longer answers regardless of

quality, and there's time to run a sweep."* → length bias plus sweep budget → **SimPO**. Skip it if the sweep budget isn't actually there.

The Low-Leverage Truth

A 2026 240-H100-run study (arXiv 2603.19335) is the load-bearing evidence behind the table above: **loss-function choice is worth roughly 1 percentage point of leverage, model scale is worth roughly 50.** Zero of 20 DPO variants tested beat vanilla DPO. Rankings also **invert with scale** — a variant that wins in a small pilot can lose at deployment size.

Two practical consequences:

  • Don't spend a routing decision agonizing over

DPO-variant bake-offs. The table above is sufficient; deeper variant selection is low-leverage compared to data quality and scale.

  • **Validate at deployment scale before trusting a

ranking.** A method comparison run on a small pilot model doesn't transfer to the production size class — re-check the winner once scale changes.

This is also why the Method Selection table above is deliberately short: it encodes the ~1pp lever, not a ranking of DPO variants that the same study shows doesn't hold up across scale. Treat any variant-selection advice that isn't in that table — including advice that claims a specific variant "wins" — as unproven until it's been validated at the target deployment size.

Production Pattern: Iterative On-Policy DPO

A single offline DPO pass on a static preference dataset is a starting point, not the production pattern. The policy drifts away from the distribution the pairs were sampled from as training proceeds, and a static dataset goes stale against that drift. Production pipelines run DPO iteratively and on-policy instead:

1. Sample completions from the current policy checkpoint. 2. Score or rank the completions (reward model, judge, or task grader). 3. Run a DPO pass using the current checkpoint as the reference model. 4. The resulting checkpoint becomes both the new policy *and* the new reference for the next round.

Repeat. Each round's reference model is the prior round's output, not a fixed initial checkpoint — that's what keeps the preference signal on-policy instead of scoring against an increasingly stale distribution.

A single-pass DPO run is still a reasonable first iteration — it just isn't the whole pipeline. Plan for at least one more round once the first checkpoint exists, rather than treating pass one as the finished artifact.

Pair Construction

Build DPO/ORPO pairs from **same-task passing-vs-failing trajectories** — two attempts at the same underlying task, not unrelated best-and-worst examples pulled from different tasks. Within that trajectory set, select the rejected m

Read more
@wshobson
Ships withagents

Use one collection of plugins, agents, skills, and commands across Claude Code, OpenAI Codex CLI, Cursor, OpenCode, Antigravity CLI, GitHub Copilot, and Pi. A harness is the coding tool that loads and runs the components.

42k185 skills137 agents
Get the whole plugin

Stars on GitHub

Momentum

stars in total
42.4k
Star history of wshobson/agents on GitHub, a chart by star-history.com

Other skills on agents.

screen-reader-testing

screen-reader-testing

Test web applications with screen readers including VoiceOver, NVDA, and JAWS. Use when validating screen reader compatibility,…

@wshobson@wshobsonInstall Skill
wcag-audit-patterns

wcag-audit-patterns

Conduct WCAG 2.2 accessibility audits with automated testing, manual verification, and remediation guidance. Use when auditing…

@wshobson@wshobsonInstall Skill
multi-reviewer-patterns

multi-reviewer-pattern…

Coordinate parallel code reviews across multiple quality dimensions with finding deduplication, severity calibration, and…

@wshobson@wshobsonInstall Skill
parallel-debugging

parallel-debugging

Debug complex issues using competing hypotheses with parallel investigation, evidence collection, and root cause arbitration. Use…

@wshobson@wshobsonInstall Skill

More skills from other plugins.

brainstorming
Auto-invoked

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or…

@obra@obraInstall Skill
ask-matt

ask-matt

Ask which skill or flow fits your situation. A router over the skills in this repo.

skills12d309k
@mattpocock@mattpocockInstall Skill
accessibility
Auto-invoked

accessibility

Design, implement, and audit accessible UI to WCAG 2.2 Level AA across Web, iOS, and Android — semantic ARIA roles and labels,…

ecc13d293k
@affaan-m@affaan-mInstall Skill
compiler-commit

compiler-commit

Use when you want to verify compiler changes and commit with the correct convention. Runs tests, lint, and format, then commits…

react3d252k
@facebook@facebookInstall Skill

Questions about preference-optimization.

Which coding agents can use preference-optimization?
preference-optimization installs in Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and Windsurf with the skills CLI, using each agent's flag shown on this page. Flowy's auto-invocation, which fires a skill when your prompt matches, runs in Claude Code only.