Skills

Description

A skill is a reusable capability package that tells an AI agent how to perform a specific class of work with consistent quality. Instead of relying only on a generic system prompt, a skill adds scoped domain knowledge, decision rules, and execution patterns for a concrete task.

In practical terms, a skill narrows ambiguity. It gives the agent a stronger default behavior for a known problem type, so outcomes are less dependent on one-off prompting and model improvisation.

What a skill usually contains

The exact format can differ by harness, but most skill systems include the same functional parts:

• Activation rules - when the skill should be used and for which task signals
• Task-specific guidance - constraints, best practices, anti-patterns, and quality bars
• Procedure - ordered steps for how to execute or reason through the task
• Output expectations - required structure, style, and completion criteria
• Tool usage boundaries - what tools are allowed, preferred, or disallowed

Taken together, these make a skill a small operational policy for a task domain.

Why skills matter in agent systems

Skills improve reliability by making behavior explicit and repeatable.

• Consistency - repeated task types produce more stable output quality
• Efficiency - less token budget is spent rediscovering the same approach each run
• Governance - risky actions can be constrained through explicit rules
• Composability - multiple skills can be combined to form richer workflows
• Transferability - operational knowledge moves from individuals into shared artifacts

In a multi-agent system, skills are especially important because they let specialized agents operate with differentiated behavior while still following shared standards.

Skills are a security and supply-chain boundary

Skills are also one of the easiest paths for a security incident to enter an agent system. A skill is not merely passive documentation: it can place instructions directly into the agent’s context, direct the agent to run bundled scripts, and influence how it uses credentials, tools, the filesystem, and the network. A malicious or compromised skill can therefore behave like a trusted prompt injection with an attached software supply chain.

Treat installing or updating a skill with the same care as adding an executable dependency. At minimum:

• install skills only from approved sources and review both SKILL.md and bundled files
• pin versions and verify content hashes or signatures before activation
• run skill scripts with least privilege, constrained credentials, restricted egress, and an appropriate sandbox
• record which skill version was active for each run so incidents can be traced and rolled back
• evaluate updates before promoting them across an agent fleet

The controls must sit outside the skill itself. A skill cannot be trusted to enforce restrictions against its own instructions or scripts. The structural controls in Security & Prompt Injection still define the maximum authority available to the agent.

Non-malicious skills can still fail at the environment boundary

A benign skill can be unsafe or unreliable when its system assumptions are implicit. For example, a bundled script may require Node.js or Python, depend on a minimum runtime version, invoke a system binary that is not installed, or ship a native executable built for a different operating system or processor architecture.

Current skill installers do not fully solve this dependency problem. The npx skills CLI, for example, documents skill installation as symlinking or copying skill files into an agent’s directory; it does not define a lifecycle for provisioning a required runtime or resolving the correct native binary for the host operating system and architecture. A successful install therefore does not prove that the skill can run on the target system.

Skill packages should declare their runtime, version, binary, operating-system, and architecture requirements explicitly. Installation should then perform pre-flight compatibility checks, resolve platform-specific artifacts, verify their provenance, and fail before activation when the environment cannot satisfy the contract. The Skill Format records these requirements. The Skill Gateway makes skills searchable and returns resolution and provenance metadata; a separate local installation client must enforce the host-side contract. Until that lifecycle is handled end to end, external system dependencies remain an open problem rather than an implementation detail.

Progressive Disclosure

Skills are loaded in tiers so that an agent can be aware of many skills while paying context cost only for the ones it activates:

1. Discovery only the skill’s name and one-line description are read at startup (on the order of tens of tokens each). An agent can know about dozens of skills for less than the cost of activating one.
2. Activation when a task matches, the full SKILL.md body loads. Keep the body small (a few hundred lines); push anything longer into bundled reference files.
3. Execution scripts, templates, and reference docs load only at the step that needs them.

Two consequences follow. First, the description is the router a weak description means the skill never activates, so it is the single highest-leverage field to get right. Second, progressive disclosure is why skills scale where always-on tool definitions do not: large tool/MCP schema sets degrade reasoning before a task even starts, while a skill index stays cheap as the library grows. The Skill Gateway’s search_skills/describe_skill operations are the dynamic form of this discovery tier.

Skills as Learned Procedural Memory

Skills are the system’s procedural memory the “how to do X” counterpart to the Knowledge Base’s declarative “what is true.” This reframing opens a write path: a verified, successful multi-step procedure can be distilled into a new skill and reused, the way Voyager grows a library of learned, composable skills from successful task completions. A skill that proves itself becomes durable capability rather than a one-off success.

This is the procedural side of the Minimal Bootstrap self-improvement loop: the system does not only improve its harness and prompts, it accumulates reusable competence. The open challenges are curation, deduplication, and conflict (two skills that disagree) at scale an identified build concern, not a solved one, and a reason skill evaluation and the Skill Gateway’s versioning matter.

Skills vs prompts, tools, and workflows

These concepts overlap but are not the same:

• A prompt gives immediate instructions for a single run.
• A tool gives the agent an external action surface (search, edit, run, fetch).
• A workflow defines the broader process and sequencing across stages.
• A skill bridges all three by encoding reusable task intelligence that can be invoked within a workflow using available tools.

Lifecycle of a skill

Skills should be treated as evolving operational assets, not static text.

1. Draft from observed task patterns.
2. Evaluate against real outputs and failure cases.
3. Version and distribute for shared use.
4. Refine based on execution telemetry and review feedback.

This maps directly to the Context Development Lifecycle: skills are one concrete way to package, distribute, and improve context over time.

Related Concepts

• Skill Format - Canonical on-disk structure for skill packaging and gateway metadata.
• Context - Skills are a structured way of packaging high-value context for specific tasks.
• Agent - Agents execute work; skills shape how they execute it.
• Planning and Execution - Skills help enforce planning and execution quality standards.
• Context Development Lifecycle - Skills fit the generate, evaluate, distribute, observe loop.