The Agent Skills Open Standard: What's in the Spec and Why It Matters

Your Agent Has a New Common Language, and You Should Learn It

In October 2025, Anthropic shipped Agent Skills as a product feature. By December, it was an open standard. That's a remarkably fast jump from vendor feature to shared format, and it happened because the core idea is simple: package agent expertise as a folder with a SKILL.md file, and any agent can read it.

The numbers back up the momentum. The anthropics/skills repository passed 62,000 GitHub stars within four months of the open-standard release, and partner skills from Atlassian, Figma, Canva, Stripe, and Notion have entered curated directories. The SKILL.md format is now recognized across Claude Code, Codex, Cursor, Gemini CLI, and chat-app agents, which is why the academic community describes the shift as a new era: prompt engineering gave way to tool use, and tool use is giving way to skill engineering.

Here's the catch, and it matters if you're about to build or install skills. The standard covers packaging and discovery, not runtime behavior. Independent analysis of 15 skill frameworks found that hosts differ in where they look for skills and what extras they support, and some catalogs accept metadata fields like allowed-tools without ever applying them. A skill that behaves one way in Claude Code may behave differently in another harness. Full portability often still requires dual manifests or per-host tweaks.

There's also a security problem nobody should gloss over. An academic survey found that 26.1% of community-contributed skills contain at least one vulnerability, and Anthropic's own engineering post warns that malicious skills can introduce vulnerabilities or direct an agent to exfiltrate data. The same review puts it bluntly: curation and scanning provide evidence, not a guarantee.

So what should you actually do?

• Learn the format before writing. The spec requires `name` and `description` frontmatter, keeps SKILL.md under 500 lines, and pushes detail into on-demand reference files.
• Treat the description field as your discoverability bottleneck. It's what the agent reads to decide whether to load the skill at all.
• Don't assume identical behavior across hosts. Keep logic in scripts and verify against each harness you care about.
• Vet every third-party skill before installing: dependencies, licenses, bundled files, and anything that calls out to the network.

That last point is where most teams fall short, because vetting by hand doesn't scale. Roughly one in four community skills carries a vulnerability, and reading a SKILL.md tells you nothing about whether the skill actually improves your agent's output. SkillzBench addresses both gaps for free: every skill in its directory is pinned to a commit SHA, security-scanned, license-checked, and benchmarked in a sandbox with and without the skill so you can see the measured Lift before you install anything.

The SKILL.md format is worth thirty minutes of your time. It's becoming the shared packaging layer for agent expertise, and the teams who understand it will write skills that travel and pick ones with evidence behind them.

Inside the Spec: Three Levels of Progressive Disclosure

At startup, an agent doesn't read your skills. It reads their business cards.

That's the essence of the Agent Skills spec's three-level progressive disclosure architecture, which Anthropic describes as "the core design principle that makes Agent Skills flexible and scalable." Here's how it works:

• Level 1: The YAML frontmatter, containing required name and description fields. This is pre-loaded at startup and costs only a few dozen tokens per skill.
• Level 2: The full SKILL.md body. The agent loads this only when it decides the skill is relevant to the current task.
• Level 3: Bundled references, scripts, and assets, pulled in on demand as the agent works through the instructions.

The economics are the point. The spec keeps SKILL.md under 500 lines and 5,000 tokens, and Red Hat's ACE team reports that performance degrades beyond that ceiling. Anthropic argues the layered structure makes bundled context effectively unbounded for agents with filesystem access, though independent reviewers counter that a large installed catalog still isn't cost-free, since those Level 1 descriptions pile up.

That's why the frontmatter is the discoverability bottleneck. The agent decides whether to trigger your skill based almost entirely on the name and description. Red Hat puts it bluntly: a skill that only works when force-loaded is unlikely to work in production. If your description is vague, the agent never loads the body, and all that carefully written expertise sits unused.

