Malhar Ujawane

Blog

Post·

What are agent skills? SKILL.md and progressive disclosure

Agent skills are folders with a SKILL.md that agents load in stages. The spec, a runnable demo, and what each stage costs in tokens.

What are agent skills? SKILL.md and progressive disclosure

Agent skills are folders of instructions, scripts and reference files that an AI agent loads only when a task needs them. Each skill has a SKILL.md file with a name and a description at the top; the agent sees those two fields at startup and reads the rest on demand. On December 18, 2025, Anthropic published the format as an open standard at agentskills.io, with a specification and a small reference library.

What happened to agent skills this week?

Anthropic first shipped skills for Claude in October. This week’s announcement added skills that Team and Enterprise admins can roll out to everyone, a directory of partner-built skills from Notion, Canva, Figma, Atlassian and others, and the open standard. The agentskills/agentskills repo holds the spec and skills-ref, a Python library that validates a skill and builds the prompt block an agent needs.

On launch day the site’s adoption section listed Claude, Claude Code, Cursor, VS Code, GitHub, OpenCode, Amp, Letta and Block. Nine days earlier, Anthropic donated MCP to the Linux Foundation’s new Agentic AI Foundation (I explained MCP here), so this is the second agent format it has opened up this month.

Why do agent skills matter to a builder?

An agent’s system prompt tends to collect everything a team knows: how branches are named, how invoices look, which test command to run. Every one of those rules is billed on every request, whether the task needs it or not. Skills split that prompt into chapters with a table of contents. The agent always pays for the table of contents, a name and a sentence or two per skill, and pays for a chapter only when it opens it. Anthropic calls this progressive disclosure.

It’s the same cost argument I made about tool definitions in code execution with MCP: whatever sits in the context on every turn gets paid for on every turn.

Skills also travel well. A skill is Markdown plus scripts in a folder, so it can live in git, go through code review, and work in any agent that reads the format.

What does an agent skill look like?

The smallest valid skill is one file in a folder with the same name:

---
name: release-notes
description: Writes user-facing release notes from git history. Use when the user asks for release notes, a changelog entry, or "what changed since vX".
---

# Release notes

1. Run `git log --oneline PREVIOUS_TAG..HEAD`.
2. Drop merge commits, dependency bumps and anything under `test/`.
3. Group the rest under "New", "Fixed" and "Changed". One line each, user-facing words.
4. End with the exact compare link if the repo is on GitHub.

The specification requires two frontmatter fields. name is 1 to 64 characters of lowercase letters, digits and hyphens, and it must match the folder name. description can run to 1,024 characters and should say what the skill does and when to use it. The optional fields are license, compatibility, metadata and an experimental allowed-tools. The body after the frontmatter is free-form Markdown.

A bigger skill adds folders. Here is a toy one that drafts a GST invoice (the same made-up invoice from my MCP post), with a script for the math and a reference file it only needs for clients outside India:

skills/
├── gst-invoice/
│   ├── SKILL.md
│   ├── scripts/invoice.py
│   └── references/export.md
├── release-notes/
│   └── SKILL.md
└── Release_Notes/          # broken on purpose, see below
    └── SKILL.md
---
name: gst-invoice
description: Drafts a freelance invoice in Indian rupees with GST. Use when the user asks for an invoice, a quote with tax, or the GST on an amount.
license: MIT
---

# GST invoice

1. Ask for hours, hourly rate in rupees, and the client's state.
2. Run `python scripts/invoice.py HOURS RATE SAME_STATE` where SAME_STATE is `yes`
   if the client is in the same state as the freelancer, otherwise `no`.
3. Paste the script's output into the invoice table. Never do the tax math yourself.
4. If the client is outside India, read `references/export.md` before writing anything.

Step 3 is the part I like most. Tax math belongs in code, where it gives the same answer every time, and the model only reads the printed result. The script is 13 lines of Python, and the 18% rate in it is an example input, not tax advice:

