What Are AI Agent Skills Files (SKILL.md)?

An AI agent skills file, usually written as SKILL.md, is a plain-text instruction packet that teaches a general-purpose AI agent how to do one specific job. It loads only when that job comes up. Think of it as a laminated procedure card in a folder, not a rule baked into the model itself.

What is an AI agent skills file, in plain English?

A skill is a directory. Inside it sits a SKILL.md file with required YAML frontmatter, at minimum a name and a description, plus a body of instructions. It can also bundle scripts, templates, or reference documents.¹ The agent doesn't read the whole thing constantly. At startup it preloads only the lightweight frontmatter for every skill you have installed, then decides at run time whether the current task matches a skill's description closely enough to justify reading the rest.¹

That's the whole trick. Instead of cramming every procedure your agent might ever need into its system prompt, you hand it a stack of index cards. Most stay closed most of the time.

How do skills actually load? Progressive disclosure, explained

Anthropic and early adopters describe this as a three-level loading model, sometimes called progressive disclosure:¹²

1. Level 1: metadata. The frontmatter, name and description, loaded for every installed skill at all times. This typically runs under 100 tokens per skill, so having dozens installed costs comparatively little at this level.²
2. Level 2: the SKILL.md body. Loaded only when the agent judges the skill relevant. This can run from a few hundred to several thousand tokens.²
3. Level 3: bundled scripts and reference files. Loaded only as needed, effectively unbounded in size since it never touches the context window until called.¹²

The payoff: a skill can be as thorough as it needs to be without bloating every turn, provided the metadata layer stays small and the agent's relevance judgment is good. That second condition matters a lot, as we'll get to.

How Skills went from a Claude feature to an open standard in under 90 days

Anthropic shipped Agent Skills for Claude in October 2025. On December 18, 2025, it published the format as an independent open standard at agentskills.io, moving governance outside any single vendor.³⁴ The launch page already listed adoption from OpenCode, Cursor, Amp, Letta, goose, GitHub, and VS Code.³ OpenAI, a direct competitor, added Skills support to Codex within roughly 48 hours of the announcement.³⁴ Microsoft has since documented Agent Skills as a supported open standard inside GitHub Copilot's cloud agent, Copilot CLI, and VS Code.⁵

That's a genuinely fast standardization arc. Most agent tooling wars drag on for years before anyone agrees on a shared format. This one settled in about a quarter.

Why do skill libraries get out of hand so fast?

The scaling problem shows up fast once teams start collecting skills instead of writing one or two carefully. One developer working in Google Cloud's ecosystem accumulated 170 installed skills pulled from public repositories, including Google's own and Addy Osmani's collection, and found his agent was injecting roughly 17,000 tokens of skill-description overhead into every single turn, about 510,000 tokens across a 30-turn coding session, before any actual work happened. After auditing and pruning down to 49 active skills and delegating the rest to meta-skill orchestrators, he cut system-prompt overhead by about 80.3%, saving over 400,000 tokens per pair-programming session, with noticeably better tool selection and lower latency. That kind of overhead is exactly the failure mode covered in our explainer on agentic context management: the model isn't the expensive part, everything you keep shoving into its memory is.

That's not just a token-cost story. Academic research on tool selection, using the Berkeley Function Calling Leaderboard, found that presenting a model with 50 tool or skill choices produced 60.9% chance-corrected selection accuracy, versus 76.8% when the choice set was narrowed to around 7 focused options. More options doesn't just cost tokens. It degrades the agent's ability to pick the right one.

Anecdotally, this matches what ordinary users report. A thread on r/ClaudeCode captured the same anxiety in plainer terms: developers feeling overwhelmed by the growing number of available skills and worried their setup was becoming bloated.⁶ The rigorous case study and the casual complaint are describing the same failure mode from opposite ends.

Skills vs. MCP: what's the difference?

Skills and MCP are not competing standards. They solve different layers of the same problem. A skill encodes stable, reusable procedural knowledge, the how: the steps for filing a certain kind of report, the conventions for writing a commit message, the checklist for reviewing a contract. MCP servers and tools supply live, changing data and deterministic execution, the what-now: the actual database query, the actual API call, the actual file write.¹⁷

