What Is Skill.md? The File Format Behind Agent Skills

Why Every Agent Suddenly Reads SKILL.md Files

If you peeked inside a coding agent's system prompt in early 2025, you'd often find a wall of text: coding conventions, tool preferences, workflow rules, all crammed into one giant instruction block. The problem got so severe that system prompt payloads ballooned from around 200 tokens to as much as 5,000 tokens, eating context and degrading performance. Meanwhile, every editor had its own workaround — Cursor Rules here, Copilot Instructions there — none of which traveled between tools.

SKILL.md emerged as the standardized answer to both problems. Introduced by Anthropic on October 16, 2025, and published as an open standard on December 18, 2025, the format defines a skill as a directory containing, at minimum, a SKILL.md file — a Markdown document that pairs YAML frontmatter (a name and a description) with a body of procedural instructions. Optional scripts/, references/, and assets/ folders ride alongside it.

The economics explain why adoption was instant. Under the format's progressive disclosure model, only about 100 tokens of metadata load at startup; the full body loads only when triggered; and unused bundled files cost zero tokens. That means an agent can carry hundreds of skills without paying a context penalty until one is actually relevant.

The cross-platform support list tells the rest of the story:

• Claude Code, Anthropic's original home for the format
• OpenAI Codex and GitHub Copilot
• Microsoft VS Code and the Agent Framework
• Cursor and Google Antigravity

What made SKILL.md different from the editor-specific hacks it replaced was portability. Cursor Rules and Copilot Instructions are activation systems tied to a single tool; as one QA-focused analysis put it, "the visible syntax differences are small compared with activation behavior." Skills, by contrast, are persistent, version-controlled, and portable across agents — a genuine standard rather than a per-editor convention.

Momentum followed quickly. Claude Skills gained more than 17,000 GitHub stars after launch, and Anthropic serves over 300,000 business customers, so the format reached a large installed base almost immediately. The Goose team at Block captured the design philosophy neatly: "MCP gives agents abilities; skills teach agents how to use those abilities well."

But the same open, filesystem-based design that made SKILL.md portable also created a trust problem. Skills run with the agent's full permissions, the ecosystem lacks mandatory reviews or package signing, and researchers have shown how quickly that can go wrong. That gap — between a format anyone can write and a format you can safely install — is exactly why SkillzBench is building independent verification and benchmarking for skills, and why anyone adopting SKILL.md today should treat every skill with a healthy dose of scrutiny.

How Progressive Disclosure Makes Skills Cheap to Install

Imagine installing a hundred browser extensions without any of them touching your RAM until you actually click. That's roughly what Agent Skills achieve for an AI agent's context window, and it's the single cleverest thing about the SKILL.md format.

The trick is a three-tier loading model the spec calls progressive disclosure. At startup, an agent reads only a skill's metadata — its name and description — at a cost of roughly 100 tokens per skill. The full SKILL.md body, which the spec recommends keeping under 5,000 tokens, loads only when the agent decides the skill is relevant to the current task. Everything bundled alongside it — reference documents, scripts, assets — costs zero tokens until the agent actually opens it. As Anthropic's documentation puts it, you can install many skills without context penalty: until one triggers, only its name and description occupy space.

• Tier 1 — Metadata (~100 tokens): name and description, always loaded, used to decide relevance
• Tier 2 — SKILL.md body (<5,000 tokens recommended): procedural instructions, loaded on activation
• Tier 3 — Bundled files: references, scripts, and assets, loaded only when referenced

Rani Osnat of Backslash Security captures the design with a kitchen metaphor: instead of forcing the AI to memorize an entire cookbook, you hand it the relevant recipe card when it's time to cook. Scripts never enter the context window at all — only their output does. This matters because system prompts have already ballooned from roughly 200 to 5,000 tokens, and stuffing expertise there simply doesn't scale.

This architecture also clarifies how skills differ from MCP. As the Goose team at Block frames it, MCP gives agents abilities; skills teach agents how to use those abilities well. An MCP server says "I can access that data for you," while a skill says "this is how the task should be done." The two layers are complementary, which is why managing them together — toggling both skills and tools per agent — is the model SkillzBench is building into its per-agent loadouts.

There's a consequence worth internalizing: because activation depends entirely on that ~100-token description, description quality is the format's load-bearing wall. A useful instruction that never activates is, as one QA practitioner observed, equivalent to a missing instruction. Vague descriptions mean silent failures — the skill sits installed but invisible. That's a key reason SkillzBench treats description quality as one of the signals in the quality judging it's developing, alongside security scanning and sandbox benchmarking. Cheap to install is the format's promise; being found when needed is the author's job.

The Trust Gap: When a Single Approval Can Cost $5 Million

In October 2025, security researchers at Cato CTRL showed how easy it is to turn a friendly skill into a weapon: they modified a legitimate GIF Creator skill so it silently fetched and executed live MedusaLocker ransomware — all under a single user approval, with no secondary prompts or warnings. The skill did exactly what the agent was told. That was the problem.

The root issue is architectural. Skills run with the agent's full filesystem, network, and shell privileges, and as Backslash Security researchers point out, the format effectively introduces prompt injection by design. A skill is just instructions plus optional scripts — nothing in the format prevents those instructions from directing the agent somewhere entirely different from its stated purpose. Anthropic's own documentation acknowledges that a malicious skill can direct Claude to invoke tools or execute code in ways that don't match the skill's stated purpose.