$ python skills/gst-invoice/scripts/invoice.py 12.5 2500 no
Subtotal: ₹31,250
IGST 18%: ₹5,625
Total: ₹36,875

How do agent skills load into the context window?

In three stages, and you can measure each one. This script validates every skill in the folder with skills-ref, prints the block an agent would put in its system prompt, and counts tokens at each level:

# budget.py: what each level of an Agent Skill costs in context.
# pip install "git+https://github.com/agentskills/agentskills@f990ba1#subdirectory=skills-ref" tiktoken==0.12.0
from pathlib import Path
import tiktoken
from skills_ref import validate, to_prompt

enc = tiktoken.get_encoding("o200k_base")      # OpenAI's tokenizer; other tokenizers give different counts
tok = lambda s: len(enc.encode(s))

dirs = sorted(Path("skills").iterdir())
good = []
for d in dirs:
    problems = validate(d)
    print(f"{d.name:14} {'ok' if not problems else 'INVALID'}")
    for p in problems:
        print(f"   - {p}")
    if not problems:
        good.append(d)

print("\nLevel 1, loaded at startup for every skill:")
block = to_prompt(good)
print(block)
print(f"-> {tok(block)} tokens for {len(good)} skills")

print("\nLevel 2 and 3, loaded only when used:")
for d in good:
    body = tok((d / "SKILL.md").read_text())
    extra = sum(tok(f.read_text()) for f in d.rglob("*") if f.is_file() and f.name != "SKILL.md")
    print(f"{d.name:14} SKILL.md {body:4} tokens   bundled files {extra:4} tokens")

Output (Python 3.13.5, skills-ref at commit f990ba1 from December 18, tiktoken 0.12.0):

Release_Notes  INVALID
   - Unexpected fields in frontmatter: version. Only ['allowed-tools', 'compatibility', 'description', 'license', 'metadata', 'name'] are allowed.
   - Skill name 'Release_Notes' must be lowercase
   - Skill name 'Release_Notes' contains invalid characters. Only letters, digits, and hyphens are allowed.
gst-invoice    ok
release-notes  ok

Level 1, loaded at startup for every skill:
<available_skills>
<skill>
<name>
gst-invoice
</name>
<description>
Drafts a freelance invoice in Indian rupees with GST. Use when the user asks for an invoice, a quote with tax, or the GST on an amount.
</description>
<location>
/tmp/demo/skills/gst-invoice/SKILL.md
</location>
</skill>
<skill>
<name>
release-notes
</name>
<description>
Writes user-facing release notes from git history. Use when the user asks for release notes, a changelog entry, or &quot;what changed since vX&quot;.
</description>
<location>
/tmp/demo/skills/release-notes/SKILL.md
</location>
</skill>
</available_skills>
-> 162 tokens for 2 skills

Level 2 and 3, loaded only when used:
gst-invoice    SKILL.md  181 tokens   bundled files  247 tokens
release-notes  SKILL.md  115 tokens   bundled files    0 tokens

Level 1, metadata. At startup the agent puts each skill’s name, description and file path in its system prompt. The spec budgets about 100 tokens per skill; my two cost 162 together. The <available_skills> XML is the format the integration guide recommends for Claude, and other agents may format it differently.

Level 2, instructions. When a request matches a description, the agent reads the whole SKILL.md. There’s no special API for this: a filesystem-based agent runs something like cat /path/to/SKILL.md, and a tool-based agent gets a tool that returns the file. The spec recommends keeping the body under 5,000 tokens and 500 lines.

Level 3, files. Scripts and references load only if the instructions send the agent to them. Scripts get executed, so their source code stays out of the context. invoice.py is 193 tokens of Python; what lands in the context is its 25-token output.

Four horizontal bars. At startup, a black bar of 162 tokens of metadata. After activation, the same bar plus an orange 181-token segment for SKILL.md, 343 total. After the script runs, a small light-orange 25-token segment is added, 368 total, highlighted. A dashed bar shows 543 tokens for loading every file of both skills up front.

