Model Adaptation

model-adaptation

The toolkit's home for what changes about your prompts, skills, and scaffolding when the underlying model changes — currently the Claude 5 family (Fable 5 + Mythos 5) succeeding Opus 4.x, plus the cross-vendor DeepSeek landscape (V4 flash/pro). It advises and audits; it does not build. skill-writer/skill-review enforce the authoring half, loop-controller the long-run half, and orchestrator the multi-agent half — this skill is where the why and the migration checklist live so those enforcement points stay in sync.

Why this skill exists

Model-adaptation guidance is the kind that rots. It's true only relative to a model generation, it cuts across every skill, and it has no natural owner — so it survives as scattered asides ("Fable 5 reroutes flagged agents", a stray /effort note) that drift out of date the moment a new model ships and nobody remembers to reconcile them. This skill is the single owner. When a new model lands, you update one landscape table here and re-run the migration audit, instead of hunting the toolkit for stale assumptions. Everything model-specific is quarantined in the Current landscape section below; the patterns are written to outlive it.

Source of record: Anthropic's Prompting Claude Fable 5 and Prompting best practices; for DeepSeek runs, the DeepSeek API docs and Thinking Mode. Re-fetch these when a new model generation ships — that's the trigger to update this skill.

The core move: a capability jump means PRUNE, not ADD

The reflex when a stronger model arrives is to write more guidance to exploit it. That reflex is usually wrong. A skill written for a weaker model is a cast made around that model's failure modes — enumerated do's and don'ts, rigid templates, anti-laziness nagging, "show your work" instructions. A stronger model has fewer of those failure modes, so the cast now constrains rather than supports it, and Anthropic measures this as a real degradation in output quality, not a wash.

So migration is mostly subtraction:

