Five Documents, One Argument

Prologue: the deletion

On 24 July 2026, the Claude Code team published a short engineering post with a sentence that should have reorganised a lot of people's work: they had removed more than 80% of Claude Code's system prompt for models like Claude Opus 5 and Claude Fable 5, and their coding evaluations did not move. Not "improved slightly". Did not move.

The author was Thariq Shihipar, a member of technical staff at Anthropic, and the post is "The new rules of context engineering for Claude 5 generation models" — seven minutes, six before-and-afters, one command. It is the first of the five documents this story is about, and it sets the tone for all of them: the harness was too loud, and the model was listening anyway.

The other four arrived over the following three months: a model-specific prompting guide for Opus 5.5, a rewritten skills authoring guide, two essays on effort, and an eighteen-minute piece from the Applied AI team arguing that most agent architectures are org charts in disguise. Together they describe the same shift from five angles.

I. Unhobbling: the six myths

The context engineering post begins with an audit, not an opinion. Reading transcripts of their own internal Claude Code usage, Thariq's team saw requests arriving with several contradictory instructions in the same message — the system prompt saying "leave documentation as appropriate", a skill saying "DO NOT add comments", the user's request implying a third thing. Claude can usually infer what was meant, but it has to spend thinking on the collision first. Every clash costs time.

Their diagnosis is a word I have not seen used in vendor documentation before: unhobbling. The constraints had been added to prevent worst-case behaviour on weaker models. "While these constraints were once needed to avoid worst case scenarios, we have since found we can delete many of them and let the model use surrounding context and judgement instead."

The six before-and-afters

What the post says to do with your own setup

• CLAUDE.md: keep it light, describe what the repo is for, and "spend most of the tokens on gotchas inside of the codebase". Avoid stating the obvious. If you have several different verification instructions, make a verification skill and reference it from the file.
• Skills: lightweight guides, not warehouses. "Avoid making them overconstrained, except in highly important areas." Long skills should be split into many files.
• References: prefer files over prose — specs, mockups, entire codebases — because code is high-fidelity instruction in a language the model knows well.
• The command: the practices were shipped as claude doctor — /doctor in Claude Code — which rightsizes your skills and CLAUDE.md files automatically.

II. The whole job in one message

The second document is not an essay but a living page: "Prompting Claude Opus 5.5" in the platform docs. It opens by telling you that you probably do not need it — "Existing Claude Opus 5 prompts should perform well without changes" — and then reorganises its own advice around symptoms rather than topics. Each line is a diagnostic: if you see this, read that section.

Four things this guide changes about how you talk to the model

Thinking is always on, so effort is the first dial. Opus 5.5 returns a 400 error if you ask for thinking to be disabled. Start at medium — the default on 5.5, where Opus 5 defaulted to high — set it explicitly, and test several levels against your own evaluations rather than carrying over the setting you used before. "Reserve xhigh and max for work where you've measured a quality gain." And a detail that bites anyone changing effort mid-conversation: altering the top-level value invalidates the prompt cache, so there is a per-message effort change (beta) that keeps it.

Prompts written for a model without thinking need to be rewritten. If your integration asks Claude to write out its reasoning as a substitute for thinking, remove the instruction and read summarised thinking blocks instead. Pushing the model to reproduce its reasoning in the response can now be declined under a reasoning_extraction refusal category.

Unattended agents stop too early, and the fix is a paragraph. On long tasks, Opus 5.5 narrates progress, and some of those updates end the turn with text rather than a tool call. A loop that treats any text-only turn as "done" stops there. The guide's remedy is specific: treat a text-only end of turn as a report, keep the task's parts in a checklist, name the open items in a short follow-up, stop after two or three automatic continuations, and where you want it to keep working, add a standing instruction that names the four early-stop patterns it should not use — closing a summary by announcing the next step, offering to continue, listing decisions that block nothing, or declaring a milestone a good place to stop.

Progress updates are a protocol, not a vibe. The between-tool-call notes come back as progress-update thinking blocks, and their text is empty at the default display setting — so a client rendering only text blocks looks silent during a long turn. Set display: "updates" to receive them.

III. The library with three doors

The third document is the least quoted and the most immediately useful: "Skill authoring best practices". Its premise is structural. At startup, only the name and description of every skill is loaded. When a skill becomes relevant, Claude reads its main file. Only if a step needs more does it open the files that file points to. Three layers — and the entire art of writing a skill is to actually use all three.

• The main file is a contents page. The guide's own metaphor: it should work "like a table of contents in an onboarding guide" — when to use the skill, what the steps are, and pointers to the reference material.
• Under 500 lines for the main body, "for optimal performance". Beyond that, split.
• One level deep. "Claude might partially read files when they're referenced from other referenced files" — and then it uses commands like head -100 to preview rather than reading. Keep every reference linked directly from the main file, and give reference files longer than 100 lines their own table of contents.
• The description is the only always-loaded text you write, and it must say both what the skill does and when to use it. "Claude uses it to choose the right Skill from potentially 100+ available Skills." The anti-pattern is a description like "helps with documents"; the good ones read like triggers, written in third person to keep the point of view consistent.

