Designing Agent Skill Schemas for Reusability

What a Skill Actually Is, and Why the Wrench-vs-Manual Distinction Matters

Most teams building AI agents conflate three things, and that confusion costs them months. A prompt gives an agent instructions. A tool gives it a primitive action it couldn't otherwise perform, like calling an API or reading a file. A skill is neither. A skill is a reusable operational package that governs when a behavior runs, how it runs, and when it stops.

A wrench expands what you can physically do. A repair manual takes the actions you already have and organizes them into a repeatable procedure, with sequencing and failure handling already baked in. Tools are wrenches. Skills are repair manuals. The agent already has hands; the skill tells it what to do with them in a specific situation, in a specific order, and when to put the wrench down.

The formal definition is S = (C, π, T, R): activation condition, execution policy, termination criterion, reusable interface. Each missing layer produces a different, specific failure mode. A skill without an explicit termination criterion keeps running. One without a well-specified activation condition fires on the wrong tasks. One without a composable interface can never be called by anything downstream. The structure isn't academic formalism. It maps exactly how skills break in production.

The clearest early proof that this matters came from Voyager, the GPT-4-powered Minecraft agent Wang et al. published in 2023. It accumulated a growing library of reusable programs over its lifetime with no gradient updates, no fine-tuning, just a well-organized skill library it could draw on. It unlocked key tech-tree milestones up to 15.3 times faster than prior methods. The mechanism is real: a growing, well-organized skill library compounds. An agent that can reuse what it already knows gets dramatically more capable without touching the underlying model.

The Four Structural Layers of a Skill and What Each One Carries

I'll cover these in the order they get neglected, not the order they appear in the formula — because that's the order they'll hurt you.

T, the termination criterion, is the most neglected and the source of the most dramatic failures. What triggers a halt? What triggers a handoff to a human? What signals an error state versus a retry? Most teams leave this unwritten. The result is runaway execution: an agent that keeps going because nobody told it when to stop. I've watched this corrupt real data on real systems, for entirely preventable reasons.

R, the reusable interface, is the input-output contract. What does this skill accept? What does it emit? Can a downstream skill or another agent call it without reading its internals? A skill without a composable interface is a dead end in a workflow. A single-use prompt with extra steps.

C, the activation condition, is the routing key. It maps the agent's current context to a yes-or-no decision: is this skill relevant right now? If the condition is vague, the agent guesses. When agents guess at skill selection, they fail in ways that are genuinely hard to diagnose, because the downstream problem looks like a reasoning error when it's actually a routing error. Different problem, different fix. You can spend a week debugging reasoning when the actual issue is a two-line activation condition that's underspecified.

π, the execution policy, is where most teams spend all their time, which is the wrong allocation. This is the numbered procedure, the decision tree, the domain-specific corrections to mistakes the model makes without guidance. The critical word is concrete. "Query the users table carefully" is not an execution policy. "The users table uses soft deletes; every query must include WHERE deleted\_at IS NULL" is. One sentence, one class of silent errors, permanently eliminated. The best execution policies I've encountered read like annotated post-mortems: here's what went wrong, here's the correction, here's why it applies every single time.

Teams write a serviceable execution policy and neglect everything else. That pattern, pretty reliably, is why skills fail to travel outside the context where they were written.

How the SKILL.md Format Embodies Those Layers in a Deployable Package

The SKILL.md format gives the four-layer model a concrete, deployable shape. A skill lives in a directory, my-skill/, with SKILL.md as the only required file, plus optional scripts/, references/, and assets/ subdirectories. The SKILL.md itself is YAML frontmatter with a name and description, followed by a Markdown body. A production template covers six sections: Purpose, Inputs, Context to Load, Procedure, Output, and Failure Modes.

The description field does two jobs: it drives automatic activation (the runtime uses it to decide when to invoke the skill) and human discovery (colleagues use it to find the skill when they need it). Write it with the actual trigger phrases your team uses in conversation, not abstract capability labels. "Resolve an on-call alert for a latency spike in the payments service" will activate correctly and be found correctly. "Provides incident response capabilities" will do neither.

