Understanding Agent Skills Link to heading

If you’ve used Claude Code, or watched an AI agent debug the same kind of error for the hundredth time like it was the first, you’ve run into the problem Agent Skills were built to solve. Large language models are broadly capable but they don’t remember how your team does things. Every session starts from zero. A coding agent that has fixed the same null pointer exception a hundred times still approaches the hundred and first as if it’s never seen it before, because whatever it learned last time disappeared the moment the context window closed.

Agent Skills are Anthropic’s answer to that problem, and in the ten months since launch they’ve become one of the more consequential ideas in how people build with LLMs. This post covers what they are, why they exist, how the mechanics actually work, some real code, and then the honest part: what’s still broken and where the research says this is headed.

The problem in plain terms Link to heading

An LLM’s knowledge lives in two places. There’s what got baked in during training, which is broad but generic and frozen at a point in time. And there’s what you put in the prompt, which is current and specific but has to be re-supplied every single time.

Neither of those is a good place to put “our team’s data pipeline always fails silently on the region column unless you cast it first” or “always run the verification script before submitting an expense report.” That kind of knowledge is procedural. It’s about how to do a recurring task correctly in your specific environment, and it needs to persist across sessions without eating your context budget every time the agent starts up.

Fine-tuning can encode this, but it’s expensive, slow to update, and hard to share. Retrieval-augmented generation can surface relevant text, but the retrieved passages are passive. They can describe a process; they can’t bundle a script, define when to trigger, or reshape what tools the agent is allowed to use next.

Agent Skills sit in between. A skill is a self-contained folder: a required SKILL.md file plus optional scripts, reference docs, and templates. The agent discovers it, decides when it’s relevant, and loads it only when needed.

Where this came from Link to heading

Anthropic launched Agent Skills across Claude’s product surface in October 2025, then released the format as an open standard two months later, in December 2025. The uptake was fast. Within about four months the reference skills repository had passed 62,000 GitHub stars, partner-built skills started showing up from companies like Atlassian, Figma, Canva, Stripe, and Notion, and other frontier model providers built structurally similar systems of their own.

The parallel development worth knowing about is the Model Context Protocol, or MCP, which Anthropic introduced in late 2024 and donated to the newly formed Agentic AI Foundation in December 2025. MCP and Skills solve different problems and work together well: MCP standardizes how an agent connects to external tools and data sources, while a skill supplies the procedural knowledge for what to do with that connection once it’s made. A skill might tell an agent to use a specific MCP server, how to interpret what comes back, and what to do if the connection fails.

How a skill actually works Link to heading

The core mechanism is called progressive disclosure, and it’s the single most important idea to understand if you want to build good skills. It happens in three stages.

Discovery. When an agent starts up, it loads only the name and description field from every available skill’s frontmatter. This is deliberately tiny, usually a few dozen tokens per skill. The point is that an agent can be aware of hundreds of skills without spending meaningful context on any of them until one is actually needed.

Activation. When a task matches a skill’s description closely enough, the agent reads the full body of SKILL.md into context. This is where the actual instructions live: the procedure, the gotchas, the examples.

Execution. The agent follows those instructions, and only now, if the instructions call for it, does it load a bundled script or a reference file from a subdirectory. Those files sit untouched on disk until something in the loaded instructions specifically points to them.

The analogy that shows up again and again in Anthropic’s own writing is a new hire’s onboarding guide. You don’t hand a new employee the entire employee handbook memorized on day one. You give them a table of contents, they find the chapter relevant to today’s task, and if that chapter references an appendix, they go pull it only when they actually need it. That’s exactly the shape of a skill.

What a skill looks like on disk Link to heading

A minimal skill is genuinely just a folder and one file:

pdf-processing/
├── SKILL.md          # required: YAML frontmatter + instructions
├── scripts/           # optional: executable code
├── references/         # optional: docs the agent reads on demand
└── assets/            # optional: templates, static resources

