A folder full of instructions can teach an AI a brand-new capability. The same folder can quietly hijack it. Here is how that trick works — and why it cuts both ways.
Why isn't a smart AI just good at my specific tasks already?
Start with a frustration anyone who has used a capable AI assistant has felt. It is brilliant in general and mediocre at your specifics. It can write an essay, but it doesn't know your company's brand voice. It can talk about spreadsheets, but it fumbles the exact way your finance team formats a quarterly model. How do you close that gap?
There are only a few honest answers, and most of them are bad.
You could retrain the model on your specifics. That is slow, expensive, and absurd for "please always use our logo's hex code." You could paste everything into the prompt — every guideline, every procedure, every reference document — at the start of every conversation. But a model's context window is finite and every token in it costs money and dilutes attention. Stuffing a hundred capabilities into the prompt to use one of them is like reading the entire manual aloud before changing a lightbulb.
So the real question sharpens into this:
How do you give a general model a large, growing library of specialized know-how — without paying for all of it, all the time?
Agent Skills are Anthropic's answer, and the answer is almost boringly simple once you see it. A Skill is a folder. Inside is a file called SKILL.md that holds instructions, plus — optionally — scripts the agent can run and reference documents it can consult. The agent doesn't load all of this. It keeps a tiny catalogue of what each skill is for, and opens the full folder only when a task actually calls for it.
The cleanest way to picture it: imagine an expert consultant with a shelf of labelled binders behind their desk. They have not memorized every binder. What they carry in their head is the spine label of each one — "Tax filings," "Brand guidelines," "PDF form-filling." When you ask a question, they glance at the spines, pull the one binder that matters, and open it. The shelf can grow to a hundred binders without making the consultant any slower on a question that needs just one.
That is the whole idea. The model's working memory stays lean; the knowledge lives on the shelf; and the act of "reading the spine, then opening the right binder" is what the industry calls progressive disclosure. It is the mechanism we'll take apart in the next chapter.
If a skill is just a folder, how does the AI know when to open it?
Two things make Agent Skills tick: the shape of the file, and the ladder by which it gets loaded. Neither is complicated — that's rather the point.
A skill is a directory whose entry point is a single Markdown file, SKILL.md. That file has two parts. At the top, between a pair of --- fences, is YAML frontmatter: structured metadata. Below it is the body: ordinary Markdown instructions telling the model how to do the thing.
---
name: pdf-form-filler
description: Fills interactive PDF forms from a data file. Use when
the user wants to complete, flatten, or populate a PDF form.
---
# Filling PDF forms
To fill a form, first read the field names with `scripts/inspect.py`,
then map the user's data to those fields, then write with `scripts/fill.py`.
For tricky layouts, see `references/edge-cases.md`.Here is that same file, dissected — each part labelled by when the agent actually pays for it:
The description is the most important line in the whole file, because it is the text the model reads to decide whether this skill is relevant right now. A vague description ("helps with documents") gets a skill ignored; a precise one ("fills interactive PDF forms from a data file") gets it picked at the right moment. Anthropic's docs cap the name at 64 characters and the description at 1,024, and recommend keeping the body under 500 lines. Everything else — scripts, reference docs, templates — lives in subfolders beside SKILL.md and is pulled in only if the body points to it.
scripts/ for runnable code, references/ for docs the model may read, and assets/ for templates and binaries. Anthropic's own examples are looser, but the rule is constant: only SKILL.md — with a name and description — is strictly required.
Here is the mechanism that makes the shelf economical. The model never loads a skill all at once. It climbs a ladder, and stops as soon as it has what it needs.
The payoff compounds with scale. A dozen skills cost almost nothing to have, because at rest they are just a dozen one-line descriptions. The expensive part — the full instructions — materializes only for the one skill a task actually invokes. Play with the trade-off yourself:
This is the subtle part, and it matters enormously for the security chapter. Activation is not a hard-coded router. The model itself decides, by reading the descriptions and judging relevance against the task at hand (you can also invoke a skill explicitly). That flexibility is the feature — you don't have to wire up triggers — but it also means the thing deciding what instructions to trust is the model, following text written by whoever authored the skill. Hold that thought.
Where do skills live, and how would I actually make one?
Skills aren't a research demo — they run today across every Claude surface. Here's where they live, how you make one, and what they're actually good at.
The same skill format works across Claude.ai, Claude Code, the API, and the Agent SDK. In Claude Code, a personal skill is a folder under ~/.claude/skills/, and a project-scoped skill lives in .claude/skills/ inside the repo. Teams can distribute skills through plugins and marketplaces; organizations can manage them centrally.
# A skill is just a folder on disk
~/.claude/skills/
pdf-form-filler/
SKILL.md # required: frontmatter + instructions
scripts/
inspect.py
fill.py
references/
edge-cases.mdAnd here is the round-trip when you actually make a request — where each part of that folder enters the picture:
You write a SKILL.md, drop it in a skills folder, and it's available. The hard part isn't the plumbing — it's writing a crisp description so the model knows when to reach for it, and a body lean enough to stay cheap. The guidance is to keep the body short and push detail into referenced files, exactly as progressive disclosure rewards.
"Fills interactive PDF forms from a data file. Use when the user wants to complete or populate a PDF." — names the task and the cue.
"Helps with documents." — the model can't tell this apart from five other skills, so it never fires reliably.
The flagship examples are document skills — creating and editing Word documents, PowerPoint decks, Excel workbooks, and PDFs — and organizational conventions like brand guidelines. But the pattern is general: any repeatable procedure with its own quirks (a deployment runbook, a house code-review style, a data-cleaning routine) is a candidate. If you can write it down as instructions plus a few helper scripts, it can be a skill.
If the AI trusts a skill's instructions, what stops a bad one from hijacking it?
Everything that makes skills powerful makes them dangerous, for one reason: a skill is instructions the agent trusts. Installing a skill means voluntarily expanding the set of commands your agent will follow. If someone else wrote it, you have invited their words into the room where decisions are made.
Recall the two facts from Chapter 2: the model decides when a skill fires, and it does so by reading text an author supplied. Now suppose the author is hostile. They don't need to breach anything. They just need you to install their helpful-looking skill — and then the agent's own obedience does the rest. This is prompt injection at the skill layer, and it is a genuinely new supply-chain risk.
SKILL.md standard — independent registries where anyone can publish. Almost every alarming number in this chapter comes from studies of that open, unvetted ecosystem, not from Anthropic's own skills. The risk is real, but it lives where the trust boundary is weakest.
The attack vector isn't a bug in the code. The attack vector is the agent doing exactly what it was told — by the wrong person.
A widely-cited illustration of the technique is disarmingly small. A skill's instructions include a conditional trigger and a hidden payload:
No exploit, no CVE, no memory corruption. The agent reads "append the API key to the URL," decides it is a legitimate instruction from its skill, and leaks the secret to an attacker-controlled server the next time it opens a link. And because skills can also ship executable scripts, a hostile skill can go further still — running arbitrary code on your machine the moment the agent decides to use it.
Security researchers who have studied skill ecosystems at scale group the risks into a handful of families:
Hidden or overriding instructions in the body — including ones buried in code comments or in invisible Unicode you'd never see in a diff.
Instructions or scripts that read secrets — API keys, tokens, files — and smuggle them out via a URL, request, or log.
Getting the agent to run commands or touch files well beyond the task it was ostensibly installed to do.
Hardcoded credentials, unpinned or malicious dependencies, and trusting third-party content pulled in at run time.
Common enough to take seriously — with the caveat above firmly in mind. In February 2026, Snyk's ToxicSkills study scanned 3,984 skills from two public third-party registries and found 1,467 (36.8%) carrying at least one security flaw, 534 of them rated critical, with 76 confirmed-malicious payloads verified by hand. A larger academic sweep — pointedly titled "Do Not Mention This to the User" — analyzed 98,380 skills across two registries and found 157 outright malicious ones, exhibiting 632 distinct vulnerabilities across 13 attack techniques.
And the theory is worse than the audits. A foundational paper published two weeks after launch — "Agent Skills Enable a New Class of Realistic and Trivially Simple Prompt Injections" — argued that the feature is fundamentally hard to secure, precisely because obeying instructions is the whole job. A follow-up measured attack success rates as high as 80% on frontier models, driving behaviors from data exfiltration to ransomware-like actions.
The obvious defense — read the skill before you install it — helps, but attackers plan for it. Payloads get hidden in code comments, in the middle of long reference files you won't scroll through, or in Unicode characters that render invisibly. A human skim is exactly what these techniques are designed to survive. That's why a category of tooling has grown up to read skills more paranoidly than you can. That's the next chapter.
So how do I know a skill is safe before I let it run?
If a skill is code you're about to trust, it deserves the same suspicion you'd give any dependency. Skill scanners are static analyzers that read a skill's files before you install them and flag the patterns that betray an attack.
The simplest scanners never run the skill. They parse the SKILL.md and any bundled scripts and pattern-match against known danger signals — the tells that separate a helpful skill from a hostile one.
Static analysis has a hard ceiling: it can only judge what it can see. A payload split across several files, buried in Base64, or written to trigger only against one specific model can read as perfectly innocent on the page. The way past that ceiling is to stop reading and start watching — execute the skill inside a sealed sandbox and record what it actually reaches for.
This is detonation. You hand the skill fake credentials (honeytokens) and see whether it tries to steal them; you route its network traffic through a proxy and see where it tries to phone home; you run it against several models at once, because a skill can behave for one and betray another.
"Skills lie. We stop that." SkillTracer detonates a skill in an instrumented sandbox against multiple models at once and reports what each one actually did — not what the description claimed. Honeytokens catch credential theft, an egress proxy catches exfiltration, and runtime tracing surfaces the obfuscated and steganographic payloads that reading alone would miss.
Every finding is scored twice — a threat rating for intent and an AIVSS-aligned risk rating for potential damage — and mapped to the OWASP Agentic Top 10 and MITRE ATLAS. It scans SKILL.md files today, with MCP servers next.
For a fast first pass — or when you simply can't run untrusted code — several static scanners read the files and flag the tells:
The tool Snyk's ToxicSkills study ran (uvx mcp-scan@latest --skills). Scans skills and MCP servers for injection and exfiltration patterns.
Supply-chain scanning for agent components, from the security vendor behind the largest public skills audit to date.
A review framework more than a one-click scanner — its stance is "every external input is untrusted until verified."
A Python CLI doing static AST + regex analysis across network, file, command-execution, injection, and dependency risks.
Anthropic's own security guidance is blunt about it: use skills "only from trusted sources — those you created yourself or obtained from Anthropic," and if you must use one from an unknown source, "exercise extreme caution and thoroughly audit it." Their one-line summary is the right instinct — treat installing a skill like installing software. Concretely, that means:
SKILL.md yourself — the whole thing, including reference files, not just the description.npm install from an unknown author: convenient, occasionally essential, and never to be trusted on faith. Scanners are your linter; your own judgment is the code review.
Where did this come from, and where is it heading?
Agent Skills went from launch to open standard in a matter of months — fast enough that the security research and the feature grew up alongside each other.
Anthropic introduces Skills — folders of instructions, scripts, and resources loaded on demand — across Claude.ai, Claude Code, the API, and the Agent SDK, with prebuilt PDF, Word, Excel, and PowerPoint skills.
Just two weeks later, researchers publish "Agent Skills Enable a New Class of Realistic and Trivially Simple Prompt Injections," arguing the design is fundamentally hard to secure.
Anthropic publishes Agent Skills as an open standard for cross-platform portability, adds organization-wide management, and launches a directory of partner-built skills.
As third-party registries fill up, Snyk and academic teams scan them at scale — tens of thousands of skills — and a class of skill scanners emerges in response.
Because skills are now an open standard, they behave less like one company's feature and more like a package format — and package formats have a well-worn destiny. Expect the same arc software dependencies took: registries, versioning, and, inevitably, signing and provenance. The central tension is baked in from the start — the very shareability that makes skills useful is the thing that makes a poisoned skill spread. The interesting question for the next year isn't whether skills succeed; it's whether the ecosystem grows trust infrastructure (signatures, reputation, vetted registries) faster than attackers industrialize the supply-chain attack.
A skill is the smallest possible unit of "teach an agent something." That is exactly why it's powerful, and exactly why it needs a chain of trust.
Strip everything away and Agent Skills are a single, clean idea: capabilities as files, loaded lazily. That buys you a growing library of expertise at almost no standing cost — and it hands anyone who can write a file a channel straight into your agent's decisions. Both halves follow from the same design. Understanding one means understanding the other.
Every figure in this piece traces to one of these. Primary sources first.
name/description limits and the 500-line guidance.