Agent Skills: packaging expertise as files, not code

Count what your agent knows before the user types anything. A coding agent wired to a dozen MCP servers — GitHub, Slack, Jira, Postgres, Sentry, the usual suspects — carries every tool definition in context: name, description, and a full JSON schema per tool. Call it 12 servers averaging 18 tools each at ~450 tokens per definition. That's roughly 97k tokens of a 200k window, spent on every single request, whether the task touches Jira or not. Anthropic's own engineering write-up on MCP describes agents connected to enough tools that they process hundreds of thousands of tokens before reading the actual request.

Meanwhile the expertise that would actually change the agent's output — the incident-postmortem structure your staff engineer refined over five years, the exact seven steps for closing the quarterly books, the reason your team never uses that one library — lives in a wiki the model has never seen. So someone pastes it into the system prompt, where it now taxes the 95% of requests that don't need it. Both failures have the same root cause: everything the agent might need is priced as if the agent needs it now.

Agent Skills are the fix for the expertise half, and the mechanism is blunt: put the expertise in files, tell the model the files exist, and let it read them when relevant. A skill is context engineering applied to knowledge — the same discipline covered in managing agent context windows, packaged as a portable folder.

A skill is a folder with a manifest

Anthropic shipped skills across Claude products on October 16, 2025, then published the format as an open standard that December. The spec is small enough to fit in your head. A skill is a directory containing a SKILL.md file, optionally alongside anything else:

pdf-processing/
├── SKILL.md          # required: frontmatter + instructions
├── FORMS.md          # optional: specialized guide, loaded only for form tasks
├── REFERENCE.md      # optional: detailed API reference
└── scripts/
    └── fill_form.py  # optional: executable code the agent runs, never reads

SKILL.md starts with YAML frontmatter carrying exactly two required fields — name (max 64 characters, lowercase letters, numbers, and hyphens only) and description (max 1,024 characters, non-empty). Those limits come from the spec, and Anthropic's platform rejects violations at upload. Here is the shape of Anthropic's documented pdf-processing example:

---
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()

For advanced form filling, see FORMS.md.
For deterministic field extraction, run scripts/fill_form.py — do not
reimplement it inline.

Notice what the description does: it states what the skill does and when to trigger it. That second clause is not documentation polish. The description is the only part of the skill the model sees when deciding whether to load it — it is the skill's entire API surface at selection time. A description that says "PDF utilities" will lose to one that says "use when the user mentions PDFs, forms, or document extraction," every time, for the same reason a vague function name loses in tool schema design.

The body is procedural knowledge in plain markdown: workflows, worked examples, edge cases, the stuff you'd put in an onboarding doc for a new hire. Anthropic's guidance says keep it under ~5k tokens; Microsoft's implementation docs say under 500 lines. Same instinct, different unit: if the body is growing past that, split the overflow into separate reference files and link them, because — as we're about to see — linked files are free until read.

Progressive disclosure is the entire mechanism

Everything interesting about skills reduces to when each piece of content enters the context window. The Anthropic platform docs define three levels, and the token economics differ by orders of magnitude between them:

Level	When loaded	Token cost	Content
1: Metadata	Always, at startup	~100 tokens per skill	name + description from frontmatter
2: Instructions	When the skill triggers	Under ~5k tokens	The SKILL.md body
3+: Resources & scripts	As needed	Zero until accessed	Reference files load when read; scripts run via shell, only output enters context

Level 3 is the part people underestimate. A bundled script is executed, not read — the agent runs python scripts/fill_form.py, and the only tokens spent are the script's stdout ("wrote out.pdf — 14 fields filled"). The 300 lines of PDF-library plumbing inside never touch the context window, and the operation is deterministic instead of being regenerated slightly differently each session. Reference files work the same way: a skill can bundle a 40-page API reference, a database schema, and a dozen worked examples, and the whole pile costs nothing until the agent opens exactly the file the current task needs. There is no practical limit on bundled content because unused content is free.

Here's a full request, end to end:

sequenceDiagram
    participant U as User
    participant AG as Agent
    participant FS as Filesystem
    participant SH as Shell

    Note over AG: system prompt holds name + description of every installed skill — ~100 tokens each
    U->>AG: "Fill out this vendor tax form"
    Note over AG: request matches pdf-processing description
    AG->>FS: read pdf-processing/SKILL.md
    FS-->>AG: instruction body (~1,200 tokens enter context)
    AG->>FS: read FORMS.md (SKILL.md points here for form tasks)
    FS-->>AG: form-filling guide (~900 tokens)
    AG->>SH: python scripts/fill_form.py vendor.pdf fields.json
    SH-->>AG: "wrote vendor-filled.pdf — 14 fields" (script code never loaded)
    AG-->>U: completed form + summary

Note what did not load: REFERENCE.md, because this task didn't need the API details, and the other 49 skills installed on this machine, which contributed only their descriptions. This is a lazy-loading pattern any systems engineer will recognize — page in on fault, not on boot. Philipp Schmid of Google DeepMind compressed the whole idea at the AI Engineer World's Fair, per Latent Space's 2026 trends recap: "Agents are just files."