• A brief instruction now beats an enumeration. Where you once listed every bad behavior by name ("don't survey options, don't over-explain root causes, don't write narrating comments…"), one short instruction plus the reason now steers the whole cluster. Fewer words, better result. (This is why skill-review's long-standing anti-pattern — "Excessive MUST / NEVER / ALWAYS without explaining why" in its audit checklist — was already the right instinct; the newer model rewards it more.)
• Some old instructions now actively backfire. The sharpest example: telling the model to reproduce, echo, or explain its internal reasoning in the response can trip a reasoning_extraction refusal on the Claude 5 family and silently elevate fallbacks to Opus. A tactic that helped a prior model now costs you the frontier model. See The refusal landmine below.
• Trust defaults before adding a rule. The migration question is "does the model already do this well without being told?" If yes, delete the instruction and let the default carry it. Add scaffolding back only where measured behavior needs it.

The opposite is also true in one direction: long autonomous runs need new scaffolding the shorter-turn era didn't (async harness, evidence-backed progress, a send-to-user channel). Subtract the prescription; add the long-run hygiene. See references/long-run-hygiene.md.

Current landscape (update this section when a new model ships)

This is the only part meant to age. The patterns below it are durable; these facts are not.

DeepSeek landscape (cross-vendor entry)

The toolkit also runs under DeepSeek models — the 2026-08-03 deep-dive vendor review (DV-1–DV-5) was a Freebuff/DeepSeek session, and this is the first vendor this skill covers besides Anthropic. The aging facts (pricing, model versions, effort mapping) live in references/deepseek-adaptation.md; the durable shape is here:

On DeepSeek the capability dial is thinking mode + effort (none/low/high/max; xhigh and medium both map to high), not a model switch — and the chain of thought arrives in reasoning_content, a separate channel from the answer. There is no reasoning_extraction refusal classifier and no Opus fallback: refusals retry inside the DeepSeek ladder (toggle thinking, switch flash↔pro). Body triggers that route here but stay out of the description (lint band): "deepseek-reasoner", "R1", "V4", "thinking mode", "cross-vendor run".

When "the next model" (a Mythos successor, an Opus 5, a DeepSeek V5) arrives: re-fetch the vendor's current docs, update this table and references/deepseek-adaptation.md, and run the migration audit at the bottom.

The pattern catalog

Each pattern: what changed, the toolkit move, and where it's enforced so it can't drift. Depth lives in the two reference files; this is the map.

Bucket A — Authoring hygiene (enforced in skill-writer / skill-review)

The one boundary to hold explicit: the "pushy / over-enumerate" philosophy is correct for the frontmatter description (the trigger slot — you want to over-enumerate contexts to combat under-triggering) and wrong for the skill body's behavioral instructions (where over-enumeration is exactly the prescription that degrades the newer model). Same word, opposite slots. skill-writer and skill-review keep these apart.

Bucket B — Long-running agents (enforced in loop-controller / the loops)

Full drop-in instructions and where each plugs into the 5-part loop contract: references/long-run-hygiene.md. Summary:

Bucket C — Multi-agent coordination (enforced in orchestrator)

Model & effort tiering (the cost doctrine)

Buckets B and C treat effort as the primary capability dial. This section is the fuller doctrine — model and effort chosen together, per task, not per project — and it is canonical here: orchestrator (per-role dispatch and Workflow-mode stages), loop-controller (Step 6), and use-freellmapi point at this section rather than restating it.

The principle. Cost leaks when a premium model does bulk work — fan-out crawls, boilerplate, mechanical edits, first drafts — that a cheaper model in the same family does just as well. Reserve the top tier for the load-bearing reasoning: architecture/contract design, adversarial verification, final synthesis, hard debugging. Two dials on the same call: model (the cheapest tier that clears the task's quality bar) and effort (low→max; lower it for routine passes, raise it only for the hardest reasoning). Output tokens cost ~5× input across the Anthropic family, so moving bulk work down a tier and trimming output dominate every other cost lever.

The provider-relativity rule (load-bearing). One project, one provider ladder — never mix vendors to save tokens. A project declares its provider and runs the whole toolkit on that one vendor's ladder:

• Default = Anthropic-native. The ladder is Haiku → Sonnet → Opus → Fable, plus the effort dial. Read a project's declared provider from .claude/profile.yaml; absent that, assume Anthropic.
• DeepSeek-native. The ladder is deepseek-v4-flash → deepseek-v4-pro, with thinking mode + effort (none/low/high/max) as the dial within each. Full facts in references/deepseek-adaptation.md.
• The doctrine is a shape — cheapest-that-clears-the-bar for grunt work, top tier for the reasoning gate — instantiated with whatever single provider the project actually runs on, staying inside that provider's own ladder.
• FreeLLMAPI is the only multi-provider carve-out (see use-freellmapi): it deliberately aggregates free provider tiers behind one endpoint, the scarce resource is rate/quota rather than dollars, and the aggregation is the ladder.

Task → tier map (the durable part; the priced ladder lives in the reference):

On a DeepSeek project the same map instantiates as: deepseek-v4-flash with thinking off for mechanical work, flash/pro with thinking on for standard implementation, deepseek-v4-pro with thinking high/max for load-bearing reasoning — the two-model family is the ladder.

The optimizer/target split. When one model authors or optimizes an artifact (a skill, a prompt, a config) that another model then executes under, tier by role, not just task difficulty: author/optimize/review on the strong tier, execute/validate on the cheap tier. microsoft/SkillOpt's cross-model study measured why this is the economical direction — the same optimized skill gained roughly 2× more on a weaker execution model (more headroom), so "cheap deployed target + one strong optimizer" beats "strong everywhere." Detail in references/model-effort-tiering.md.

Guardrails:

• No effort param on Haiku 4.5 — the API returns a 400. Tier down to Haiku or dial effort down, not both.
• DeepSeek effort semantics differ. The API maps xhigh→high and medium→high; emit none/low/high/max (none = thinking off), and don't bother with xhigh. Thinking mode ignores temperature/top_p/penalties (accepted, no effect).
• Don't reflexively max. On the Claude 5 family high/xhigh is the sweet spot, and low effort often matches or beats prior-generation xhigh/max — so low/medium is the correct setting for routine work, not a compromise.
• Pass model and effort explicitly on every Agent/Workflow spawn. Per-agent defaults resolve to the session-start model, which goes stale the moment the user runs /model — the subagent-model footgun. This deliberately overrides the Workflow tool's generic "omit opts.model by default" guidance.
• Conciseness ≠ reasoning suppression. Output-trimming (caveman-style) is fine; instructing the model to expose its reasoning in the response trips the reasoning_extraction refusal (see the landmine below).

The priced Anthropic ladder (model IDs, $/1M, effort support), the billing-surface table, provider-relative instantiation, and the per-consumer wiring live in references/model-effort-tiering.md — like the Current landscape table above, its model and pricing facts age; update both when a new model ships.

Image-proxy model allowlist

use-pxpipe puts an image proxy in front of a session: the bulky, re-sent parts of every request are rendered into dense PNGs, because image tokens are priced by pixel area rather than characters. That only works if the model behind the proxy can actually read the render — and a model that misreads dense glyphs doesn't error, it produces confident wrong answers from garbled input. Because the failure is silent, the gate is governed here, in one place, fail-closed:

• Only allowlisted models may sit behind an image proxy. An unlisted or newly released model defaults to not allowed, no matter how capable it is otherwise — read fidelity on dense renders is a distinct, measured property.
• A model earns its slot by passing pxpipe's ~20-call glyph sweep — cheap, minutes of work. Re-run it on every model release, the same trigger that updates the Current landscape table above.
• This axis is independent of the tiering ladder. A model can be exactly the right execution tier per the optimizer/target split above and still be barred from the proxy. Choose model + effort from the tiering doctrine, then check this allowlist before enabling the proxy — two separate gates.

The current allowlist — which models pass today and their measured read rates — ages with the model generation, so it lives with the other aging facts in references/model-effort-tiering.md (Image-proxy allowlist — current state). use-pxpipe treats that list as its safety gate: it owns the wiring, this skill owns the policy.

Capability handoff (extract an operating manual)

When a stronger model is leaving the plan — or you want a cheaper model to run with a stronger model's discipline — extract an operating manual of working procedures from the strong model and run it as the cheap model's system prompt. The mechanic is real but bounded: a manual ports discipline, not capability — the prompt-level cousin of the optimizer/target split above. The hardened extractor (scripts/extract_operating_manual.py), an already-extracted manual (references/operating-manual.md, reusable as-is — on-demand only, never injected into Claude Code sessions), the three refusal/continuation/framing hardenings, and the corrected cost note live in references/capability-handoff.md.

Also reach for this section on "fable handoff", "capability handoff", "model leaving plan", or "model is going away". These triggers live in the body rather than the description because the description is held under the 950-char lint band — a body hit still routes here once the skill is open.

The refusal landmine (read this even if you read nothing else)

For a toolkit that authors prompts and skills, the highest-consequence change in the Claude 5 family is a class of instruction that now causes a refusal:

Instructions that tell the model to echo, transcribe, or explain its internal reasoning as response text can trigger the reasoning_extraction refusal category on the Claude 5 family, returning stop_reason: "refusal" and silently elevating fallbacks to Opus 4.8.

The danger is that a skill-authoring toolkit can bake this into every skill it produces ("narrate your reasoning", "show your thinking step by step in the output", "explain your chain of thought"). If your app needs reasoning visibility, read the structured thinking blocks from adaptive thinking, or surface progress with a send-to-user tool — never ask the model to reproduce its reasoning in the response. skill-review now audits for this; the full mechanics, the other classifier domains (offensive cyber, bio/life-sciences, frontier-LLM development), and the fallback configuration are in references/refusal-and-fallback.md.

On DeepSeek the classifier doesn't exist, but the instruction is still wrong. Thinking mode already emits the chain of thought in reasoning_content (a separate channel), so asking the model to also narrate its reasoning into the response doubles output tokens and buries the answer — a cost/quality failure instead of a refusal. Read reasoning_content (or the harness's structured thinking) when you need the reasoning; and since there is no Opus fallback on DeepSeek, reroute refusals inside the DeepSeek ladder (toggle thinking, switch flash↔pro). See references/deepseek-adaptation.md.

When a new model lands: the migration audit

Run this checklist against an existing skill/harness (or the whole toolkit) on a model change:

1. Re-fetch the guide. Pull the vendor's current docs — Anthropic's prompting guide, or the DeepSeek API docs for a DeepSeek project — and update the Current landscape table above and the priced ladder in references/model-effort-tiering.md (models, pricing, effort support all age). New behaviors = new audit items.
2. Subtract first. For each skill, ask per instruction: does the new model already do this well without being told? If yes, cut it. Rigid templates, anti-laziness nags, and long enumerations are the first candidates.
3. Hunt the refusal landmine. Run the audit recipe in references/refusal-and-fallback.md — that file owns the canonical grep (don't inline a variant here; divergent copies of the sweep are exactly the drift this skill exists to prevent). Every hit that routes reasoning to the response is a refusal risk — rewrite it.
4. Check the long-run scaffolding. For any loop/autonomous skill, confirm the references/long-run-hygiene.md patterns are wired: evidence-backed progress, the last-paragraph check, context-budget reassurance, effort selection, send-to-user.
5. Check the coordination scaffolding. For the orchestrator, confirm effort-per-wave, async/long-lived subagents, and the refusal→fallback contract.
6. Re-benchmark, don't assume. If the toolkit has evals (skill-creator), re-run them with and without the pruned instructions. Keep the cut only if quality holds or improves — the model updating its own approach on the fly is often better than the old rule.

Reference files

• references/deepseek-adaptation.md — the cross-vendor DeepSeek landscape: the V4 flash/pro family, thinking-mode mechanics (reasoning_content, the Anthropic-format endpoint, tool-call pass-back), the effort mapping, the provider-relative tiering instantiation, the image-proxy status, and the audit additions for DeepSeek runs. Read when a project declares DeepSeek, or when adapting any skill for DeepSeek execution.
• references/refusal-and-fallback.md — the four Claude 5 classifier domains, the reasoning_extraction landmine in depth (what trips it, the symptom, the fix, how to audit for it), the stop_reason: "refusal" contract, and server-side vs client-side fallback to Opus 4.8. Read when a skill gets refused, when writing security-agent prompts, or when auditing authored skills for the landmine.
• references/long-run-hygiene.md — the long-running-agent behavioral patterns with drop-in instruction text (verbatim from Anthropic where they published it) and where each plugs into loop-controller's 5-part contract: async turns, evidence-backed progress, last-paragraph check, context-budget reassurance, the send-to-user tool, effort tiers, and user-facing readability. Read when authoring or migrating any loop.
• references/model-effort-tiering.md — the aging half of the tiering doctrine: the priced Anthropic ladder (model IDs, $/1M, effort support), the output-token asymmetry and billing-surface table, provider-relative instantiation, the current image-proxy allowlist (which models pass the glyph sweep today), and how each consumer (orchestrator dispatch, Workflow-mode stages, loop-controller Step 6, use-freellmapi, use-pxpipe) wires the policy in. Read when assigning model+effort to roles/stages/loops, when enabling the image proxy, or when a new model ships and the ladder needs updating.