# Model Adaptation

> Adapt prompts, skills, and agent scaffolding when the underlying model changes — currently the Claude 5 family (Fable 5/Mythos 5) vs Opus 4.x, plus the cross-vendor DeepSeek landscape. Stronger models need LESS scaffolding: this skill says what to PRUNE, what backfires (narrating reasoning trips a reasoning_extraction refusal), and what to add for long autonomous runs. Canonical home of the model & effort tiering policy (declared-provider ladder — Anthropic or DeepSeek; FreeLLMAPI carve-out) and the capability-handoff technique — extract an operating manual from a stronger model to run on a cheaper one. Use when migrating a skill to a new model, agents get refused, or picking model/effort per role. Trigger on "migrate to Fable", "Fable 5", "Mythos 5", "deepseek", "model migration", "reasoning_extraction", "tune effort", "model tiering", "long-running agent hygiene", "extract operating manual", "pxpipe", "image proxy".

- Skill: `ivy00johns/model-adaptation` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add ivy00johns/model-adaptation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ivy00johns/model-adaptation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ivy00johns (https://skillmd.com/u/ivy00johns)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ivy00johns/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](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5)
and [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices);
for DeepSeek runs, the [DeepSeek API docs](https://api-docs.deepseek.com/quick_start/pricing/)
and [Thinking Mode](https://api-docs.deepseek.com/guides/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.

| Model | Role today | What to know for adaptation |
|---|---|---|
| **Fable 5** | Frontier (Claude 5 family) | Long-horizon autonomy (multi-day runs), strong first-shot correctness, dispatches parallel subagents readily, high bug-finding recall. Runs safety classifiers (offensive cyber, bio/life-sciences, frontier-LLM development, reasoning-extraction) → can return `stop_reason: "refusal"`. Adaptive thinking only; no extended-thinking budgets; summarized-only thinking output. |
| **Mythos 5** | Frontier sibling (Claude 5 family) | Same family, same prompting patterns and refusal behavior as Fable 5. Everything here that says "Fable 5" applies to Mythos 5 unless a future note says otherwise. |
| **Opus 4.8** | Prior baseline **and the fallback target** | The model a refused Claude 5 request should reroute to. Prompts/skills tuned for it are the ones this skill helps you prune. |

### 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:

| Model | Role today | What to know for adaptation |
|---|---|---|
| **deepseek-v4-flash** | Cheap tier | Non-thinking + thinking modes; tool calls, JSON output, Anthropic-format endpoint (`api.deepseek.com/anthropic`). Cache-hit input is ~30× cheaper than cache-miss — prompt-cache hits are the dominant cost lever. |
| **deepseek-v4-pro** | Top tier | Same feature set, stronger reasoning; the reasoning-gate tier. 1M context / 384K max output across the family. |

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`)

| Pattern | What changed | The toolkit move | Enforced in |
|---|---|---|---|
| **Prune over-prescription** | Prior-model prescription degrades Claude 5 output | On migration, delete enumerations/rigid templates the model no longer needs; keep the *why*, drop the MUSTs | `skill-review` anti-pattern checklist (*"Excessive MUST/NEVER/ALWAYS"*, *"Overly rigid templates"*) — now flagged as a **model-driven** re-review trigger, not just static smell |
| **Reasoning-extraction refusal** | Telling the model to narrate/echo its reasoning as response text now trips a refusal | Never instruct "show your thinking / explain your reasoning in the output"; read structured `thinking` blocks or use a send-to-user tool instead | `skill-review` audit checklist (new anti-pattern) → detail in `references/refusal-and-fallback.md` |
| **Brief instruction > enumeration** | One instruction + the reason steers a whole behavior cluster | Prefer a short "why" over naming every behavior; don't carry the *description* field's "pushy / over-enumerate" style into *behavioral* instructions | `skill-review` audit checklist (*"Excessive MUST/NEVER/ALWAYS"* + the prior-model over-prescription trigger); `references/long-run-hygiene.md` has the drop-in brevity instruction |
| **Give the reason, not only the request** | The model connects the task to context better when it knows intent | Already a scored `skill-review` rubric dimension (*"explains WHY, not just WHAT"*) — the Claude 5 family rewards it more | `skill-review` deep-review rubric |

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:

| Pattern | What changed | The toolkit move |
|---|---|---|
| **Longer turns by default** | A single request can run minutes; autonomous runs, hours | Structure harnesses to check **asynchronously** (scheduled/poll), not block; lengthen timeouts; add progress indicators |
| **Ground progress claims** | Long runs can emit *fabricated* status reports | Instruct: audit each progress claim against an actual tool result before reporting it (distinct from the anti-*gamed-gate* rule loops already have) |
| **Don't end a turn on a promise** | Deep in a run, the model can say "I'll now run X" with no tool call, or pause to ask when it has enough | Add a last-paragraph self-check + an autonomous-operation reminder to the loop prompt |
| **Context-budget reassurance** | Surfacing a token countdown makes the model prematurely summarize / suggest a new session | Don't show the model raw budget counts; if you must, add "you have ample context, don't stop" |
| **Fresh-context verifier** | Fresh verifiers beat self-critique | **Already covered** — `loop-controller`'s GAN / Plan-Generate-Evaluate evaluator is exactly this. Cite it; don't reinvent |
| **Send-to-user tool** | Long async agents need to surface verbatim content mid-turn | Give the agent a client-side `send_to_user` tool + elicitation language |
| **Effort as the primary dial** | Effort trades intelligence/latency/cost; low effort on Claude 5 can beat xhigh on prior models | Pick effort per task: `high` default, `xhigh` for the hardest, `medium`/`low` for routine |

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

| Pattern | What changed | The toolkit move | Enforced in |
|---|---|---|---|
| **Async, long-lived subagents** | Fable 5 dispatches subagents readily; blocking on the slowest one wastes its strength | Prefer async orchestrator↔subagent comms and long-lived subagents (cache reuse) over a strict block-on-every-reply relay, where the build allows | `orchestrator` coordination rules + its `references/workflow-orchestration.md` |
| **Effort per wave/role** | Effort is the main capability dial, not just the ultracode switch | Set `xhigh` for the hardest agent (contracts, adversarial verify), `low`/`medium` for routine (docs, mechanical edits) | `orchestrator` runtime section |
| **Refusal reroute contract** | A flagged agent returns `stop_reason: "refusal"` and reroutes to Opus 4.8 | Treat as expected routing; **configure** the server/client fallback rather than assuming it; note the security-agent implication | `orchestrator` + `references/refusal-and-fallback.md` |
| **State the boundaries / don't over-refactor at high effort** | At high effort the model may tidy/refactor beyond the ask, or act when only asked to assess | When the ask is a question or a "thinking out loud", the deliverable is the assessment — report and stop; scope refactors to the task | `orchestrator` coordination rules |

## 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):

| Task class | Examples | Model | Effort |
|---|---|---|---|
| **Mechanical / high-volume** | file transforms, migration edits, formatting, lint-fix application, boilerplate, broad research crawl, first drafts | Haiku, or Sonnet if it needs light reasoning | low/medium (none on Haiku) |
| **Standard implementation** | feature code, test authoring, straightforward role-agent build work | Sonnet | medium/high |
| **Load-bearing reasoning** | architecture & contract design, adversarial verification / fresh-context evaluator, final synthesis, hard debugging, ambiguity resolution | Opus or Fable | high/xhigh (max only when correctness ≫ cost) |

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.