One clarification worth making, because the two get confused: skills and MCP are complementary layers. An academic survey frames it as skills supplying the "what to do" while MCP supplies the "how to connect." A skill teaches the agent a workflow; MCP gives it authenticated access to external systems. They stack rather than compete.

Now the honest caveat. The spec standardizes packaging and discovery, not runtime behavior or permissions. Script support and tool permissions are left to each implementation, and reviewers have documented hosts accepting metadata fields like allowed-tools without applying them. Reading the same SKILL.md folder on two different agents does not guarantee identical behavior between them. The format also says nothing about whether a skill is safe: research found that 26.1% of community-contributed skills contain vulnerabilities, and Anthropic itself warns that malicious skills can direct data exfiltration.

So treat the spec as a shared envelope, not a guarantee of what's inside. That's exactly the gap SkillzBench addresses: every skill in its free directory is pinned to a commit SHA, security-scanned, license-checked, and benchmarked in a sandbox with and without the skill, so you can see the measured Lift before anything touches your agent. Curation and scanning provide evidence, not a guarantee, but evidence beats installing blind.

The Fine Print: Portability Gaps and a 26% Vulnerability Problem

An open standard is only as good as its worst implementation, and the Agent Skills spec has some genuinely uncomfortable fine print. If you're betting workflows on SKILL.md portability, you need to know where the seams show.

The first gap is behavioral. The spec standardizes packaging and discovery, but it deliberately leaves script support and tool permissions to each host. An independent frameworks review puts it bluntly: reading the same skill folder does not establish identical invocation or permission behavior across hosts. The spec "does not by itself supply an agent runtime, a security boundary, or a guarantee that the agent follows the process."

That's not theoretical. At an inspected commit, Grok's skill catalog accepted metadata fields like allowed-tools, model, effort, license, and compatibility without actually applying them. In other words, a skill author can declare tool restrictions that a host simply ignores. And per Red Hat's ACE team, full portability in practice may require maintaining multiple directories or dual manifests, because harnesses differ in where they look for skills and what extras they support.

The second gap is security, and the numbers are worse than most people expect. An empirical analysis of community-contributed skills found that 26.1% contain at least one vulnerability. This isn't a fringe concern from skeptics. Anthropic's own engineering post warns that malicious skills "may introduce vulnerabilities in the environment where they're used or direct Claude to exfiltrate data and take unintended actions," and recommends installing skills only from trusted sources.

Before you install any third-party skill, do the following:

• Review the actual package: dependencies, bundled scripts, permissions, and any instructions that connect to external network sources.
• Check the license and update provenance, since most Anthropic Skills examples are Apache-2.0 but some document skills carry separate terms.
• Prefer skills with pinned versions and security-scan evidence over whatever appears first in a search.
• Remember that curation and scanning provide evidence, not a guarantee, so verify before you trust.

One more wrinkle worth knowing: hook-based enforcement in some implementations fails open. Crashes, timeouts, and malformed responses allow execution to continue, which means the guardrail you think you have may quietly disappear under stress.

This is the evidence-based case for independent verification, and it's why SkillzBench exists as a free directory. Every skill gets pinned to a commit SHA, security-scanned, license-checked, and benchmarked in a sandbox before it earns a trust score. The point isn't to scare you off skills; the format is becoming the shared packaging layer for agent expertise. The point is that "it worked on my machine" isn't a security model, and a quarter of the community catalog failing basic vulnerability checks means you shouldn't install blind.

How to Choose Skills That Actually Help: A Practical Checklist

Knowing the spec is one thing. Choosing skills that genuinely help your agent is where most teams stumble, and the research is blunt about what works.

First, treat every skill like software, not like a prompt snippet. Red Hat's ACE team recommends versioning, Git-based code review, and rollback for skills, plus security hygiene: credentials in environment variables, input validation, and human confirmation for anything that alters state. A skill is code your agent executes. Manage it accordingly.