With two skills the saving is small: 368 tokens against 543 for loading everything. The point shows up at scale. At roughly 80 tokens of metadata per skill, 50 skills would cost about 4,000 tokens at startup (my arithmetic from the numbers above, not a measurement), while their bodies and files stay on disk until a task needs one of them. I showed in what a context window is how fast fixed overhead eats into a window when it’s resent every turn.

How are agent skills different from MCP and system prompts?

They answer different questions. A system prompt is text the model always sees. An MCP server gives the model functions to call in a separate process, and every connected tool’s schema sits in the context. A skill is instructions and code that the agent reads and runs inside its own environment, in stages.

System prompt MCP server Agent skill
What it is Text A server with tools, resources and prompts A folder with SKILL.md, scripts and files
When it’s in context Always Tool schemas, whenever the server is connected Name and description always; the rest on demand
Runs code No Yes, on the server Yes, scripts in the agent’s environment
Needs Nothing A running server A filesystem, plus code execution for scripts

They combine well. A skill can tell the agent which MCP tools to call and in what order; Anthropic’s engineering post mentions exactly that pairing as something it’s exploring.

Where do agent skills break?

A vague description means the skill never fires. The model decides from the description alone whether to open a skill. The spec’s own bad example is description: Helps with PDFs. I’d write descriptions the way a user would phrase the request, with the nouns they’d use (“invoice”, “GST”, “quote with tax”).

The validator only checks format. skills-ref validate caught three problems in Release_Notes: uppercase, an underscore, and a top-level version field the spec doesn’t allow (it belongs under metadata). It can’t tell you that step 2 of your instructions is wrong.

A skill is code you run. Anthropic’s engineering post says plainly that malicious skills “may introduce vulnerabilities in the environment where they’re used or direct Claude to exfiltrate data and take unintended actions.” The integration guide lists sandboxing, allowlisting trusted skills, asking before dangerous operations, and logging every script run. I’d treat a skill from the internet like a shell script from the internet: read it before you install it. Instructions inside a skill are also one more place for injected text to reach the model, the same problem I wrote about in AI browsers and prompt injection.

Scripts need an environment. In Claude’s apps, skills require Code Execution and File Creation to be turned on. An agent without a filesystem can still read a SKILL.md as text, but it can’t run scripts/invoice.py.

Portable on paper. The file format is shared. How each agent matches descriptions, when it activates a skill, and whether it honors allowed-tools (the spec says support “may vary between agent implementations”) are up to each product. A skill that works in one agent should be tested in the next one.

Is the open standard worth building on?

My opinion: yes, for team procedures. A skill is a cheap way to give an agent team-specific knowledge: Markdown and a few scripts in a repo, with no server to run and nothing to deploy. I’d use skills for “how we do X” and MCP servers for live access to systems, and expect most agents to need both. What would change my mind is evidence that agents pick the wrong skill once they have hundreds installed; then the table of contents stops working and skills would need retrieval of their own.

FAQ

Are agent skills only for Claude?

No. The format is an open standard, and on December 18, 2025 the agentskills.io adoption list included Cursor, VS Code, GitHub, OpenCode, Amp, Letta and Block alongside Claude and Claude Code.

Do skills cost tokens when they aren’t used?

A little. Every installed skill’s name, description and path go into the system prompt at startup, about 80 tokens each in my demo. The SKILL.md body and bundled files cost nothing until the agent reads them.

What is the difference between a skill and an MCP server?

An MCP server is a separate process that exposes tools the model can call. A skill is a folder of instructions and scripts that the agent reads and runs itself. Skills teach a procedure; MCP connects a system. A skill can include steps that call MCP tools.

How do I check that a skill is valid?

Install skills-ref from the agentskills repo and run skills-ref validate path/to/skill. It checks the frontmatter fields, the naming rules and that the folder name matches name. The README notes the library is for demonstration, not production.

Sources

Get new posts in your inbox

© 2026 Malhar Ujawane. Built with Astro.