liveBook · Manning

Agent skill

As explained in Designing AI Agents

A packaged agent capability that specifies how to perform a class of tasks, including relevant tools and workflow guidance.

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

How Designing AI Agents covers it

How deep it goes
Details applicability contracts, isolated and coexistence gates, bounded trials, layered routing, operating evidence, and reversible withdrawal.
Examples
Uses Voyager's Minecraft JavaScript library and Claude Code's SKILL.md packages to illustrate reusable capabilities.
What you can do after
Build a versioned skill admission and routing workflow with evidence-backed gates, hard filters, abstention, and rollback.
How it connects
Connects skills to progressive disclosure, reflection, routing, evaluation, permissions, and experience replay.

Also explained in

Compare how 6 books explain agent skill →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Agents. The section links point to the parts of the book it draws on.