What is an agent skill?

A filesystem package for procedural context

The open Agent Skills format defines a skill as a directory whose required SKILL.md contains metadata and Markdown instructions. The directory may also carry executable scripts, detailed references, templates, images, or other assets:

release-review/
├── SKILL.md
├── scripts/
├── references/
└── assets/

The description is part of the operating contract: it tells a compatible agent what the skill does and when it is relevant. The body tells the agent how to perform the work. Supporting files keep the main instructions focused and make deterministic operations or reusable templates available when needed.

Progressive disclosure manages context

A harness does not need to place every installed procedure into every model call. A typical flow exposes compact names and descriptions for discovery, loads the full SKILL.md when a task activates the skill, and reads supporting files only when the instructions require them.

This is progressive disclosure: spend context on a capability when it becomes relevant. It reduces permanent prompt weight, but it does not make context free. Poor descriptions can trigger the wrong skill or hide the right one; oversized instructions can still crowd out task evidence; stale references can produce a confident but obsolete workflow.

Skill, tool, hook, and subagent are different

A skill primarily supplies knowledge and procedure. A tool supplies an interface for reading data or causing an effect. A hook runs at a named lifecycle event. A subagent executes a delegated loop in a separate context. A plugin may package several of these surfaces together.

A skill may explain how to use a deployment tool or include a validation script, but its prose does not grant credentials or permission. The harness must still resolve tool schemas, authorize the current principal, request approval where required, constrain execution, and record effects. Treating “the skill says to run it” as authorization would move policy into model-readable text.

The standard and the client are separate contracts

The open specification defines the portable core, including the directory and frontmatter shape. Agent products may add invocation controls, storage rules, dynamic context, subagent execution, marketplaces, or distribution packages. Those extensions are client behaviour, not automatically part of the portable format.

Write the smallest portable skill that solves the recurring task, then document any runtime dependency explicitly. Version it like code, review scripts before execution, keep secrets outside the package, and test the result in every client you claim to support.

Evaluate activation and outcomes

A skill needs more evidence than valid YAML. Use representative requests that should activate it, near-miss requests that should not, and adversarial content that tries to override its boundary. Inspect which files entered context and whether the agent followed the intended procedure without inventing unavailable tools or permissions.

Then grade the real task outcome, side effects, resource use, and recovery. A skill is useful when it improves a repeatable workflow under declared conditions, not merely when the agent can recite its instructions.