Implementations differ in plumbing, not pattern. Anthropic's agents read skills with ordinary filesystem operations inside a code-execution environment (in Claude Code, skills live at ~/.claude/skills/ or the project's .claude/skills/; on the API they run in a sandboxed container with no network access). Microsoft's Agent Framework instead exposes explicit load_skill, read_skill_resource, and run_skill_script tools, and describes the same lifecycle as four stages — advertise, load, read, run — with the same ~100-token advertise cost and the same under-5k-token load recommendation. Same protocol, different transport.

The token math

Time to put numbers on the trade. The comparison that matters is standing overhead: what does a unit of capability cost on requests that don't use it?

Standing context cost of capability (illustrative, mid-2026):

MCP, definitions loaded upfront (default client behavior):
  12 servers × ~18 tools × ~450 tokens per JSON schema ≈ 97k tokens
  Paid on EVERY request, used or not.
  At $3/M input tokens: ~$0.29/request of pure definition overhead.
  10k requests/day ≈ $2,900/day before any real work happens.
  Prompt caching cuts the dollar cost ~10× — but not the window:
  ~97k of a 200k context is still occupied by schemas.

Skills, progressive disclosure:
  50 installed skills × ~100 tokens metadata ≈ 5k tokens, always.
  1 triggered skill: body + one reference ≈ 3k tokens, this request only.
  Bundled scripts and unread references: 0 tokens.
  Standing overhead: ~5k vs ~97k — roughly 20× less.

Anthropic's measured version of the same move (tools as code on disk):
  150,000 → 2,000 tokens for one workflow, a 98.7% reduction.

Two honest caveats on that block. First, prompt caching genuinely defangs the dollar cost of big static prefixes — skill metadata and tool definitions are both cache-friendly. What caching cannot recover is window occupancy and attention quality: 97k tokens of schemas still crowd the model's effective working memory and still degrade retrieval from the middle of the context. Second, MCP clients are closing the gap from their side — Anthropic's code-execution approach presents MCP servers as code APIs on disk that the agent discovers on demand, which is progressive disclosure for tools and the subject of the sibling piece on code execution vs. tool calling. The 150k → 2k figure above is that technique. Skills and code-mode MCP are converging on the same insight from opposite ends: the filesystem is a better home for capability than the context window.

{ "type": "context-window", "window": 200000, "title": "Where the window goes: tool schemas vs. skill metadata" }

Agent Skills vs. MCP vs. fine-tuning: the actual trade

"Should I write a skill or an MCP server?" is usually the wrong question — they occupy different layers. The real decision is a three-way trade in context tokens, latency, and maintenance burden:

Dimension	MCP server	Agent Skill	Fine-tuning
Context cost	All tool schemas, typically upfront (10k–100k+ tokens at scale)	~100 tokens/skill until triggered	Zero at inference
Latency profile	Network round-trip per call, plus fatter prompts	One local file read on trigger	None — behavior is baked in
Build cost	Server, JSON-RPC, auth, error handling: days to weeks	A markdown file: hours	Data curation + training + evals: weeks
Update cost	Redeploy the server	Edit a file, commit	Retrain, re-eval, redeploy
Survives a model swap	Yes — it's a wire protocol	Mostly — instructions may need retuning	No — retrain on the new base
Best at	External state, credentials, isolation	Procedure, house style, workflows	Tone, format instincts, small fast models
Characteristic failure	Context bloat, schema sprawl	Rot, mis-triggering, convergence	Drift, cost, staleness

The rule of thumb that falls out: MCP is for connectivity, skills are for procedure, fine-tuning is for behavior that can't be written down. An agent that files expense reports needs an MCP connection to your ERP (auth, external state, process isolation — see how MCP actually works) and a skill that encodes your company's expense policy and the exact validation steps (procedure). The two compose: the skill teaches the agent how your org uses the connection. Anthropic frames them as complementary for exactly this reason.

Fine-tuning enters only when instructions fail. If you can write the expertise down, a skill delivers it at a fraction of the cost and updates with a git commit instead of a training run. Fine-tune for the things prose can't carry — a voice learned from ten thousand examples, sub-second classification on a small model, formats that must survive with zero prompt overhead — and consult the fine-tuning vs. RAG vs. prompting framework before spending the weeks. The startup cost of a skill is a markdown file. The startup cost of an MCP server is a weekend and an OAuth flow you will come to regret. The startup cost of a fine-tune is a data pipeline, an eval suite, and a recurring obligation.

flowchart TD
    Q1{"Does the agent need an\nexternal system with auth?"} -->|yes| MCP["MCP server\n(connectivity + isolation)"]
    Q1 -->|no| Q2{"Can the expertise be\nwritten down as instructions?"}
    Q2 -->|no| FT["Fine-tune\n(behavior, not knowledge)"]
    Q2 -->|yes| Q3{"Needed in most requests?"}
    Q3 -->|yes| SYS["System prompt\n(always-on context)"]
    Q3 -->|no| SKILL["Skill\n(~100 tokens until triggered)"]

    style MCP fill:#374151,color:#fff
    style FT fill:#9f1239,color:#fff
    style SYS fill:#0e7490,color:#fff
    style SKILL fill:#00e5ff,color:#111
    style Q1 fill:#1e293b,color:#e2e8f0
    style Q2 fill:#1e293b,color:#e2e8f0
    style Q3 fill:#1e293b,color:#e2e8f0