Anthropic frames Skills explicitly as complementary to MCP, not a replacement for it, and describes Skills as a way to teach agents complex workflows that involve external tools.¹ The Model Context Protocol project has gone further, publishing its own guidance on building with Agent Skills for MCP server development, where skills walk an agent through design decisions like deployment model, auth pattern, and tool structure before it scaffolds a server.⁷ The two formats are being formally integrated, not left to compete. If you're already thinking about how an agent should orchestrate several tools and servers at once, this is the same territory covered in our piece on orchestrating your own office of clones.

Where do skills fail silently?

Skills don't throw clean errors when something's wrong. They just quietly underperform. Documented failure modes include:⁸

• Vague trigger descriptions. If a skill's description doesn't clearly signal when it applies, the agent never selects it, and nothing tells you it exists.
• Truncated skill lists. When combined skill descriptions exceed an internal character budget, some get cut off entirely.
• Broken frontmatter. Autoformatters can mangle single-line YAML, silently corrupting the metadata the agent depends on.
• Staleness. A markdown file doesn't know when the process it describes has changed. Nothing forces a review.
• No built-in auth. Skills have no native way to hold OAuth tokens or credentials the way a connected MCP server does, so any skill needing live authenticated access has to hand off to a tool or server that owns that auth.⁸

None of these produce a stack trace. They just produce an agent that quietly does the wrong thing, or nothing at all.

Are skills files a security risk?

Yes, and it's the part that should worry anyone treating skills as harmless documentation. A skill is just a text file, which means it's also a delivery vector.

Snyk's ToxicSkills research scanned 3,984 published skills across public registries and found that 36.8% carried at least one security flaw, 13.4% carried a critical-level issue, and 76 skills contained confirmed malicious payloads, 91% of which paired prompt injection with traditional malware.⁹ A separate academic analysis by Liu et al., published in January 2026, used static analysis and model-based classification across 31,132 skills and found 26.1% contained at least one vulnerability across 14 patterns, with data exfiltration at 13.3% and privilege escalation at 11.8% the most common issues.⁸ Two independent teams, two different datasets, two different methods, and roughly the same conclusion: a meaningful chunk of the skills people are installing from public repositories are unsafe.

This is the governance problem in miniature. A skill file looks like documentation, gets treated like documentation, and gets installed with none of the scrutiny you'd apply to a binary or a dependency. But it runs inside your agent's context and can direct it to exfiltrate data or escalate privileges just as effectively as compromised code can. This is the same trust question raised anywhere an outside system gets read access to your data, which is why it's worth understanding how AI connectors handle that access before you install anything from an unvetted repo. Treating your skill library as an unmanaged pile of downloaded markdown is the same mistake as treating a plugin marketplace as risk-free because it's just JavaScript.

Should you build a skill, an MCP server, or both?

A simple framework for deciding:

1. Build a skill when the thing you're encoding is procedural knowledge that doesn't change often: a style guide, a checklist, a workflow a human would otherwise explain in a Slack message every time.
2. Build an MCP server or tool when you need live data, a deterministic action, or anything requiring authentication: a database read, an API call, a ticket creation.
3. Build both when the task involves a stable procedure that also needs to touch a real system. Let the skill carry the reasoning and let MCP carry the execution.
4. Audit before you install. Treat every third-party skill like a dependency: check its source, read the frontmatter and body before adding it, and prune skills you're not actively using.
5. Watch your token overhead. If your agent's context is filling up with skill metadata before it does any work, that's a sign your skill library needs consolidation, not expansion.

The underlying point matters more than any single checklist item. Skills and MCP are both pieces of infrastructure you can own outright, plain text and open protocols, not a rented feature buried in someone else's platform. If your team is standardizing internal knowledge into skills, it's worth making sure that knowledge is actually readable by the agents pulling it, the same problem covered in serving markdown to AI agents using Accept headers. The standard moved fast. The discipline to run it safely, at scale, on infrastructure you actually control, is still catching up.