An agent skill is a reusable capability package for a class of tasks. It combines discovery metadata and instructions or executable logic with an interface, dependencies, and a version. A runtime selects an applicable skill for a new task; a general solver remains available when no admitted skill fits. section 7.4 section 10.5
Skills reduce repeated reasoning and tool work, but a successful run is not proof of a general capability. A procedure may depend on a particular environment, compete with other skills, or route the wrong tasks. Treat extraction from a trace as a proposal, not an automatic promotion. section 7.4.1 section 7.4.5
A production skill needs an applicability contract and an admission path:
- Record the supported task family and inputs, selection conditions, required permissions and dependencies, expected outputs and checks, supporting evidence, stable identity, and version. section 7.4.1
- Test the candidate against a baseline in isolation, then alongside the active library for routing and coexistence regressions. Preserve hard regressions even when an aggregate score improves. section 7.4.1
- Run a bounded, observable trial before activation. Require durable evidence for each gate; a failed trial returns the skill to candidate status. section 7.4.4
- Route only among active skills that meet task, risk, permission, and dependency constraints. Narrow the legal set using evidence, and abstain or use the general solver when selection is unsupported. section 7.4.4 section 7.4
Table 7.7 Skill admission states
|
State
|
Traffic
|
Evidence held
|
Next decision
|
|
Candidate
|
None
|
Source traces, contract, isolated and coexistence results
|
Revise, reject, or begin trial
|
|
Trial
|
Bounded and observable
|
Passed offline gates plus trial outcomes
|
Activate or return to candidate
|
|
Active
|
Allowed by routing policy
|
Complete admission record and operating evidence
|
Keep, refine, merge, demote, or deprecate
|
The admission states distinguish evidence collection from bounded trial traffic and active routing. section 7.4.1
Progressive disclosure limits context pressure: in Claude Code, visible names and descriptions provide a discovery layer, the SKILL.md body loads when used, and referenced files load as needed. Startup cost depends on descriptions and listing settings, so measure it with the context inspector rather than assuming a fixed saving. Loading a skill does not itself authorize its tool calls or production changes. section 3.4.5 section 6.3.2 section 7.4.6
Maintain skills as a portfolio. Record eligible and selected versions, dependencies, outcomes, latency, cost, failures, and corrections; review duplicates, misroutes, conflicts, and dependency changes. Low use warrants review, not automatic demotion: a rare security or incident-response skill may remain critical. Withdrawal should retain evidence and a rollback path, with authorized approval for consequential scope changes. section 7.4.5
Voyager skill library
After a successful Minecraft task, Voyager stores a verified JavaScript program and retrieves relevant programs for later tasks. Complex skills can compose simpler ones. This demonstrates reuse, but a stable game environment does not establish how skills behave when production dependencies, traffic, and neighboring skills change. section 7.4





