Skills & Instruction Packs

Every engineering team has at least one procedure it trusts completely and documents badly: the four-step migration one senior engineer always runs by hand, the review pass that catches the failure mode nobody wants to see twice, the release checklist that lives half in a wiki page and half in muscle memory. The procedure works. What doesn’t scale is the knowledge of it — a new hire gets walked through it once, an agent gets told about it fresh in a prompt, and six months later the wiki page is stale and the muscle memory belongs to one person.

Asking an agent to run that procedure on demand exposes a mechanical problem underneath the organizational one. A team could paste the full procedure into the system prompt of every session, guaranteeing the agent always has it — at the cost of every session paying that context bill whether or not the task at hand needs it. Or the team could leave the procedure undocumented for agents entirely, available only if someone remembers to explain it fresh each time. Neither scales, and the shape of the problem should already be familiar: it is the same static-versus-just-in-time tension this Library’s second volume worked through for file contents, one level up, applied to instructions themselves.

What a skill actually is

The mechanical answer the field converged on is the skill: a self-contained bundle — typically a folder holding an instruction file plus whatever scripts or resources the procedure needs — that a harness can discover without loading into every session by default. Anthropic’s Agent Skills announcement, which established the pattern as an open standard rather than a single-vendor feature, describes skills as “organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks.” Claude Code’s own documentation frames the trigger for building one in blunter, more familiar terms: create a skill “when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact.”

The mechanism that makes this cheap is progressive disclosure applied to a metadata layer first. A skill’s front matter — name and description — is small enough that a harness can keep every installed skill’s metadata resident without much cost, the way a table of contents costs nothing to leave open while the chapters themselves stay closed. Only when a task actually calls for a given skill — the model judging it relevant, or a person invoking it directly by name — does the full instruction file, and whatever it references, get read into context. Anthropic states the savings plainly: an agent “doesn’t need to read the entirety of a skill into their context window when working on a particular task” that skill isn’t relevant to. Claude Code’s docs put the same point in cost terms: unlike a standing instruction file, “a skill’s body loads only when it’s used, so long reference material costs almost nothing until you need it.”

Progressive disclosure of instructions

This is the same argument Volume II made for file contents, aimed at a different target. There, the case was that a harness reading an entire repository into context before the first tool call wastes the window on files that will never matter to the task at hand, and that giving the agent a directory listing and a read tool instead lets it fetch only what turns out to be relevant — the pattern the literature calls progressive disclosure. Skills apply the identical discipline to procedures rather than files: a team can install a hundred of them — a migration runbook, a release checklist, a dozen review passes for different parts of the codebase — and the harness pays the context cost of exactly the ones a given session actually invokes, never the other ninety-nine sitting idle on disk.

The isolation spectrum

Skills solve the packaging problem, but they don’t solve every problem a team runs into when it wants an agent to do more than follow one procedure in the foreground. Sometimes a task genuinely benefits from being pursued somewhere the main conversation can’t see: a broad search through an unfamiliar codebase, a debugging session that will chase two or three wrong theories before finding the right one, work that would otherwise flood the primary session with intermediate noise nobody needs to reference again. The field’s answer is a spectrum of increasing isolation and parallelism, and each point on it trades shared context for independent capacity.

A subagent is the first step up in isolation: a specialized assistant that runs in its own context window with its own system prompt, tool access, and permissions, works a delegated task, and returns a summary to the main conversation rather than the transcript of everything it tried. What the subagent read, the dead ends it explored, the tool output it sifted through — none of that lands in the parent’s window; only the distillation does. Claude Code ships three built-in subagents — Explore, Plan, and a general-purpose worker — alongside the ability to define custom ones, and the stated intent is explicit: keep large explorations out of the primary context, or run focused research in parallel without paying for it twice in the same window.

Agent teams sit at the far end of the spectrum, and as of this writing they remain explicitly experimental in at least one major harness, gated behind an opt-in flag. Where a subagent works within a single session and reports only to the parent, a team is multiple independent sessions — a lead plus teammates — each holding its own full context window, coordinating through a shared task list and messaging each other directly rather than filtering everything through one summary. A person can address any teammate directly, not just the lead. The trade is real: a team costs meaningfully more tokens than either a skill or a subagent, because every teammate is a separate running instance rather than a delegated task that folds back into one.

A subagent reports back a summary. A teammate is someone you can just talk to.

On the line between delegation and coordination

Choosing a point on the spectrum

None of this is a menu to reach for by preference. Choosing a point on the isolation spectrum is itself an engineering decision, with a cost curve as real as any infrastructure choice, and the field’s own guidance skews conservative by default. A well-scoped skill is the cheapest way to package a procedure a team already trusts — reach for it first, and reach for it by name whenever the procedure is genuinely known rather than novel. A subagent earns its isolation cost when a task benefits from exploring somewhere the parent can’t see: a search broad enough to generate noise nobody will reference again, an investigation likely to chase a couple of wrong theories before the right one surfaces. Agent teams earn their much larger cost only when the underlying work is genuinely parallelizable into units independent enough to run concurrently but still needing to coordinate — a rarer shape than it first appears, and one this Library’s sixth volume takes up directly under the heading of when not to reach for multiple agents at all.

The instinct to reach for the most capable-sounding option first is understandable and usually wrong. A skill costs almost nothing extra and handles the overwhelming majority of “we already know how to do this” work. A subagent is worth its isolation the moment a parent session would otherwise be flooded with exploration nobody will reread. An agent team is worth its multiple, when the work really does split into independent, coordinating pieces — and not, as it more often turns out, when a single conversation just needed to be asked more clearly.