Agent Skill Format

Sources#

Summary#

SKILL.md is the member of the Agent Context Files family that has a written specification, a measured population and, since July 2026, a second vendor's loading runtime. A skill is a directory: a SKILL.md with YAML frontmatter (name, description, optional license, allowed-tools, metadata, compatibility) and an instruction body, plus optional scripts/, references/ and assets/. Loading is two-stage. Every installed skill's description is resident in the system prompt from initialization, and the body loads only when the description matches a request. Referenced files are read on demand after that.

The evidence on this page covers four things. What practitioners ship: Gao et al.'s census finds files flat and short, mandatory fields at 99% conformance, and optional fields mostly unused. What the client does with malformed files: Kapner et al. find it loads skills the reference validator rejects. Whether the format is cross-vendor: Genkit implements the loading runtime in four language SDKs, which is evidence of convergence but not of progressive disclosure's asserted benefits. What two-stage loading costs: the instruction-count ceiling moves onto the size of the skill catalog, and Claude Code's listing cap truncates descriptions before any adherence floor is reached. The same reference tree that keeps a skill small is also where the Zenity campaign hid its loader.

Whether a skill helps is measured on the skill pages listed from Agent Context Files. Two bear directly on the format: Co-Installed Skill Conflicts measures two-stage loading under a rival, and Skill Copy Provenance measures copies that cross agents unadapted.

What the population of skill files actually looks like (Gao et al., July 2026)#

The authoring guidance on Agent Context Files is prescriptive; From Registry to Repository: How AI Agent Skills Are Written, Adapted, and Maintained (empirical, 18,463 registry + 23,199 repo-resident SKILL.md files) measures what practitioners ship:

Structure is flat and short. Median SKILL.md is 1,678 tokens / 19 headers for registry skills, 1,114 / 13 for repo-local ones (Mann-Whitney p<0.001). H1 and H2 appear in >90%, H3 in 79.8%/67.9%, deeper levels are rare — a flatter hierarchy than human-targeted READMEs, consistent with the progressive-disclosure guidance being followed more by accident than by design.
The spec's mandatory clauses hold; its optional ones are dead letters. ≥99% conformance on SKILL.md presence, valid YAML frontmatter, and description typing/length — but license 16.1%/9.1%, allowed-tools 15.0%/12.5%, metadata 13.1%/10.4%, compatibility 4.0%/3.2%. references/ is the most-used optional subdirectory (31.0%/17.0%), then scripts/, then assets/.
Repo-local skills drift from the activation contract. Only 91.2% of personal-use skills have name matching the parent directory (97.7% in the registry) — a silent activation break, and the paper notes frontmatter descriptions are the most frequently re-tuned field precisely because vague criteria stop the skill firing. The "write the description as trigger conditions, not a summary" advice has measurable teeth.
Six recurring content themes across a 180-file thematic sample: scoping and activation (100%), running the execution lifecycle (89%), grounding domain knowledge (85%), governing agent conduct (81%), ensuring output quality (69%), user/agent coordination (68%) — the backbone a prefilled template would cover, which is the paper's recommendation to registries.

See Agentic Work Systematization for the same study's lifecycle findings (verbatim copying, additive maintenance, the never-edited behavioural contract).

The specification the reference client does not enforce (Kapner et al., September 2026)#

Gao et al. above find ≥99% of individual SKILL.md files carry valid frontmatter; Kapner et al. (Red Hat, arXiv 2609.07360, empirical) count per repository and find 2.3% of 2,660 setups and 3.5% of 511 collections ship a skill with no frontmatter block — consistent, since one bare file among dozens is enough to count. In Claude Code that skill loads anyway on an improvised description while the spec's reference validator rejects it, and a subagent with no description (0.8% of setups) is silently never delegated to, the "silent activation break" shape Gao et al. attribute to name/directory mismatch. The field Gao et al. find nearly dead, allowed-tools (15.0%/12.5% adoption), is the census's most security-relevant: in 3.7% of collections it pre-approves an unrestricted shell. Full treatment: Harness Configuration Defects.

The loading runtime, shipped by a second vendor (Genkit Go, July 2026)#

The census above treats SKILL.md as an Anthropic-originated format that other people write. Google's Genkit Go post (Daniela Petruzalek, 2026-07-31, vendor-claim) is the other half: Google has implemented the loading runtime for the format — in Genkit for TypeScript, Go, Dart and Python — against the agentskills.io specification, which it calls an open standard. The on-disk layout is the spec's, unchanged: SKILL.md (required metadata + instructions) plus optional scripts/, references/, assets/.

The mechanics as the post states them, worth stating precisely because the design is easy to mis-summarize as a set of retrieval tools:

