the interface

The last segment of a path, which is the directory name the specification compares a skill's name against.

Every skill a source offers, read and parsed.

A source that lists a directory with no document is a broken source, not an empty one, so discover refuses rather than skipping it: silently offering a model a skill it cannot open is how an agent comes to invent a tool it does not have.

Every fault in a document, from the fence to the last rule.

This is the call a validator makes: a document that does not parse is one fault of kind malformed, and the rest of the list is whatever validate finds in the fields. It is the whole check of a SKILL.md in one function, which is what a command line and a test both want.

a and b with exactly one / between them, whichever slashes either already carries.

Paths are joined here rather than with the platform's separator: a skill root is a key in a Source, and a key that reads the same on every system is the one a report can be compared against.

The limits of the Agent Skills specification.

One skill from a directory.

Raises when the directory holds no document, or when the document is not readable as one: a caller that wants to carry on past a broken skill uses check, which reports the same trouble as a fault.

Read a skill document.

The document opens with a --- fence, then YAML, then a closing ---, then the Markdown body. The YAML is read as StrictYAML, the dialect the specification was written against: every scalar is text, so name: 42 is the name forty-two rather than a number, and a frontmatter that means something other than what it looks like is refused instead of guessed.

root is the directory the document came from. validate compares the directory name with the skill name, and Skill::location needs it to name the document; leave it out when the text has no directory yet.

Reading is lenient about the fields themselves: a document with no name still parses, and validate says what is wrong with it. Only a document that is not a skill document at all is refused.

The block a client puts in a system prompt so a model knows which skills exist, without putting their bodies in the context.

This is the first tier of the specification's progressive disclosure: one entry per skill, the name and the description, and where the document is so the model can ask for the rest. A skill with an empty description still gets an entry — a model that cannot see the name cannot choose the skill, and the description is what validate reports.

Every rule the specification states about the frontmatter, judged against the skill's own text.

The list is empty when the skill is valid. It is not a refusal: a validator reports all the faults at once, because a person fixing a document wants the whole list rather than the first line.

Two things are deliberately not faults. The body length and the token budget are recommendations — the specification asks for a SKILL.md under five hundred lines and says nothing breaks when it is longer — and an unknown key under metadata is the caller's business, since the specification reserves that mapping for clients.

Every fault in the skill at path, judged as a directory rather than as a document that already parsed.

This is the check a repository runs over docs/skills/ in CI: it covers the three things that can go wrong before a document is read — nothing at the path, a file where a directory should be, no document inside — and then the specification's rules about what the document says.

One skill from a directory.

Raises when the directory holds no document, or when the document is not readable as one: a caller that wants to carry on past a broken skill uses check, which reports the same trouble as a fault.