agentskills.io specification (the open skills standard)

The open, cross-vendor specification that formalizes agent-skills as a portable format. Per adk-agents-with-skills, skills authored to this spec are universal — the same skill runs across "Gemini CLI, Claude Code, Cursor, and 40+ other products." This is the agent-skills form factor maturing from each tool's native skill directory into a single shared standard.

A skill's shape

Each skill bundles: metadata (name, description), a detailed instruction body, and optional reference resources.

Progressive disclosure (the core mechanism)

A three-level loading architecture so the agent pays context cost only for what it actually uses:

L1 — metadata (~100 tokens): names + descriptions, loaded at startup so the agent knows what exists.
L2 — instructions (<5,000 tokens): the full skill body, loaded only when the skill is activated.
L3 — resources: external references, loaded on demand.

The claim: this cuts baseline context usage by ~90% vs. a monolithic system prompt adk-agents-with-skills. (Vendor-stated figure, not independently benchmarked here.)

Why it matters to the thesis

It sharpens the agent-skills insight — capability as portable markdown an agent loads — into an interoperable one: the same markdown procedure now moves across vendors. It also operationalizes the "load knowledge on demand" idea that distinguishes the llm-wiki's index-then-drill pattern; progressive disclosure is the procedural analog of the wiki's index → page drill-down. Related substrate: model-context-protocol.

Distribution (skills as packages)

As the format standardizes, skills get published/installed like packages — e.g. node-js-functional-patterns-skill via an MCP/skills marketplace, and Hermes' "Skills Hub" (hermes-agent). A nascent skill-marketplace layer riding on this spec.

Canonical first-party home

Anthropic publishes the spec and a reference set of skills in its official anthropic-skills repo — the spec (./spec/), a template, example skills, and a Claude Code plugin marketplace in one place. So the standard isn't only a third-party agreement; a major vendor authors and ships it directly, including the source-available document skills that power Claude's production file handling.

The widest install matrix so far (2026-07-28)

perplexity-api-platform-skills is a second major vendor authoring against the spec, and it stretches the portability claim further than anything here. One repo is simultaneously a Claude Code plugin marketplace, a Codex plugin marketplace, and a plain skills/ directory — no symlinks, no separate plugins/ tree. npx skills add perplexityai/api-platform-developers reportedly "fans out to ~70 agents", gh skill add supports version pinning, and there's a zero-install fallback that makes the point sharply: "Any agent that can fetch a URL can use a skill directly."

That last path is the standard reduced to its minimum: the artifact is a markdown file at a URL, and any agent that can read it can use it, no installer in the loop. Set against ponytail's 15-host roster wired per-host and renwei-writing's Cola-specific directory, the delivery layer is visibly consolidating even where it's still packaged per-client.

The same repo bundles a docs MCP server in its root .mcp.json alongside the skills, so procedure (skills) and current facts (MCP) install together — the skills×MCP pairing as one artifact rather than two decisions.

What progressive disclosure does not price (2026-08-15)

The L1/L2/L3 architecture prices text: keep the body out of context until the skill activates and the resources out until they're read. agent-skills-can-be-harmful measured 182 cost blowups against paired reference runs and found that framing covers about a quarter of them. Excessive Procedure — the extra steps the skill's instructions induce — is 114 of 182 cases (62.6%), with excessive verification alone at 67. A skill can be small at every level and still be expensive to obey, because the L2 body's cost is not its token count but the workflow it mandates.

Where cost is context, the split lands squarely on this spec's own boundary and says authors are putting material on the wrong side of it: 43 of 46 context-overhead cases are the mandatory body, 3 are the L3 supplementary material. Lazy loading works. The body is where the bloat went, because it is the part that sits in every model call once activated. The paper's recommendation is the spec's mechanism used harder — short always-loaded instructions, examples and checklists moved behind explicit L3 triggers.

Two other findings touch the metadata layer. The L1 description is an applicability signal, and mis-signalling it is nearly a non-problem in practice: only 2 of 125 functional failures came from a skill that should not have loaded. And nothing in the spec distinguishes a skill's requirements from its examples and defaults — which is the mechanism behind 86 of those 125 failures, and the one format-level gap this evidence names. Cf. pm-skills-arsenal's typed input_schema/output_schema as the closest thing the ecosystem has to declaring that boundary.

The format is universal; the location is not (2026-08-23)

attention-is-all-you-have crawled the ecosystem this spec created and produced the first counts of it: 56,804 SKILL.md directories across 1,133 repositories, and — the number that lands on this page — 75 coding agents using 54 distinct project-level skills directories, plus 58 different home-directory locations. Nineteen agents have converged on .agents/skills/; the other 56 sit in vendor dotdirs. The community CLI copes by installing once and symlinking into every agent it detects.

So "the same skill runs across 40+ products" is true of the format and false of the delivery. A team running two agents maintains two installations, and an author documents N install paths. This spec standardized what a skill is and left where it goes to each vendor, which is the gap atskills-protocol attacks — by removing storage rather than standardizing it.

The same paper prices the L1 layer from the other side. Progressive disclosure keeps the body out of context, but the description that stays resident costs 50–280 tokens per installed skill and its only purchase is auto-triggering, whose reliable capacity the authors bound at fewer than a hundred slots per agent (argued from the literature, not measured — they propose the measurement as future work). Two consequences for this page. Skill bodies are median 921 words, which settles that residency was never an option for them. And the L1 description has become a bidding surface: authors pad it with trigger conditions to win the match, Stripe's flagship skill carrying roughly 150 words of them at about 20× the tokens of a quiet description. That is the spec's cheapest layer turning into its most contested one.

agent-skills · atskills-protocol · attention-is-all-you-have · adk · adk-agents-with-skills · model-context-protocol · llm-wiki · node-js-functional-patterns-skill · anthropic-skills · perplexity-api-platform-skills · agent-skills-can-be-harmful · skill-induced-failure · agentic-awesome-skills