The scale of abuse is already real. A campaign tracked as ClawHavoc deployed over 300 credential harvesters through skill marketplaces, according to Backslash's analysis. Meanwhile, the financial stakes keep climbing: the average cost of a ransomware incident now stands at $5.08 million per IBM's 2025 Cost of a Data Breach Report, cited by Cato. One careless install of a "helpful" skill can sit at the center of that bill.

What makes the situation sharper is the ecosystem's maturity gap. Skills have spread rapidly — Claude Skills gained 17,000+ GitHub stars since launch — yet the ecosystem reportedly operates without mandatory reviews, package signing, or lockfiles. Anthropic's official response to the ransomware demonstration placed the burden squarely on users: it is the user's responsibility to only use and execute trusted Skills. Cato CTRL's researchers put it more bluntly: when visibility ends after the first approval, trusted code becomes an attack surface, and one consent can become total compromise for an enterprise.

• Skills execute with the agent's full filesystem, network, and shell permissions — the same privileges as the person who approved them.
• A single approval is the only gate: Cato CTRL's MedusaLocker demo ran end-to-end with no secondary prompts or warnings.
• There is no mandatory review, signing, or lockfile mechanism in the ecosystem to catch tampered or malicious skills.
• API skills run in a sandboxed container with no network access, but Claude Code skills have full network access — risk varies sharply by surface.

This is the trust gap that verification infrastructure has to close. It's why SkillzBench is building security scanning, version pinning to commit SHAs, and sandbox benchmarking into its Verify pillar — and why, at launch, it will list script-bearing skills as link-out only, keeping its own ecosystem limited to instruction-only packages until the trust problem has real tooling behind it. Until then, Anthropic's advice stands as the ecosystem's only real defense: treat every skill install like installing software from an unknown vendor, because right now, that's exactly what it is.

What to Check Before Installing Any Skill

Installing a skill takes seconds; undoing the damage from a bad one can take far longer. Because a malicious skill can direct an agent to invoke tools or execute code in ways that don't match its stated purpose, a short pre-installation review is worth the two minutes it costs.

Anthropic's own guidance is to treat skill installation like installing software — the same caution you'd apply to any new binary on your machine. That starts with pinning. Rather than pulling from a moving branch, pin the skill to a specific commit so the code you reviewed is the code you run. The ecosystem currently operates without mandatory reviews, package signing, or lockfiles, so provenance is entirely on you.

Next, read the SKILL.md body, not just the description. The description is what triggers activation; the body is what the agent actually follows. Look for instructions that drift from the skill's stated purpose — unexpected network calls, requests to run scripts you didn't anticipate, or steps that touch files unrelated to the task. Cato CTRL demonstrated this exact pattern: a modified legitimate skill silently fetched and executed live ransomware under a single approval, with no secondary prompts or warnings.

A few more checks before you commit:

• Verify the license — confirm the repo states terms you can actually use, especially for skills you'll deploy across a team.
• Check frontmatter hygiene — name must match the parent directory (max 64 characters, lowercase with hyphens), and version belongs inside metadata, not as a top-level field, if you want portability across agents.
• Know your runtime — API skills run in a sandboxed container with no network access, while Claude Code skills have full network access. A skill that's harmless in one surface may not be in another.
• Scan bundled scripts — remember that scripts never enter the context window; only their output does, which means you won't "see" what they do in the transcript.

The inconvenient truth is that this manual review doesn't scale, and security researchers note that skills effectively introduce prompt injection by design, operating with the agent's full filesystem, network, and shell permissions. That's the gap SkillzBench is building for: pinning every version to a commit SHA, validating licenses, security-scanning, and quality-judging skills before you ever install them — so the checklist above becomes automated rather than aspirational. Until then, review before you trust.

Where Independent Verification and Benchmarks Fit In

So who closes this gap? Anthropic's own guidance puts the burden squarely on users: "It is the user's responsibility to only use and execute trusted Skills" (per Cato CTRL's threat research). Yet the ecosystem reportedly runs without mandatory reviews, package signing, or lockfiles — the basic plumbing npm and pip worked out years ago. That combination — real attack surface, no institutional trust layer — is exactly the opening for independent verification.

This is where SkillzBench comes in. Built by AIQ Labs as an independent testing lab for agent skills, it is currently in pre-launch development around five pillars designed to answer the two questions every skill user has: is this skill safe, and does it actually help?

• Discover — continuously crawl and deduplicate skills from GitHub, so the ecosystem gets one canonical record instead of scattered forks.
• Verify — pin every version to a commit SHA, then validate structure, check licenses, security-scan, and quality-judge each skill.
• Benchmark — run every skill in a sandbox with the same model, with and without the skill, and publish the Lift in percentage points.
• Equip — one MCP server plus per-agent loadouts, where each agent only sees the skills and tools explicitly toggled on for it.

The benchmarking methodology matters most. Measuring performance with and without the skill isolates its actual contribution — the difference between a skill that earns its context footprint and one that just sounds good in its description. And because activation is driven entirely by that description, per the Agent Skills specification, a skill that never triggers is functionally invisible regardless of how well-written its body is. Lift is always reported separately from the trust score, and money never touches either number.

The design is also architecturally honest about the format's constraints. SkillzBench's launch scope covers instruction-only skills — SKILL.md plus text references — while script-bearing skills are listed link-out only. That boundary reflects the research: Cato CTRL showed a modified GIF Creator skill delivering live ransomware under a single approval, and the ClawHavoc campaign reportedly pushed 300+ credential harvesters through skill marketplaces. Verification and sandboxed benchmarking are being built precisely because "it worked for someone on GitHub" is not evidence.

SkillzBench is not live yet — the waitlist and newsletter are. If you want independent verification and real Lift numbers before you install your next skill, that's where to watch.