Discovery is injection, not a tool call. At Genkit initialization the middleware scans the configured SkillPaths for SKILL.md files and injects their frontmatter metadata into the system prompt. There is no separate listing step — the catalog is resident from the first token.
Activation is a single tool. When a request matches a skill's description, use_skill is called and the full SKILL.md body, plus access to bundled scripts and references, is loaded into the active context.
The third level has no tool at all. References and scripts are read through the agent's ordinary file access once the body points at them: "use the references/ folder to keep your SKILL.md clean. The agent can read these files on demand."
It is middleware, not a framework rewrite. Skills ride Genkit's existing hook pipeline (WrapModel / WrapTool / WrapGenerate), registered per call as ai.WithUse(&middleware.Skills{SkillPaths:...}). Progressive disclosure implemented as an interceptor around an unmodified generate loop is the cheapest possible way to ship it, and plausibly why it landed in four language SDKs at once.

What this is evidence for, and what it is not. It is real evidence that SKILL.md is becoming a cross-vendor convention rather than one company's file format — the convergence claim at the top of Agent Context Files, previously argued from authoring conventions (CLAUDE.md / AGENTS.md / .cursorrules as one primitive under different names) and now supported on the runtime side, where a second vendor's SDK consumes another vendor's spec verbatim. It is evidence for none of progressive disclosure's benefits. The post gives no token-savings numbers, no adherence numbers, and no comparison against loading every skill eagerly. "Token efficiency" is the first of three asserted advantages; the one sentence in the piece that reads like a result — "with progressive disclosure, token consumption is delayed until absolutely necessary" — is a caption on a Gemini-generated diagram, not a measurement. The two worked examples (a recipe CLI; a multimodal art-restoration flow that picks a paintings skill over drawings / photography) show activation firing on one input each, with the author noting it "might take a few tries."

Three smaller observations that bear on sections above:

Who decides activation is stated two ways. The architecture paragraph says "by monitoring incoming prompts, the middleware detects matching descriptions and activates skills dynamically"; the how-it-works and best-practices sections say the model calls use_skill, and that descriptions need "clear, imperative language so the model knows when to call use_skill". Model-decided is the reading the rest of the post supports, but the two are never reconciled — and the difference matters, because a model-called tool makes activation a tool-selection problem with tool-selection's reliability, where middleware matching would make it retrieval.
The description-as-trigger advice arrives independently. Google's leading best practice is to write the frontmatter description as trigger conditions in imperative language. Gao et al. above found description is the most frequently re-tuned frontmatter field in the wild, precisely because vague criteria stop a skill firing. Prescription and measurement converge from different vendors by different methods.
The vendor exemplar carries the fields practitioners drop. Google's sample frontmatter includes license and a metadata block (author, version) — two of the optional provisions Gao et al. measured at 16.1%/9.1% and 13.1%/10.4% in the wild. Nothing follows about adoption; it is a reminder that those conformance rates are measured over practitioner files, not vendor documentation.

The connection neither source makes. Google's stated rationale is a token budget: loading every procedure and reference into the persistent window "consumes valuable tokens, dilutes the model's focus, and increases the likelihood of incorrect responses." But the measured binding constraint is simultaneous instruction count, not tokens — Instruction Compounding records all-rules compliance floored at zero by ~80 verifiable instructions on all five models tested, in every format and both placements. Progressive disclosure is a direct architectural answer to that floor: the instructions in force at any one generation are a single skill body, not the union of every skill installed. It is the same argument the lazy-subdirectory bullet on Agent Context Files makes for nested AGENTS.md, now shipped as a first-class SDK primitive rather than practiced as a loading discipline.

It is a partial answer, and the partiality is the interesting part. Every installed skill's description sits in the system prompt from initialization, so the design lowers the count from all instructions to all descriptions plus one body — it relocates the ceiling onto the size of the skill catalog rather than removing it. Nobody has measured where the relocated ceiling sits.

The catalog ceiling two-stage loading creates#

Two-stage loading lowers the instructions in force at one generation from every installed instruction to every installed description plus one body. The ceiling therefore moves onto the size of the skill catalog. Whether that ceiling is real was the question this section carried, and it is now answered on existence (Resolved Questions below): Claude Code's skill listing is capped at 1% of the context window, so descriptions are truncated before any adherence floor is reached, and selection already degrades when one same-job rival is added. The threshold, and whether selection breaks before all-rules compliance does, is still open. The tool-layer version of the same wall, and the routes that take a catalog off the context, are on Tool-Catalog Context Cost.

Progressive disclosure used as concealment, in the wild (August 2026)#