What breaks

Skills are nine months old as a shipped feature and the failure modes are already well-documented by people running them daily. Four stand out.

Skills rot per model release

A skill body is not neutral prose — it's instructions tuned, consciously or not, to the model that was current when you wrote it. The skill that says "always use pdfplumber, never PyPDF2" exists because some model release kept hallucinating a PyPDF2 API. The skill that spells out sub-steps in exhaustive detail was written for a model that needed them. Then the next release lands: the hallucination is fixed, the model handles sub-steps natively, and your skill is now dead weight — or actively harmful, steering a better model into a worse workflow to compensate for a bug that no longer exists. This is the same decay curve as prompt engineering, but skills feel more permanent because they live in files with version numbers, so teams forget to question them.

Treat model upgrades as breaking changes for your skill suite. Anthropic's own authoring guidance puts evaluation first: build a small set of representative tasks per skill and re-run them when the base model changes. A skill without an eval is a cache with no invalidation strategy.

Context-budget creep and mis-triggering

Each skill costs ~100 tokens forever. Fifty skills is 5k tokens — fine. But skill marketplaces and plugin bundles make installation a one-click habit, and the math is only half the problem. The worse half is selection: the model chooses skills by matching your request against fifty-odd descriptions, and past a few dozen, descriptions start to overlap. Two skills both claim spreadsheet work; the model picks the wrong one, or — quieter and worse — picks neither, and you get generic output with no error anywhere. A skill that doesn't trigger doesn't fail loudly. It just silently doesn't help, and you discover it three weeks later when someone asks why the agent stopped following the deploy checklist.

Practitioners hit this fast enough that it acquired a nickname — Matt Pocock was warning about "skills hell" within months of launch, and his recommendation matches what the selection math predicts: fewer, smaller skills with sharply distinct descriptions. Prune skills like you prune dependencies. If a skill hasn't triggered in a month, it's either mis-described or unnecessary.

Convergence: everyone runs the same skills, ships the same output

The portability that makes skills attractive — one folder format, an open spec, dozens of compatible clients — also makes them viral. A good design skill or code-review skill gets a GitHub repo, the repo gets 20k stars, and now a meaningful slice of the industry is running identical expertise. Paul Bakaus made this the center of his skill-engineering argument at AIEWF 2026: when everybody uses the same skill, everything ends up looking the same. Laravel already ships official skills through its first-party Boost package; every agent-built Laravel app that installs it inherits the same instincts.

So the strategic value inverts. Public skills are table stakes — they raise the floor and erase differentiation simultaneously, the same dynamic as everyone using the same UI component library. The skills that constitute an edge are the ones encoding your postmortem culture, your pricing-page voice, your data team's validation gauntlet — the procedure a competitor can't clone from a repo. Which means the uncomfortable conclusion: writing and maintaining private skills is now part of the engineering work, not a side quest.

Skills are an attack surface with a package manager

A skill is instructions plus executable code, running with whatever permissions the agent has. Read that sentence again: it describes a prompt-injection vector with a distribution channel. A malicious skill can direct the agent to exfiltrate data or invoke tools in ways that don't match its stated purpose, and Anthropic's docs are blunt about it — treat installing a skill like installing software, audit every bundled file, and be especially suspicious of skills that fetch external URLs, because fetched content can carry injected instructions even when the skill itself is honest. On the API, skills at least run in a network-isolated container. In Claude Code, they have the same network access as anything else on your laptop. The ecosystem is currently at the "curl | bash" stage of its security maturity, and it knows it.

The decision in practice

Here's the order of operations I'd actually defend. Start every piece of agent guidance in the system prompt — it's the simplest thing that works. The second time you paste the same instructions into a session, or the moment your system prompt crosses a couple thousand tokens with material most requests don't use, extract the situational parts into skills. Add MCP when — and only when — the agent needs external state behind auth; and per the token math above, prefer code-mode/on-demand tool loading over schema dumps as your server count grows. Reach for fine-tuning last, after a skill has demonstrably failed to express the behavior, because everything about it — cost, latency of iteration, model lock-in — is worse except the per-request token bill.

Then run your skills like code, because that's what they are: version them in git, review changes like PRs, attach a small eval set per skill, and re-run the suite on every base-model upgrade. Budget the metadata layer deliberately — a few dozen sharply described skills beat two hundred vague ones, both in tokens and in trigger accuracy. And keep the strategic ledger straight: download public skills to raise your floor, but expect no edge from anything with a star count. The expertise worth packaging is the kind that took your team years to earn. Skills just make it loadable — about 100 tokens at a time, until the moment it's needed.