And SKILL.md itself is just YAML frontmatter followed by markdown. Here’s a genuinely minimal one:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---
Use pdfplumber for text extraction. For scanned documents, fall back to
pdf2image with pytesseract.

## Extract text

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

The name field has to match the parent directory name, use only lowercase letters, numbers, and hyphens, and stay under 64 characters. The description field is capped at 1024 characters and it is doing almost all the work in the whole system, because it’s the only thing the agent sees before deciding whether to load the rest. A vague description like “Helps with PDFs” will quietly fail to trigger on the exact tasks it should handle. A better one names both what the skill does and when to reach for it:

description: >
  Extracts text and tables from PDF files, fills PDF forms, and merges
  multiple PDFs. Use when working with PDF documents or when the user
  mentions PDFs, forms, or document extraction.

A worked example: gotchas Link to heading

The single highest-value thing you can put in a skill isn’t a polished explanation of the domain. It’s a list of gotchas: sharp, specific corrections to mistakes the agent will otherwise make, because they defy what a reasonable assumption would be. This is the part of a skill that a generic prompt could never replicate, because it’s institutional knowledge, not general knowledge.

## Gotchas

- The `users` table uses soft deletes. Queries must include
  `WHERE deleted_at IS NULL` or results will include deactivated accounts.
- The user ID is `user_id` in the database, `uid` in the auth service,
  and `accountId` in the billing API. All three refer to the same value.
- The `/health` endpoint returns 200 as long as the web server is running,
  even if the database connection is down. Use `/ready` to check full
  service health.

Nobody derives this from first principles. Someone learned it the hard way once, and now it lives in the skill instead of being relearned by every future task.

A worked example: plan, validate, then execute Link to heading

For anything destructive or batch-oriented, the more reliable pattern is to have the agent build a plan in a structured format through relentless questioning, check that plan against a source of truth, and only then act on it.

## PDF form filling

1. Extract form fields: `python scripts/analyze_form.py input.pdf` → `form_fields.json`
2. Create `field_values.json` mapping each field name to its intended value
3. Validate: `python scripts/validate_fields.py form_fields.json field_values.json`
4. If validation fails, revise `field_values.json` and re-validate
5. Fill the form: `python scripts/fill_form.py input.pdf field_values.json output.pdf`

Step 3 is the important one. The validation script checks the plan against reality before anything irreversible happens, and a good validator returns an error specific enough for the agent to fix itself, something like “field ‘signature_date’ not found, available fields are customer_name, order_total, signature_date_signed” rather than a bare failure.

What’s actually happening in practice Link to heading

It’s worth being precise here about what’s been observed rather than what people assume.

Skills help, but not evenly, and not automatically. Benchmarking on curated, human-verified skills has shown they can raise agent success rates by double digit percentage points on average, a real and substantial effect that held up well enough that a smaller model equipped with good skills could beat a larger model working without any. But self-generated skills, meaning skills an agent wrote for itself with no human review, have actually made things worse on average in testing. The likely mechanism is that self-generated skills tend to encode overly specific or subtly wrong heuristics that a human reviewer would have caught.

The benefit also looks wildly uneven by domain. Skills tend to produce large improvements in domains like healthcare and manufacturing, but much smaller gains in software engineering and mathematics. The likely explanation is that skills add the most value where a model’s training data was thin or unstructured to begin with. In domains like code and math, where the model already saw enormous amounts of procedural data during pretraining, an external skill has less to add.

The security picture is worse than most people building with skills realize. Large-scale audits of community-contributed skills pulled from public marketplaces have found that roughly a quarter contain at least one real vulnerability, spanning things like prompt injection, credential exfiltration, and privilege escalation. Skills that bundle executable scripts are meaningfully more likely to be vulnerable than instruction-only skills. Confirmed malicious skills tend to fall into two recognizable patterns: “data thieves” that exfiltrate credentials through supply chain tricks, and “agent hijackers” that manipulate the agent’s decision-making through the instructions themselves.

