Context Design for Claude Skills: What to Include or Cut

Every token you put in front of Claude is doing one of two things: helping the model do the task, or diluting its attention. There is no neutral context. The hardest discipline in building Agent Skills is not writing good instructions — it is deciding what to leave out, because the instinct is always to add "just in case" material, and that instinct quietly degrades every response. This post is about context design: the deliberate craft of choosing what enters the window, what stays on disk, and why a leaner context almost always outperforms a fuller one.

Context is a budget, and attention is the real cost

It is tempting to think of a large context window as free headroom — Claude supports a very large window, so why not fill it? But the cost is not only tokens; it is attention. The more irrelevant material sits in context, the harder the model works to find what matters, and the more its responses drift toward the noise. A focused 800-word context routinely beats a sprawling 8,000-word one on the same task. Skills are built precisely so you do not have to choose between depth and focus: progressive disclosure lets you keep depth on disk and pull only the focused slice into context when it is relevant.

The three questions for every piece of content

Before any sentence goes into a Skill body, ask three things. Is it needed for this task, or only for some tasks? If only some, it belongs in a reference file that loads on demand, not in the always-loaded body. Does the model already know it from training? General knowledge — how JSON works, what a REST call is — wastes space when restated. And is it actionable, or merely background? Procedures and decision rules earn their place; ambient context the model won't act on usually does not. Run every line through these and bodies shrink dramatically without losing capability.

flowchart TD
  A["Candidate content"] --> B{"Needed for every run of this task?"}
  B -->|No| C["Move to reference file, load on demand"]
  B -->|Yes| D{"Already known from training?"}
  D -->|Yes| E["Cut it"]
  D -->|No| F{"Actionable, not just background?"}
  F -->|No| E
  F -->|Yes| G["Keep in SKILL.md body"]

What to keep in the body

The body should hold the irreducible procedure: the steps in order, the decision points where the model must choose, the project-specific conventions it cannot infer, and the explicit inputs and outputs. These are the things that change the model's behavior on this exact task and that it would otherwise get wrong. Keep them tight and concrete. "Validate the email column against RFC format and drop failures" is a keeper. "Email validation is important for data quality" is filler — it states a value the model already holds and gives it nothing to do.

Project-specific knowledge is the highest-value content because the model genuinely cannot know it: your naming conventions, your error codes, the one API quirk that bites everyone. That is exactly what a Skill is for. The art is including that and almost nothing else.

A practical way to find the right line is to write the body, then go through it and strike anything a competent engineer who had never seen your system would already know. "Parse the JSON response" survives only if there is something unusual about your JSON; otherwise it is noise. "The status field uses our internal codes, not HTTP codes — see codes.md" survives because it corrects an assumption the model would otherwise make wrong. The body that remains after this pass is dense with exactly the information that changes behavior, which is the information worth paying for on every trigger.

What to push to disk

Reference material is the obvious candidate: full field glossaries, exhaustive error tables, long style guides, example galleries. None of it should sit in the body, because the body pays its full cost on every trigger. Put it in files the body references conditionally — "for the complete list of status codes, read codes.md" — and the model fetches it only when a task actually touches that material. The same goes for large examples; one tight illustrative example in the body, the rest in a file. This is the within-Skill application of progressive disclosure, and it is what lets a Skill carry enormous latent depth at near-zero standing cost.

The mental shift this requires is to stop thinking of the body as the place where all the knowledge lives and start thinking of it as the place where the procedure and the pointers live. The knowledge lives on disk; the body knows where to find it. This is genuinely counterintuitive at first, because the instinct of anyone who has written a long system prompt is to put everything important right in front of the model. But "important" and "needed right now" are different predicates, and conflating them is what produces bloated, expensive, distracted agents. The discipline is to keep only the second category resident and let the runtime fetch the first on demand.

Avoiding context poisoning

A subtler failure than bloat is contradiction. When a Skill body, a Project instruction, and an MCP tool description all say slightly different things about the same behavior, the model has to reconcile conflicting signals and often picks wrong. As you layer context — Projects for standing rules, Skills for task procedures, tool schemas for interface details — keep each layer authoritative for its own concern and silent on others. The Skill should not restate the Project's standing rules, and the tool schema should not duplicate the Skill's procedure. One source of truth per fact prevents the quiet drift where two instructions disagree and the agent's behavior becomes unpredictable. This is also why pruning matters over time: stale instructions that no longer match reality are worse than missing ones.

Designing for long-running agents

In multi-turn or subagent workflows, context discipline compounds. A subagent that starts with a lean, task-specific context reasons better and returns a cleaner summary, which keeps the orchestrator's context clean in turn. Loading every possible Skill and document into every agent is the opposite of the design intent — it recreates the bloated-prompt problem you adopted Skills to escape. Let each agent pull only the Skills its slice needs, let those Skills pull only the reference files the moment demands, and the whole system stays sharp even across long, complex runs. Lean context is not a constraint you tolerate; it is the mechanism that makes capable agents reliable.

There is also a time dimension that newcomers underestimate. A long conversation accumulates: tool outputs, intermediate reasoning, earlier answers all pile up in the window as the session runs. Even if each individual addition was justified, the sum eventually crowds out the thread of the task. Designing for this means being willing to summarize and discard — collapsing a finished sub-task into a one-line result, or handing the next phase to a fresh subagent rather than dragging the entire history forward. The agents that stay coherent over long sessions are the ones whose builders treated context as something to actively curate, not just accumulate. Skills make that curation natural by keeping most knowledge off-context until the moment it earns a place.

None of this is about being stingy for its own sake. The goal is a system where, at any given moment, what sits in front of the model is precisely the material that makes the current step go well — no less, so the model is not flying blind, and no more, so its attention is not diluted. That balance is the craft. Get it right and a modest, focused context consistently outperforms a sprawling one, on quality and on cost at the same time. Skills, with their tiered loading and on-demand resources, are the tool that makes hitting that balance the path of least resistance rather than a constant fight against your own configuration.

Frequently asked questions

If the context window is huge, why not fill it?

Because attention, not token count, is the binding constraint. Irrelevant material makes the model work harder to find what matters and pulls responses toward noise, so a focused small context typically outperforms a large sprawling one on the same task.

What belongs in the body versus a reference file?

The irreducible per-task procedure, decision points, project-specific conventions, and explicit inputs/outputs go in the body, which loads on every trigger. Bulky reference material — glossaries, error tables, long examples — goes in files the body loads only when a task needs them.

What is context poisoning and how do I avoid it?

It is when overlapping layers — Project, Skill, tool schema — give the model contradictory instructions about the same thing, causing unpredictable behavior. Avoid it by making each layer authoritative for its own concern and silent on others, keeping one source of truth per fact.

How does context design change for subagents?

Give each subagent a lean, task-scoped context so it reasons well and returns a clean summary, which keeps the orchestrator's context clean too. Loading every Skill and doc into every agent recreates the bloat that Skills exist to prevent.

Sharp context, applied to real conversations

CallSphere brings this same context discipline to voice and chat agents — loading only the procedure a call needs, calling tools at the right moment, and booking work without drowning in noise. See it live at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.