The Failure Modes section is where T, the termination criterion, lives in the actual file: missing inputs, tool failures, scope ambiguity, conditions that require escalation. This is the primary structural difference between a skill and a prompt. No Failure Modes section means you've written a prompt, and the prompt will eventually run past the edge of the map.

Keep the full body under 5,000 tokens. The reason for that constraint becomes clear once you understand how loading works.

Why Token Economics Force a Three-Tier Loading Model and How That Shapes Skill Writing

Context windows are not infinite, and even large ones degrade performance when filled indiscriminately — in ways that are easy to miss until you're debugging something subtle at 2 a.m. with logs that don't quite explain what happened.

The SKILL.md architecture addresses this through three-tier progressive disclosure. At startup, only the name and description load for each installed skill, roughly 30 to 50 tokens per skill. The full body loads only when a skill is triggered. Reference files in the references/ subdirectory load only when the execution policy explicitly calls for them during a run. With 50 skills installed, startup overhead runs around 1,500 to 2,500 tokens total. The model stays clean until something actually needs to execute.

Scripts in the scripts/ directory are particularly efficient for a precise reason: when the agent executes validate\_form.py, only the script's output enters the context window. The code itself doesn't. Deterministic sub-tasks belong in tested, versioned scripts, not in the procedure body. The signal that something belongs in a script is simple: if execution traces show the agent reinventing the same logic across multiple runs, extract it, test it, and bundle it.

This architecture implies a writing discipline that cuts in both directions. The SKILL.md body must be self-contained enough to handle the common case without reaching for reference files on every run. At the same time, edge-case content must stay out of the base body. Inflate it with content that only one-in-ten runs needs, and you're paying a token tax on the other nine. Every time. For the lifetime of the skill.

Where Skills Sit Relative to MCP, Tools, and Multi-Agent Orchestration

The Model Context Protocol standardizes how agents connect to external data sources and tools through a JSON-RPC interface, with tools, resources, and prompts as its three primitives. It operates at a different layer entirely from skills.

Skills and MCP are orthogonal. A skill can instruct the agent to invoke a specific MCP server, interpret the response according to domain-specific rules, and define fallback behavior if the connection fails. The skill governs the procedure; MCP governs the plumbing. They compose cleanly because they solve different problems; conflating them produces architectures where nobody is sure who owns failure handling.

A skill is also not a sub-agent. It's a procedure that runs inside a single agent's context. Multi-agent orchestration sits above that layer and can invoke skills as capabilities, roughly the way a manager delegates to a specialist who already knows the procedure. The architectural pattern that has emerged is: workflows for orchestration, skills for specialization. Hybrid architectures replaced monolithic single-agent designs not because they're more impressive but because separation of concerns produces systems maintainable past the first month.

Cross-platform portability is real, but it carries a caveat better learned from the page than from a failed deployment. Execution environments vary, especially around network access and package installation constraints. A skill that requires outbound network access and runs in an environment where that's restricted will fail, and without explicit handling, the failure won't be graceful. Compatibility metadata must be explicit in the skill, not assumed.

There's no built-in versioning mechanism in the base format. Updating a skill's behavior immediately affects every application using it. Production deployments need an explicit directory-based versioning strategy (something like skills/v1/ and skills/v2/), maintained deliberately before multiple teams depend on the same library, not after.

What Curation Actually Means and Why Generated Skills Don't Substitute for It

SkillsBench produced a finding that should genuinely reorient how teams approach skill authoring: zero-shot-generated skills provide no benefit on average. Not marginal benefit. No benefit. Agents equipped with curated, human-authored skills, on the other hand, consistently outperform the no-skill baseline across evaluated tasks.

The structural reason for this gap isn't format compliance. Generated skills and curated skills often look similar on the surface, same headings, same sections, similar length. The difference is in the executable content: domain knowledge derived from actual experience with the actual system. The SkillFlow analysis found that high-quality skills contain significantly more actionable steps and more of the specific corrections that only come from having been wrong before, in that system, under those conditions.