Zenity Labs' campaign write-up (Michael Bargury, 2026-08-06, case-study) is the first in-the-wild use of the format's central loading discipline as concealment: benign front skills routed the agent, through sibling cross-references, to a secondary setup-installation.md holding a curl … | base64 -d | node loader, so no single file contained both the instruction to run something and the thing to run, and the file a reviewer, scan or listing reads is not the one that executes. The surface is ordinary — Gao et al. above put references/ in 31.0% of registry and 17.0% of personal-use skills — and the malicious skills also declared the attacker's checkout the "only supported" install path, showing that instructions about where to trust are the same kind of text as instructions about how to work, which the format gives a reader no way to weight differently. This pairs with the EvoMal scope boundary Agent Context Files has carried since 2026-09-02: markdown skills are excluded from the CREATE-path attack by definition, yet they are the substrate with the in-the-wild campaign, where the attacker needs the agent only to follow a reference. Full treatment: Agent Supply Chain Risk.

Connections#

Co-Installed Skill Conflicts — the skill format's two-stage loading under a rival: the model chooses between two same-job skills from descriptions alone (body read only after), install scope rather than listing order decides, a personal skill silently overrides the project's, and the listing cap is low enough to truncate a description in 95.8% of Opus 5's two-similar-skill listings
Skill Copy Provenance — the skill format in circulation. Copies cross agent folders unadapted: 23.2% of .codex skills and 14.7% of .cursor skills name tools only Claude Code provides, and a third of copies between agent folders now cross platforms. The paper asks vendors to check that a skill names only the loading agent's tools
Tool-Catalog Context Cost: the tool-layer version of this page's skill-catalog ceiling question. Measured resident-definition costs (~93K tokens for 287 MCP tools; 13.7× first-call context for 23 tools vs 4) and the routes that take the catalog off the prefix: deferred loading, a discovery proxy, a CLI
Agent Supply Chain Risk — what the convention on this page becomes once it is distributed. A SKILL.md plus its references/ tree is now shipped through marketplaces, installed by a package-manager-shaped command, and reused by verbatim copy with no update channel, which is a supply chain in everything but tooling. The 2026-08 Zenity campaign is that page's first in-the-wild instance and this page's first adversarial reading of progressive disclosure: the loader lived in the referenced file, the front file stayed clean, and takedown of the listing could not reach the copies
MCP Tool Poisoning — where the concealment reading above is stated formally. ShareLock shows per-tool description scanning is information-theoretically blind once a payload is split across descriptors; the Zenity chain reaches a weaker version of that property through this page's progressive-disclosure convention alone, with the loader one dereference past the file a scan reads. The difference is what it costs the attacker — secret sharing there, a second markdown file here — and what it costs the defender: a scanner that follows a skill's reference tree closes the second, and nothing closes the first
Agent Context Files — the parent pattern: the skill file is one member of the repo-versioned markdown control plane, and the Khatri correctness null, the Claude 5 rewrite of the rules and the maintenance disciplines that bear on skills are there
Harness Configuration Defects — the per-repository census behind the Kapner section: skills without frontmatter, subagents without descriptions, allowed-tools pre-approving an unrestricted shell
Instruction Compounding — the count ceiling progressive disclosure attacks: all-rules compliance floors at ~80 simultaneous verifiable instructions, which is why the resident-description catalog is the quantity to watch
Agentic Work Systematization — Gao et al.'s lifecycle findings (verbatim copying, additive maintenance) and the Codex skills-adoption data; the Genkit post as the runtime mirror of the authoring side
LLM-as-Compiler Knowledge Base — the Open Knowledge Format, where Google is on the authoring side; Genkit is the case where it consumes another vendor's spec, and only that side is evidence of convergence
Agent Self-Poisoning (the CREATE-Path) — EvoMal's scope boundary: executable self-authored skills are in scope, markdown skills are excluded, yet the in-the-wild campaign used markdown

Open Questions#

Residual of the skill-catalog-ceiling question (Resolved below): at how many resident skill descriptions does selection degrade, and before or after all-rules compliance? Settler: Prompt Design at Scale: How Format, Instruction Count, and Context Length Shape Instruction Adherence and Hallucination in Large Language Models's harness on N skill frontmatters at default listing caps.

Resolved Questions#

