The Agentic Harness

Designing Reusable Agent Skills as Composable Units

Treating skills as distinct design units prevents reuse failures and production breaks.

· 10 min read
Cover illustration for “Designing Reusable Agent Skills as Composable Units”
Harness Engineering · October 9, 2026 · 10 min read · 2,248 words

A skill is a composable package of instructions, code, and resources that an agent loads on demand, giving it a capability it did not have encoded in its weights. The field has converged on skills as the structural unit of agent behavior because they let procedural knowledge get extended without retraining a model or rewriting a system prompt. A 2026 survey on agent skills formalizes this convergence into a four-stage lifecycle: representation, acquisition, retrieval and selection, and evolution. That framing treats a skill as something designed as a building block from the outset, not something discovered after the fact by watching an agent behave well in one session and hoping the behavior generalizes.

This marks a break from an older formulation of what an agent even is. The earlier shorthand, agent equals LLM plus memory plus tools plus planning plus action, treated skill-like behavior as an emergent property of the system's other parts working together. Harness engineering rejects that premise. Placing skill as its own entry in that list, distinct from tool description and tool implementation, makes a specific claim: a skill is a separate engineering surface with its own lifecycle and its own failure modes, not a synonym for a tool or a stretch of prompt text dressed up with a name.

The payoff of treating a skill this way becomes visible at the point an organization tries to scale past a single agent built by a single team. A named, versioned, inspectable skill can be tested on its own, before it is ever composed with anything else. It can be attributed when something downstream breaks, because the trace can point to the specific skill that ran rather than to the agent as an undifferentiated whole. It can be composed deliberately, with an engineer reasoning about what it requires and what it produces, rather than accidentally, by two prompt fragments happening to coexist in the same context window. None of that is available when a skill lives only as implicit behavior inside a longer prompt. Whether a skill is ever reusable, in any meaningful sense, is decided at the moment it is defined. What decides whether reuse is possible later is the design decisions made then, not the intentions behind them.

What makes a skill genuinely reusable versus merely callable

A skill being callable in many contexts says nothing about whether it will behave correctly in most of them. Reusability and callability are different properties, and the gap between them is where agent systems quietly accumulate risk.

A 2026 study drew evidence from 138,133 public SKILL.md files across 20,556 repositories and asked what structurally separates skills that transfer cleanly into new contexts from skills that only work inside the context that produced them. The analysis identifies three structural properties as the dividing line. The second is isolated state: the skill does not silently read from or write to ambient state, whether that is a session variable, a global memory store, or context owned by the caller, unless that access is part of its declared interface. The third is narrow responsibility: the skill does one thing at the level of the procedure it performs, which is what makes it possible to test the skill, attribute a failure to it, and replace it without disturbing the skills around it.

These three properties are necessary conditions for reuse, not stylistic preferences that make a skill definition tidier to read. A skill missing any one of them can still be called successfully in a new context, but only by coincidence, when the new context happens to share the same hidden assumptions the skill was built against. The moment that coincidence breaks, the skill fails, and it fails silently, because nothing in its definition declared the assumption that was just violated. Treating these properties as optional polish misses what the corpus evidence actually shows: skills lacking them are not slightly less robust, they are reusable only by accident.

The failure modes that appear when structural decisions are deferred

Deferring a structural decision at design time does not make the cost disappear. It converts that cost into a production failure, one that costs more to diagnose than the original design work would have cost to do properly, because the failure now has to be traced backward through a running system.

The first pattern is a composability failure. A skill can work fine in isolation, and it can pass every test written against it directly. A ranked list looks like a plan. It is not one, and the gap between the two becomes visible only once execution starts, which is the most expensive possible moment for it to appear.

The second pattern is state pollution. Attribution becomes actively misleading.

The third pattern is responsibility creep. If a skill handles more than one concern, you cannot update or replace it without putting both concerns at risk at once, so the skill becomes load-bearing in ways no one declared explicitly. So every agent that calls it inherits its entire surface area of risk, including the parts of that surface the calling agent never meant to depend on.

Correctness per skill and correctness of the composed system are not the same measurement, and systems that only check the former have not checked the thing that actually matters in production.

Designing input/output contracts that hold across callers

A contract attached to a skill is only useful if a caller with zero knowledge of that skill's internals can verify it, and that requirement sets a real bar. Parameter names and a short free-text description are not enough to clear it. A contract that holds across callers has to be explicit about types, about preconditions, about postconditions, and about failure modes, stated with enough precision that verification does not require reading the skill's implementation.

A complete contract specifies an input schema with typed fields, marking which are required and which are optional, and constraining valid ranges or enumerated values rather than leaving the field open to anything that happens to parse. It also specifies declared failure modes: precisely what the skill returns or raises when it cannot complete its task, so that a composing agent can handle the failure as a distinct case.

Findings from the 2026 Task Decomposition-Guided Reranking work bear directly on how these contracts should be written. The implication for contract design is direct: a contract anchored to a narrow, specific task performs better as a routing signal than a broad capability claim does, because the narrow version gives an orchestrator something concrete to match against.

The contract, written this way, doubles as the skill's test surface. A skill with an explicit, stated postcondition can be tested by asserting that postcondition against a replay of an actual execution. The contract and the evaluation are the same artifact, examined from two different angles, and a skill definition that cannot support this kind of assertion has not specified a real contract yet, whatever its documentation claims.

State isolation as a design requirement, not an implementation detail