A skill synthesized from your team's post-mortems, runbooks, and 2 a.m. Slack threads will outperform one synthesized from a generic article, every time. Emerging approaches like SkillGen and SkillX treat real execution trajectories — successful and failed — as the primary source of skill content, distilling what the agent actually did into the procedure and failure modes. The lived execution is the ground truth.

Curation is also not a one-time authoring event. Environments change. APIs change. Schemas change. The soft-delete gotcha that was accurate six months ago does not necessarily reflect the current state of the database. Skills need feedback loops from real execution to stay accurate, and someone needs to own that loop explicitly, not as a side responsibility. Without ownership, skills drift from the reality they're supposed to encode. A skill that hasn't been updated since the system it describes last changed is a fossil with good formatting.

How Skill Overlap Degrades a Library and What to Do Before Adding the Next Skill

Library size and library quality are not the same thing, and confusing them is expensive. Research on skill libraries points to a performance threshold somewhere in the range of 50 to 100 skills for tested models, beyond which performance degrades sharply.

The failure mode that overlap produces is subtle, and subtle is the dangerous kind. Two skills from the same capability family, using the same domain vocabulary and roughly the same procedure shape, but one points to a stale resource, skips a precondition, or applies the wrong version of a check. The agent chooses between them. The choice can look defensible enough to escape notice in review. The error propagates quietly across every subsequent run that triggers the wrong skill.

The public skill directories with millions of entries are an existence proof that scale without curation produces noise, not capability.

Before adding any new skill, check semantic overlap against the existing library. If similarity to an existing skill exceeds a meaningful threshold, the decision is to merge or differentiate, not to add. Merging requires resolving which version is accurate and deprecating the other, actually deprecating it, not leaving both in place and hoping the agent picks correctly. Differentiating requires making the activation conditions genuinely distinct. A near-duplicate left unresolved is technical debt that compounds silently and fails ambiguously.

For libraries that have grown well past the productive threshold, flat lookup is insufficient. Hierarchical routing with confusability-aware mechanisms becomes necessary. Depth beats breadth. A single agent with a small, deep, well-curated library can match the performance of multi-agent frameworks that distribute work across many specialized agents. Quality returns more than quantity — the opposite of the instinct most teams follow.

Governance Properties That Let Skills Cross Team Boundaries Safely

Provenance and observability are prerequisites for any skill that crosses team boundaries — not nice-to-haves. Each execution should emit structured metadata: what data sources were accessed, what parameter values were used, what intermediate outputs were produced, what decision points were reached. This is what makes a skill auditable, debuggable, and reproducible by someone who wasn't in the room when it was written. Without it, a shared skill is a black box that breaks in places you can't see, at times you can't anticipate.

Policy laundering is an anti-pattern that's more common than teams acknowledge. A skill that rephrases a destructive operation as "cleanup," or encodes a permission it doesn't actually have as a default assumption, bypasses governance controls that exist for real reasons. The execution policy must encode the actual governance requirement, the actual approval gate, in the actual place it belongs.

The description field functions as a governance surface as well as a technical one. A skill that can't be found by the team that needs it will be rebuilt. Rebuilt skills are uncoordinated duplicates with different quality levels and failure modes, contributing directly to the overlap problem and eroding the library you built. Descriptions written with real trigger phrases prevent that redundant work before it starts.

A governed skill registry converts individual expertise into organizational capability. Once a skill is published and discoverable in a shared registry, the marginal cost of a second team using it approaches zero. Without a registry, every team rebuilds the same procedures independently, and the organization never accumulates the compound benefit a growing skill library should produce.

The connection between permissions and portability is where this gets concrete. A skill that reads from access-controlled data sources must respect those permissions when it runs in a different team's environment. A skill that silently succeeds with the wrong access level is a liability. Compatibility metadata and explicit permission requirements are what make portability safe rather than merely possible.

Before publishing a skill to a shared registry: validate against real execution traces, document failure modes explicitly from those traces, set compatibility metadata including network and permission requirements, establish a versioning path before publication rather than after. Then confirm the description passes the routing test: ask someone who didn't write the skill to find it using only the language they would naturally use. If they can't, the description isn't doing its job and the skill isn't ready to travel.