Agent Skills
Table of Contents
1. Summary
A skill in agent tooling is a document that an assistant loads in order to
perform a kind of work. Anthropic specifies the format used by Claude Code: a
directory containing a SKILL.md file, whose frontmatter carries a name and a
description and whose body holds the instructions the assistant follows. Other
agent tools read the same format.
This page separates two things that are easily conflated. The first is the specification: what the format requires, published informally as prose documentation rather than as a grammar. The second is a set of empirical observations about how published collections use it, none of which the specification requires. ORE Studio owns neither, and the page states no project policy. For the narrower definition this project adopts, and for the academic and practitioner literature on the construct, see Skills in the Compass Skill Framework.
2. Detail
2.1. Purpose
The construct exists because of two properties of the underlying LLM. A model recalls its training imperfectly and cannot distinguish a confident recollection from an absent one. It also holds only what its context window carries, and retains nothing between sessions.
Procedural knowledge that an assistant must apply reliably therefore cannot be left to recall. It must be supplied as text the model reads at the moment it is needed. A skill is that text, together with the conditions under which it should be read.
2.2. The Specification
A skill is a directory. It contains a SKILL.md file and any supporting files
to which that file refers.
The frontmatter carries two required fields. The name field supplies the
identifier a user types. The description field states what the skill does and
the circumstances in which it applies. A disable-model-invocation flag
restricts the skill to invocation by a person.
The body holds the instructions. The specification fixes no length, imposes no internal structure, and requires no relationship between one skill and another.
That permissiveness is what makes the next section necessary.
2.3. Empirical Observations
In this section we identify several approaches found in published skill collections, none of which the specification requires. The specification defines a container and leaves its contents to the author, so how a skill is written cannot be derived from it and must instead be observed.
Our observations are drawn from Claude Code's own documentation and from three collections: pstack, the Matt Pocock skills, and the Council of High Intelligence. We examine three axes on which the collections make choices: how they organise a collection by invocation, how they manage the cost a skill body imposes on the context window, and what length they settle on. The sample is small and the field is a few years old, so we report regularities rather than established practice.
2.3.1. Invocation as an Organising Axis
The specification supplies the disable-model-invocation flag. Practitioners
have made a design principle of it, dividing a collection into skills a person
invokes and skills the assistant may select for itself.
The division determines what the description does. For a skill the assistant may select, the description is the activation condition, and its wording governs the reliability with which the skill fires. Where invocation is restricted to a person, the description serves only as documentation.
2.3.2. Progressive Disclosure
A skill body occupies the assistant's context window for as long as the skill is active, and competes there with everything else the assistant must attend to. The established response is to relocate material into sibling files and refer to them from the body, so that the assistant loads each only when the work requires it. The specification permits the supporting files; it does not prescribe this use of them.
The technique introduces a dependency. Material held behind a reference is retrieved only when the referring sentence is phrased precisely enough to prompt the retrieval, so a poorly phrased reference silently withholds the material it names.
2.3.3. Length
Published skills in the sample range from a few lines to several hundred. The specification constrains neither bound, and the sample shows no convergence.
2.4. Skills and Tools
A skill and a tool are distinct constructs, and agent frameworks provide both.
A tool is a callable capability. The assistant emits a structured request, a caller executes it, and the result returns into the context. A tool extends what the assistant can do.
A skill is text the assistant reads. It changes how the assistant proceeds, and what it does with the tools already available. A skill confers no capability that the assistant lacked.
3. See also
- Skills in the Compass Skill Framework — the narrower definition this project adopts, and the literature on the construct.
- Large language models — the substrate, defined externally.
- pstack — a published collection, which divides its skills into principles, playbooks and workflow tools, and routes work to them through a sticky mode.
- Matt Pocock skills — a published collection organised on the invocation axis, where user-invoked skills orchestrate and model-invoked skills hold the reusable discipline.
- Council of High Intelligence — a published collection of one coordinating skill and eighteen sub-agents, each supplying a distinct analytical lens.
- Claude Code — the tool that loads these skills.
- External — the reference cluster this page belongs to.