State isolation belongs in the skill's definition, not in a hope that the implementation will behave. It is a prerequisite for attribution: a skill that reads from or writes to ambient state makes it structurally impossible to tell, after a failure, whether the failure originated in the skill's own logic or in the state it inherited from somewhere else in the system. So without isolation, every downstream investigation starts from a position of ambiguity that no amount of logging at the agent level can resolve.

The isolation boundary needs to be explicit as part of how the skill is defined: which memory keys it reads, which keys it writes, and which it is prohibited from touching under any circumstance. Stated this way, a harness can enforce the boundary mechanically, so engineers no longer have to just assume it holds because the skill was written carefully. Where that footprint is left to be inferred instead, the granularity reasoning breaks down, because there is no reliable signal left to reason from.

A practical corollary follows from this. A skill that needs access to a large, loosely bounded slice of memory signals that it was not decomposed finely enough in the first place, and the breadth of its memory access is evidence of a second, undeclared concern hiding inside what was supposed to be one responsibility. Isolation, treated as a design requirement, makes this kind of problem visible at definition time, when it is cheap to fix, instead of after deployment, when it appears as a mysterious corruption three skills downstream.

Keeping responsibility boundaries narrow enough to be testable

The right size for a skill's responsibility is the size that lets the skill be fully validated by one clearly stated assertion. If describing the test for a skill requires stacking several independent conditions together, the skill is doing more than one thing, and the fix is to decompose it.

Skill-Pro's 2026 results, built on learning reusable skills from experience through non-parametric PPO, show markedly better cross-task and cross-agent reuse rates than episodic memory baselines achieve. Narrow scope at the point of extraction is what makes the reuse rate hold up outside the original training context.

Testability and composability turn out to be the same property viewed from two directions. A skill with one clearly bounded responsibility can be swapped for a different implementation without touching anything adjacent to it, because nothing adjacent was ever depending on its internals. A skill carrying multiple responsibilities cannot be swapped this way. Every caller has to be audited first, because no one can be sure in advance which of the skill's several jobs a given caller is actually relying on. If a skill spans several sub-tasks at once, it breaks the graph's routing logic, because the graph has no way to represent a node that is really several nodes fused together.

The most common route into this failure is incremental. Skills grow over time as edge cases get added inline, one at a time, rather than extracted out into their own separate skills. Each addition looks small and local when it happens. The accumulation is what makes the skill untestable and unattributable as a single unit, and by the time anyone notices, the skill has drifted far enough from its original scope that decomposing it back down is a much larger job than any of the individual additions ever were.

Retrieval and selection at composition time

Compositional routing, the process of decomposing an incoming query into sub-tasks and assembling the right skills into an executable plan, fails most often because the skills being matched were defined in ways that leave their relationships to sub-tasks ambiguous and their interactions with each other undeclared, even when the retrieval model doing the matching is strong. A retrieval system can only reason about what the skill definitions make legible to it.

SkillTrace's 2026 query-skill graph is a direct response to this limitation. The Task Decomposition-Guided Reranking work shows a complementary result: combining a skill's fit to a decomposed sub-task with its fit to the original query, through stage-wise reranking, improves selection quality over either signal alone. Both results depend on the same upstream condition. The skills being retrieved have to be described at the level of the sub-task they actually perform, not at the level of a broad capability claim. If a skill is described as handling document processing, a retrieval system has almost nothing to match against precisely. A skill described as extracting named entities from a structured document field gives it something concrete.

This makes the description inside a skill's definition part of its interface, not a piece of metadata bolted on for search convenience. The same logic extends to interdependencies between skills. If skill B cannot run correctly until skill A has already completed, that precondition belongs explicitly inside skill B's own contract. An orchestrator left to infer execution order by observing behavior will get that order wrong the moment it encounters a task distribution it has not seen before, because inference from behavior only ever generalizes as far as the examples it was built on.

How production traces reveal whether skill boundaries held

The only test of whether a skill's boundaries actually held is a production trace.

TelemetrySuffBench's 2026 work asks the question directly: is agent telemetry sufficient for diagnosing where a failure originated? The answer turns on whether the telemetry captures intermediate states at the boundaries between skills, not merely the final input and output of the agent as a whole. Inspecting the point where the failure surfaced is not enough.

Traces expose each of the three structural failures in a recognizable way. State pollution occurs when a downstream skill receives an input value that its declared predecessor never produced, indicating that something modified ambient state outside its declared write boundary. Responsibility creep appears as a single skill call that spans several distinct sub-task completions at once, indicating that the skill's actual scope has drifted past the boundary it was defined with. Contract violations occur when a skill returns a value whose type or shape does not match its declared output schema, indicating that a postcondition existed on paper but was never enforced in the running system.

Each of these is a structural decision from earlier in a skill's lifecycle becoming visible, for the first time, under real load. The trace does not create these failures. It only shows, honestly, whether the design decisions made when the skill was first defined were sound enough to survive contact with production.

Sources

  1. Task Decomposition-Guided Reranking for Adaptive Agent Skill Retrieval
  2. A Comprehensive Survey on Agent Skills: Taxonomy, Techniques, and Applications
  3. Skill-Pro: Learning Reusable Skills from Experience via Non-Parametric PPO for LLM Agents
  4. What Keeps Agent Skills from Being Reusable? Evidence from 138K SKILL.md Files
  5. AgentDebugX: An Open-Source Toolkit for Failure Observability, Attribution, and Recovery in LLM Agents
  6. TelemetrySuffBench: Is Agent Telemetry Sufficient for Failure-Origin Diagnosis?

More in Harness Engineering