This isn’t hypothetical. The most concrete case so far is an incident from early 2026 involving a popular community agent framework, where attackers uploaded malicious skills to its public registry, combining metadata poisoning with prompt injection to get agents to install credential-stealing malware and drain cryptocurrency wallets. It’s worth being careful with the exact scale here, because different audits reported different totals as the investigation progressed, and early estimates in fast-moving security incidents often get revised down once more careful review comes in.

The core problem underneath all of this is that skills currently operate on implicit trust. Once an agent loads a skill, everything in that skill, instructions and code alike, gets treated as authoritative. There isn’t yet a widely deployed equivalent of a package manager’s permission system, where a skill has to declare what it needs access to before it gets that access.

Skill selection breaks down at scale. As libraries grow past some threshold, the accuracy of picking the right skill for a task tends to degrade sharply rather than gradually. This matters more than it sounds like it should, because it means the progressive disclosure trick that makes skills cheap to keep around doesn’t automatically make them cheap to choose between once you have hundreds or thousands of them.

The open gaps Link to heading

A few problems keep showing up as genuinely unsolved rather than just underdeveloped.

Portability is aspirational, not real. Skills are an open format on paper, but a skill written and tested against one agent’s specific execution environment, tool signatures, and quirks often doesn’t transfer cleanly to another. Nobody has a universal skill runtime yet.

Verification and testing tooling barely exists. Software has unit tests and CI pipelines that have existed for decades. Skills have almost nothing equivalent. There’s no standard way to confirm a skill does exactly what it claims and nothing more, which matters a lot once you remember that a quarter of community skills have at least one vulnerability.

Composition is still ad hoc. Real tasks often need more than one skill working together, and right now conflict resolution, shared resource handling, and failure recovery across multiple active skills are handled case by case rather than through any principled framework.

Permission models are still coarse or missing. The fix that would address most of the security findings, a system where a skill has to declare what tools, files, and network access it needs before being granted them, is a proposal in the research literature right now, not something broadly deployed.

Self-generated skills need a lot more scaffolding before they’re trustworthy. The gap between “an agent learned something useful through practice” and “that knowledge is now a portable, auditable, human-inspectable skill” is still wide. The systems that learn skills through reinforcement learning or autonomous exploration mostly keep that knowledge trapped inside model weights rather than exporting it as something a person could review.

Where it’s headed Link to heading

There’s a reasonably consistent direction of travel here. Anthropic’s own Advanced Tool Use features, introduced not long after Skills itself, already point at one piece of it: tools like programmatic tool search that let an agent look up relevant tools from a large registry rather than having them all pre-loaded, cutting token overhead substantially. That’s the scaling problem for skill libraries starting to get addressed directly.

Governance is the other place where movement seems inevitable rather than optional. The natural next step is a tiered trust system where a skill’s permissions scale with how thoroughly it’s been verified rather than being all-or-nothing, which maps cleanly onto the three layers that already exist in progressive disclosure. Untrusted skills would get metadata-only visibility; verified ones would earn their way up to running code with real system access. Nothing like that is standard yet, but it’s the shape most of the current thinking is converging toward, and incidents like the one described above are exactly the kind of event that tends to accelerate adoption of something like it.

The more interesting long-term question is whether skills are a permanent architectural layer or a stepping stone. One line of thinking treats external skills as infrastructure that agents will keep depending on indefinitely, the same way software keeps depending on external libraries. A different line argues that persistent reliance on external skills carries real costs, retrieval noise, context overhead, and a kind of shallow compliance where a model follows instructions without ever truly internalizing them, and that mature systems should eventually distill reliable, frequently used skills directly into the model’s own weights rather than keep re-loading them from a folder every time. Under that view, a skill repository looks less like a permanent library and more like a training ground, a scaffold you eventually build on top of rather than lean on forever.

Nobody has settled that question yet. But given how fast this went from a launch announcement to a real ecosystem with production usage and a real security incident in under a year, it’s probably not going to stay unsettled for long.