Anthropic's Agent Skills: how to package reusable knowledge for Claude agents

Anthropic launched Agent Skills as a way to package domain knowledge for Claude agents without bloating the context. The official documentation describes a Skill as a directory of files, a SKILL.md with YAML metadata plus instructions, and optionally scripts and reference materials, which Claude reads using bash commands when the user's request matches the Skill's description.

For those already building agents with MCP and RAG, what's interesting isn't the idea of "giving context to the model" (RAG already does that), but the staged loading mechanism. That's where the cost gain lies, and also where the plug-and-play promise starts to crack.

How it works under the hood: progressive disclosure in three levels

The architecture described by Anthropic separates a Skill's content into three layers, each loaded at a different moment:

• Level 1, metadata (always loaded): the YAML frontmatter with name and description. It stays in the system prompt from initialization onward and costs, according to the doc, about 100 tokens per Skill. It's against this description that Claude compares the request to decide whether to trigger the Skill.
• Level 2, instructions (loaded on trigger): the body of the SKILL.md, which the doc recommends keeping under 5,000 tokens. It only enters the context when Claude executes cat SKILL.md via bash.
• Level 3, resources and code (loaded on demand): extra files (FORMS.md, REFERENCE.md), schemas, templates, and scripts. Reference files only occupy context when read; scripts run via bash and only the output enters the context, never the source code.

In practice, the system prompt lists dozens of installed Skills while only paying for their descriptions. When the user asks for something, Claude reads the corresponding SKILL.md, and if that specific step doesn't need FORMS.md, that file is never opened. The doc gives the example of the pdf-processing Skill: faced with "extract and summarize this PDF," Claude runs cat pdf-processing/SKILL.md, concludes that filling out a form isn't necessary, and skips FORMS.md.

Minimal structure of a SKILL.md

The required file has frontmatter and a markdown body:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

Use pdfplumber to extract text from PDFs:

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

The validation rules are explicit: name accepts a maximum of 64 characters, only lowercase letters, numbers, and hyphens, and cannot contain the reserved words anthropic or claude. The description goes up to 1024 characters and needs to state what the Skill does and when to use it, because it's literally the activation trigger. A vague description is the number one cause of a Skill that "doesn't trigger."

In Claude Code, there's no upload and no API call: just place the directory in ~/.claude/skills/ (personal) or .claude/skills/ (project), and Claude discovers it on its own. That's the fastest path for anyone who wants to test it today, without touching any endpoint.

Skills versus plain RAG: where each one wins

The most useful comparison is with RAG. In a classic RAG pipeline, you embed documents, run vector similarity search, and inject the retrieved chunks into the prompt on every call. That pays a context cost every time and depends on the quality of the retriever.

Skills invert part of that logic. The comparison that makes sense to draw:

• Idle context cost: with RAG, every request loads the retrieved chunks. With Skills, an untriggered Skill costs only the ~100 tokens of its description. If you have a lot of rarely used knowledge, Skills tend to come out cheaper in aggregate.
• Determinism: the doc highlights that scripts run via bash deliver "deterministic operations" without loading code into the context. Filling out a PDF form with fill_form.py is more reliable than asking the model to generate the code on the fly. RAG doesn't offer this axis.
• Latency: Skills add bash round trips (reading SKILL.md, maybe reading REFERENCE.md, maybe running a script). That's more round trips than a single RAG context injection. For short, frequent answers, plain RAG can be faster; for multi-step tasks that reuse procedures, the cost pays off over time.
• Actual semantic search: here RAG remains irreplaceable. Skills match the request against natural-language descriptions; they don't perform similarity-based retrieval over millions of chunks. If your use case is "find the relevant passage among 50,000 documents," that's RAG, not a Skill.

The honest reading is that the two complement each other: a Skill can contain the instructions and scripts for a workflow, and within it point to a vector index when semantic search is needed.

Where plug-and-play breaks down

The part that optimistic announcements tend to downplay is in the limitations sections of the doc itself, and it matters for those building in Brazil who rely on integrating external APIs.

No network on the API and on Bedrock/Foundry. Skills running via the Claude API run in an isolated container with zero network access and no runtime package installation. Only the code execution tool's pre-installed packages are available. In other words: a Skill that needs to call your internal API, query a remote database, or fetch an exchange rate simply doesn't work in this environment. In Claude Code, by contrast, the Skill has the same network access as any program on the machine, and on claude.ai it depends on admin configuration.

Skills don't sync across surfaces. A Skill uploaded to claude.ai doesn't show up in the API, and vice versa. Claude Code is filesystem-based and lives separate from the other two. If you want the same Skill in three places, you upload it three times.

Different sharing models. On claude.ai, a Skill is per-user, with no centralized admin management or org-wide distribution. On the API it's workspace-wide. In Claude Code it's personal, per-project, or via Plugins. For a team, this means "create once, everyone uses it" only holds within each surface, with distinct rules.

Security is the installer's responsibility. The doc is emphatic: only use Skills from trusted sources. Because a Skill brings instructions and executable code, a malicious Skill could direct Claude to invoke tools or exfiltrate data in ways that don't match its stated purpose. Skills that fetch data from external URLs are flagged as a particular risk, since the downloaded content may contain injected instructions. The recommendation is to treat installation like installing software: audit the SKILL.md, scripts, and all resources before running it on a system with sensitive data. Enterprise organizations can turn on Skill content scanning on claude.ai and Claude Cowork, but this does not cover Skills uploaded via the Skills API or the Console.

Data retention. Skills are not covered by ZDR (zero data retention). Definitions and execution data follow Anthropic's standard retention policy, a detail relevant to anyone with compliance requirements.

When it's not worth it

Skills aren't the answer for every agent. They're not worth it when:

• your workflow depends on network calls and the target is the API or Bedrock/Foundry, where the container is isolated;
• the real problem is large-scale semantic retrieval, which remains RAG's job;
• the guidance is a one-off instruction for a conversation (in which case a plain prompt is enough, without the overhead of a file);
• you need centralized management and automatic distribution for a large team on claude.ai, a scenario the doc explicitly says isn't supported.

For those who already know MCP, a useful way to frame it: MCP connects the agent to tools and external sources via a protocol; Skills package how the agent should work (procedures, deterministic scripts, reference materials) within the filesystem itself. A mature agent likely uses both, and the SKILL.md is the natural place to document the step-by-step usage of the MCP tools you've already exposed.