Agent Skills, From the Ground Up

What a Skill is, and the problem it solves

Modern models are capable, but capability is not the same as competence at your task. Anthropic frames the gap plainly: “Claude is powerful, but real work requires procedural knowledge and organizational context.” A model knows how to write Python in the abstract; it does not know your company's brand guidelines, your spreadsheet conventions, or the exact steps your team follows each month to finalize its financial accounts. An Agent Skill is how you give it that knowledge.

The official definition: “Agent Skills: organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks. Skills extend Claude's capabilities by packaging your expertise into composable resources for Claude, transforming general-purpose agents into specialized agents that fit your needs.” The recurring analogy is worth remembering, because it explains nearly every design decision that follows: “Building a skill for an agent is like putting together an onboarding guide for a new hire.”

Sources: anthropic.com · Equipping agents for the real world with Agent Skills (problem statement; definition; onboarding analogy) · platform.claude.com · Agent Skills · Overview · anthropic.com · Introducing Agent Skills.

Why not just put it all in the prompt?

You could paste your conventions into every conversation, or grow your system prompt until it covers every task. The problem is the context window. Anthropic treats it as a scarce shared resource: “The context window is a public good. Your Skill shares the context window with everything else Claude needs to know.” Loading all of your procedural knowledge up front — most of which is irrelevant to any given request — leaves less room for the conversation itself. Skills solve this with the design principle covered in section 3: they make the loaded cost of knowledge proportional to its relevance. As the engineering team puts it, because agents can read files on demand, “the amount of context that can be bundled into a skill is effectively unbounded.”

Sources: platform.claude.com · Agent Skills · Best practices (“The context window is a public good”) · anthropic.com (“effectively unbounded”).

1 · Anatomy of a Skill

“At its simplest, a skill is a directory that contains a SKILL.md file. This file must start with YAML frontmatter that contains some required metadata: name and description.” Everything else — extra instructions, reference docs, scripts, templates — is optional and lives alongside it in the folder.

The SKILL.md frontmatter

The frontmatter is YAML between --- fences. Two fields are required, and the docs specify exact validation rules for each — because these strings end up in the model's system prompt and are how it chooses the right skill.

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

# PDF Processing

## Instructions
[Step-by-step guidance for Claude to follow]

## Additional resources
- For form-filling, see [FORMS.md](FORMS.md)
- For the full API reference, see [reference.md](reference.md)

2 · Progressive disclosure — the idea that makes Skills work

The whole design rests on one idea: “progressive disclosure: Claude loads information in stages as needed, rather than consuming context upfront.” A skill is loaded in three levels, and most of it usually never loads at all. This is what lets you install a hundred skills without overwhelming the context window.

What actually happens, mechanically

The best-practices “runtime environment” section explains the mechanics behind the table:

• Metadata pre-loaded: “At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt.” At this point the agent only knows each skill exists and when to use it.
• Files read on-demand: “Claude uses bash Read tools to access SKILL.md and other files from the filesystem when needed.” Reading the body is a deliberate act, not an automatic load.
• Scripts executed efficiently: “Utility scripts can be executed via bash without loading their full contents into context. Only the script's output consumes tokens.”
• No context penalty for large files: “Reference files, data, or documentation don't consume context tokens until actually read.”

3 · How a Skill is triggered and run

Put the format and the disclosure model together and you get the full runtime picture. Anthropic walks through it as a four-step sequence on the context window — from a request arriving, to the skill being read off disk, to the task being done. Crucially, none of this is a special “skill engine”: the agent simply uses ordinary bash and file reads against a filesystem.

6 · The open standard

On December 18, 2025, Anthropic published Agent Skills “as an open standard for cross-platform portability.” The format — the same SKILL.md-in-a-folder you've seen throughout — is documented at agentskills.io and is no longer Claude-specific: “The Agent Skills format was originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products.”

Sources: anthropic.com (the Dec 18, 2025 open-standard update banner) · agentskills.io · Home.

The result is one creator, one spec, and many independent implementations — including tools from Anthropic's direct competitors. The agentskills.io quickstart states it plainly: “Agent Skills are an open format. The same skill works in any compatible agent, including Claude Code and OpenAI Codex” — and it demonstrates the format in VS Code (where skills live under .agents/skills/ by default). Beyond those, the standard's client showcase lists dozens more implementations — among them Google's Gemini CLI, GitHub Copilot, Cursor, Mistral AI Vibe, Block's Goose, and data platforms like Databricks and Snowflake — each entry linking to that client's own skills documentation. In short, this is not a Claude-only format.

Sources: agentskills.io · Quickstart (“The same skill works in any compatible agent, including Claude Code and OpenAI Codex”; VS Code default path .agents/skills/) · agentskills.io · Client Showcase (lists each named client, with a link to that client's own setup instructions). The list grows over time — treat the named examples as a snapshot as of the research date.

The portable spec is deliberately small. It defines a directory with a SKILL.md (optionally plus scripts/, references/, assets/), YAML frontmatter followed by Markdown, and a tight frontmatter field set: required name and description, plus optional license, compatibility, metadata, and an experimental allowed-tools. It restates the same progressive-disclosure budgets — “Metadata (~100 tokens)… Instructions (< 5000 tokens recommended)… Resources (as needed)” — and the “keep SKILL.md under 500 lines” guidance.

7 · Authoring a good Skill

Anthropic's best-practices guidance is prescriptive, and most of it follows from one premise: “Default assumption: Claude is already very smart. Only add context Claude doesn't already have.” A skill is not documentation for a beginner; it's the missing context for an expert.

Source: platform.claude.com · Agent Skills · Best practices (concise-is-key; degrees of freedom; third-person descriptions; prefer scripts; build evaluations first; test across models) · anthropic.com · developing & evaluating skills.

8 · Security & trust

Skills are powerful precisely because they carry instructions and code — which is also why they carry risk. Anthropic is direct: “a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose.” The guiding rule is to “treat [a skill] like installing software.”

The security boundary depends on the surface

How much damage a skill could do depends entirely on where it runs — and the three surfaces differ sharply on network access. This is the single most important operational distinction:

Summary

Glossary