IV. The dial, not the brain

The fourth item is actually two documents, and they were written two months apart because the first one left a question open. "Choosing a Claude model and effort level in Claude Code" (Lydia Hallie, Claude Code team, 7 July 2026) explains what the two settings are. "Using Claude Code: Spending your effort" (Thariq Shihipar, 25 September 2026) runs the experiments that show what they do.

Model is knowledge. Effort is work.

Lydia's framing is the clearest sentence in the whole set. The model setting "chooses the set of fixed weights" — the capability range, the things the model knows. Effort "controls how much work Claude does on your request overall", which includes how long it thinks, but also how many files it reads, how much it verifies, and how far it pushes through a multi-step task before checking in with you. Her analogy: Fable is the specialist who has seen problems almost nobody else has, Opus the expert, Sonnet a very good generalist — and effort decides how long any of them spends on your task.

Two numbers make the cost real: the high-effort path generates roughly 7× more tokens to reach a higher-confidence answer, and effort shapes token consumption but does not cap it — the only hard cap is max_tokens.

What effort actually buys, measured

Thariq ran the same prompts at different levels. An underspecified request to "build a personal fitness and workout tracker app" took 1.5 minutes at low and produced a log and a simple graph; at max it took 67 minutes and produced something with a heat chart. A lightly specified design task: 1 minute at low, 28 minutes at max, "a mockup that looked very much like Claude Code, along with a bunch of walkthroughs for different flows". A highly specified build task behaved very differently — the models converged, 16 / 22 / 33 / 79 minutes, similar designs. Specification and effort are substitutes to a degree.

The harder evidence comes from Terminal-Bench 3.0, and it is the part worth remembering because it is negative as well as positive:

Across the benchmark, raising effort reduced failures from missing edge cases but did not fix a wrong approach — the failures in the "picked the wrong reading" bucket barely moved. Pass rates by domain, Fable 5.1 at low → top effort: security 64% → 87%, hardware 34% → 75%, ML 54% → 73%, science 41% → 61%, software 43% → 56%, media 18% → 30%, operations 12% → 22%.

The rules of thumb, from both documents

And the loop Thariq says he actually uses for feature work: let Claude interview you about the spec, implement on low, review, iterate on low, then verify and test on high. When something still goes wrong, Lydia's heuristic is the one to keep: ask whether it did not try hard enough (skipped a file, skipped the tests → raise effort) or did not know enough (had everything, tried, still wrong → move to a bigger model).

V. The org chart that shouldn't be an org chart

The fifth and longest document is the one most likely to be misquoted: "Building agents: When to fold subagents into your main agent loop" (Diane Sarkis, 18 minutes, 22 October 2026). It is not an argument against subagents. It is an argument against using subagents to reproduce your company.

The word is frequently, and the article is careful with it. What follows is a taxonomy of how enterprise agent architectures go wrong: context that gets lost in the back and forth ("a telephone game"), subagent sprawl with hundreds of overlapping agents and no owner, the Frankenprompt where every team adds a sentence to the system prompt until the rules conflict and the voice is gone, evals that are over-optimised for one team's subtask, and latency — one customer measured a multi-agent harness against a single loop and the loop ran roughly 2× faster.

When subagents still earn their place

1. A single agent loop hits measurable performance degradation from context bloat.
2. Tasks genuinely run in parallel with fresh, discardable context windows.
3. One agent struggles to select tools, or the system prompt contains conflicting instructions.

Two design rules do most of the work elsewhere in the article. The first is divide by context, not by problem type: give each subagent work that needs little from the rest of the system and have it hand back a compact result — independent research paths, clean component interfaces, black-box verification. The second is the tool limit: once you exceed 30–50 tool definitions, tool choice degrades, so group tools by user intent rather than one tool per API, and use deferred loading with tool search.

The migration, in the order they suggest

• Build an eval first. One shared end-to-end set owned by a central team, with small sets shipped by each team that owns a skill. "Even a set of 10 golden examples is enough to start."
• Call subagents as tools before rewriting anything — this gives you a baseline without structural change, though it keeps the lossy summaries and the nested latency.
• Fold one subagent at a time: turn its prompt into a skill, its API calls into MCP tools, and compare with and without. "Keep it as a subagent only if the folded version scores worse."
• Run every task more than once. Their own example: folding one subagent lowered latency but broke a process that had been passing, and the break showed up in one run out of two.
• Read which tasks flipped, not just the final score. The concrete failure: the main agent answered on its own without asking the shipping specialist for the delivery date.