Second, keep your catalog lean. The same research finds 1 to 3 skills per task is the sweet spot, because overloaded catalogs make agents load relevant skills less often. Progressive disclosure keeps token costs low, but it doesn't make a bloated catalog free. If your agent sees fifty skills, it will miss the one that matters.

Third, prefer durable skills over gap-patches. Red Hat distinguishes preference-style skills that encode workflows and institutional knowledge from ephemeral capability skills that deprecate as models improve. A skill documenting your deployment process outlives a skill teaching the model a trick it will learn natively next quarter.

Fourth, vet third-party skills before you install anything. Empirical analyses found 26.1% of community-contributed skills contain vulnerabilities, and Anthropic itself warns that malicious skills can direct data exfiltration. Check the dependencies, the license, and what permissions the skill assumes.

Your practical checklist before adding any skill:

• Is it versioned, reviewed, and rollback-able, with a pinned source you can audit?
• Does your agent already cover this task with 1 to 3 skills, or would this one crowd the catalog?
• Does it encode durable workflow knowledge, or patch a gap the model will close on its own?
• Have you reviewed its dependencies, license, and bundled scripts for external calls?

Doing all of this by hand is a lot, which is why independent verification exists. SkillzBench pins every skill in its free directory to a commit SHA, runs security scans and license checks, and benchmarks each skill in a sandbox with the same model, with and without the skill, so the Lift is visible in percentage points. It also tracks upstream changes and re-verifies when a skill's source moves, and the free MCP connector lets you toggle skills per agent so it only sees what you chose.

One caution from the frameworks review: curation and scanning provide evidence, not a guarantee. Verification narrows the risk; it doesn't eliminate it. Keep your loadouts small, your skills versioned, and your benchmarks tied to the workflows you actually run.

Staying Current: Why One-Time Vetting Isn't Enough

Vetting a skill once tells you what it looked like the day you checked. It doesn't tell you what it looks like today. The anthropics/skills repository passed 62,000 GitHub stars within four months of the open-standard release, and that pace of change applies to every skill your agents depend on, not just the famous ones.

Splunk's analysis of agent reliability makes the case plainly: production environments and the skills upstream of your agent change continuously, so one-time evaluation is insufficient. A skill that scanned clean in March can pick up a vulnerable dependency in April. Given that empirical analyses found roughly 26% of community-contributed skills contain at least one vulnerability, treating verification as a snapshot is a real risk, not a theoretical one.

This is why SkillzBench treats "stay current" as a core pillar rather than an afterthought. The platform tracks upstream changes to the skills in its directory, re-scans them when changes land, and re-runs sandbox benchmarks so the published Lift reflects the current version, not a stale one. If a skill you rely on changes upstream, free alerts notify you, so you're not manually diffing GitHub commits over coffee.

Ongoing verification only pays off if what reaches each agent stays under your control. That's where per-agent loadouts matter. On SkillzBench, you toggle skills and tools per agent, and each agent only sees what you chose for it. A research agent gets a different loadout than a coding agent, and neither inherits skills you didn't approve. That matters because a skill format, as the independent frameworks review puts it, doesn't by itself supply a security boundary.

A practical ongoing routine looks like this:

• Re-verify on upstream changes: any new commit to a skill's source should trigger a fresh security scan and license check, not a rubber stamp.
• Re-benchmark after material updates: a skill's Lift can shift when its instructions or scripts change, so old numbers shouldn't stand in for new ones.
• Scope skills per agent: keep loadouts minimal, since research points to 1–3 skills per task as optimal and overloaded catalogs make agents load relevant skills less often.
• Get alerted, don't poll: subscribe to change notifications for the skills you depend on instead of hoping you'll notice a breaking update.

None of this turns verification into a guarantee. Curation and scanning provide evidence, and you should still review what a skill actually does. But evidence that refreshes itself beats evidence that fossilizes. You can browse continuously verified skills, check current trust scores and Lift results, and set up free alerts at skillzbench.com. The directory, benchmarks, and MCP connector are all free, and the free MCP tool connects any agent to exactly the skills you've chosen for it.