Does metadata-injection discovery hit a catalog ceiling on the skill layer, as it does on tools? Answered (2026-10-26) on existence: yes, and on the skill layer it is a hard truncation cap that arrives before any adherence floor. Yan, Xu et al. (arXiv 2610.11647, empirical) measure Claude Code 2.1.283's skill listing at 1% of the context window (8,000 characters for Sonnet 4.6 and Haiku 4.5, 6,000 for Opus 5). Under that cap, 95.8% of Opus 5's listings with two similar project skills would lose at least one description, so the authors raised it to 20,000 to run at all. Selection also degrades at the smallest step, from one candidate to two: a same-job rival lowers use of the installed skill by 19.9 pp, against 5.9 pp for an unrelated extra skill. Threshold and ordering stay open (residual in Open Questions). Details on Co-Installed Skill Conflicts. Evidence trail (original bullet, moved 2026-10-26): Metadata-injection discovery relocates the instruction-count ceiling onto the skill catalog rather than removing it: every installed skill's description is resident from initialization, so a large enough skills/ directory should floor adherence before any skill body loads. How many resident descriptions does that take, and does use_skill selection degrade before or after all-rules compliance does? Falsifiable with Prompt Design at Scale: How Format, Instruction Count, and Context Length Shape Instruction Adherence and Hallucination in Large Language Models's harness pointed at N skill frontmatters instead of N rules. Partially answered on existence, not on threshold (2026-10-15): Uber's MCP Gateway (Designing MCP Gateway: Uber's MCP Management Platform, case-study, first-party) hit the same ceiling one layer over, on resident tool definitions. At 800+ servers and 5,000+ tools (self-reported) it stopped keeping the catalog resident, replacing it with incremental discovery (Omni MCP's discover_server → discover_tools → get_tool_schema → invoke_tool) and a CLI (Code Mode, now its default for coding agents). A sibling Uber post prices the resident version at ~50–70K tokens for 100+ tools. That confirms a practitioner hit the wall and routed around it. It reports no N, and no selection or compliance curve, and the stated reason is the context limit, not degraded selection, so both halves of the question stay open.

Sources#

From Registry to Repository: How AI Agent Skills Are Written, Adapted, and Maintained — Gao, Lulla, Lin, Baltes, Treude & Zahedi, From Registry to Repository, arXiv 2607.00911, 2026-07-01, empirical. Cited for §V-A packaging and spec conformance (Table I), §V-B content taxonomy (Table II) and the name/directory mismatch rate. Lifecycle findings on Agentic Work Systematization
Designing MCP Gateway: Uber's MCP Management Platform — Srivastava et al., Designing MCP Gateway, Uber engineering blog, 2026-10-01, case-study (first-party, self-reported). Cited only for the 2026-10-15 partial answer in the resolved catalog-ceiling question
Prompt Design at Scale: How Format, Instruction Count, and Context Length Shape Instruction Adherence and Hallucination in Large Language Models — Netanel Eliav, arXiv 2607.19257, 2026-07-21, empirical. Cited for the harness that would settle the residual catalog-ceiling question
Enable on-demand expertise with Agent Skills in Genkit Go — Daniela Petruzalek, Google Developers Blog, 2026-07-31 (vendor-claim, 2,801 words): "Brief Recap of Agent Skills" (the agentskills.io on-disk layout and frontmatter example), "How it works" (the three stages — metadata injection at init, use_skill activation, body-plus-resources execution), the Genkit middleware hook taxonomy, and "Best practices for skills". No measurement of any kind appears in the post; the "token consumption is delayed until absolutely necessary" line is a diagram caption, not a result, and the two demos are single-input walkthroughs. The raw body was rebuilt from the page HTML after WebFetch merged that caption into body prose as though it were a sentence, dropped the demo image's identification, and dropped every inline link; all 11 code blocks were byte-identical either way
Attackers Target Agents via The Skill Supply Chain — Michael Bargury (Zenity Labs), Attackers Target Agents via The Skill Supply Chain, labs.zenity.io, 2026-08-06, case-study (vendor-authored; the corroborated record — OSV MAL-2026-10484 / MAL-2026-10869, GitHub commit SHAs, Internet Archive captures, published hashes — is treated as fact, the detonation results are attributed to the vendor's own lab, and the platform install counters are attributed as displayed-not-unique). Cited here for "Hiding in progressive discovery" (the benign front file, the setup-installation.md reference opened only at install, the cross-skill routing) and the quoted skill text on borrowed authority (the "only supported" install path, the "managed registry and the source of truth" instruction). Full treatment on Agent Supply Chain Risk
One Skill Too Many: How Co-Installed Skills Conflict in Coding Agents — Yan, Xu, Li, Xu, Liu, Deng & Ma (UNSW et al.), One Skill Too Many: How Co-Installed Skills Conflict in Coding Agents, arXiv 2610.11647, 2026-10-08, empirical. Cited for §2.1 and §3.8 (two-stage loading, per-skill truncation, the measured listing cap). Full treatment and parse notes (Table 1 welded, transcribed from pdftotext) on Co-Installed Skill Conflicts