Its closing line is the thesis of all five documents, said plainly: "As models get more capable and agents get longer running, more of your subagents can be skills and tools… Build a small end-to-end eval, fold in one subagent, and keep it as a subagent only if the folded version scores worse, then rinse and repeat."

Epilogue: the harness shrinks

Put the five side by side and the disagreement disappears. A system prompt loses 80% of its text because the model can read context. Prompting advice becomes "give the whole job and then leave it alone", because the model can hold a specification. Skills move reference material out of the always-loaded layer, because the model can ask. Effort becomes a per-task dial instead of a global maximum, because the model's thoroughness is now a parameter. And agents collapse into loops with skills, because the loop can carry the plan it is executing.

What survives is worth naming, because it is what the shrinking does not touch:

• Gotchas. The context post is explicit: the tokens left in your CLAUDE.md should be spent on things the model would get wrong without being told. Judgement cannot invent your business rules.
• Verification that has to be blind. Black-box checking — reviewing work without seeing how it was made — remains a legitimate reason to keep a separate agent, and a legitimate reason to run one twice.
• Parallelism. Fifty independent tasks still want fifty contexts.
• Measurement. Every one of the five documents resolves an argument with an eval, a benchmark run, or a transcript audit. The subagents piece ends with the only durable instruction: "measure, change one thing at a time, and keep what holds up."

📚 The five documents at a glance

🛠 What to change on Monday

1. Run /doctor in Claude Code and let it rightsize your skills and CLAUDE.md. Then read what it kept and ask of every line: is this a gotcha, or is it something the model can see for itself?
2. Write one message with the whole job — goal, audience, what good looks like, the inputs, and the completion condition — and delete any sentence that tells the model to double-check or to be careful.
3. Split your biggest skill into a contents page under 500 lines plus reference files linked one level deep, and rewrite its description as "what it does, when to use it", in the third person.
4. Set effort explicitly to the model's default, then drop to low for drafting and raise to high only for verification, where the edge cases live.
5. Take your most convoluted agent design, build ten golden examples, and fold one subagent into a skill plus tools. Run each example twice. Keep the subagent only if the folded version scores worse.

🔑 Key takeaways

• Five documents, one thesis: as the model gets more capable, the harness should shrink. Anthropic's own numbers — 80% of Claude Code's system prompt deleted, no measurable eval loss — are the proof of concept.
• Rules become judgement. "Never write comments, one line max" became "write code that reads like the surrounding code". A rule that is wrong sometimes is worse than a principle that is right generally.
• Examples constrain. Few-shot tool examples were the top tip a year ago; on Claude 5 they narrow the exploration space. Design the interface — enums, expressive parameters — instead of demonstrating it.
• Progressive disclosure is the single mechanism behind three of the five documents: skills load in layers, tools defer their definitions, and CLAUDE.md becomes a tree of files rather than a warehouse.
• Skills have a shape: a contents-page main file under 500 lines, references exactly one level deep, a table of contents in long references, and a description that says both what it does and when to use it — because that description is all Claude sees when choosing among 100+ skills.
• Model and effort answer different questions: did it not know enough (bigger model) or did it not try hard enough (higher effort). Model is capability; effort is how many files it opens and how far it goes before checking in.
• Effort buys edge-case testing, not good ideas. 1.5 minutes versus 67 minutes on the same prompt; 0/5 to 5/5 on tasks with hidden edge cases; and almost no improvement when the model picked the wrong approach in the first place.
• Start at medium and set it explicitly. High effort is roughly 7× the tokens, the default moved between model generations, and max is for work where you have measured a gain.
• Most agent architectures are Conway's law wearing a diagram. Subagents survive in exactly three cases — context bloat, real parallelism, tool/instruction overload — and black-box verification is the one job that keeps earning a separate agent.
• Everything is settled by measurement. Ten golden examples are enough to start, run each at least twice, and read which tasks flipped rather than the average score. Change one thing, keep what holds.

🔗 Sources

Every claim in this piece comes from one of the five documents below; the originals are the thing worth reading, and all of them are linked in full.

• The new rules of context engineering for Claude 5 generation models — Thariq Shihipar, 24 July 2026, 7 min
• Prompting Claude Opus 5.5 — Claude Platform docs (see also Prompting Claude Opus 5, whose patterns remain the starting point)
• Skill authoring best practices — Claude Platform docs
• Choosing a Claude model and effort level in Claude Code — Lydia Hallie, 7 July 2026
• Using Claude Code: Spending your effort — Thariq Shihipar, 25 September 2026, 8 min (benchmark task links: Terminal-Bench 3.0)
• Building agents: When to fold subagents into your main agent loop — Diane Sarkis, 22 October 2026, 18 min
• Referenced tools: /doctor and the effort parameter, /skill-creator and /skill-doctor, and the multi-agent Claude API skills used by the migration kit