Anthropic Agent Skills: Format, Loading & Portability

What a Skill is on disk

A Skill is a directory, and the one file it requires is SKILL.md, a markdown document that opens with a short YAML frontmatter block and continues as plain-language instructions. The frontmatter needs exactly two fields: name (lowercase letters, numbers and hyphens only, 64 characters or fewer, and barred from containing the words "anthropic" or "claude") and description (up to 1024 characters, required to state both what the skill does and when Claude should use it). Anthropic's own skill-creator tool can generate this file automatically, but the underlying format is ordinary markdown plus YAML, not a proprietary schema. [1][4]

Beyond SKILL.md, a Skill's folder can hold whatever else the task needs: additional markdown files with deeper instructions, reference material such as API documentation or a database schema, and executable scripts. Anthropic's own pre-built skills for document work follow this pattern, for example bundling a script such as fill_form.py alongside markdown instructions that tell Claude when to run it rather than write equivalent code from scratch. [1][4]

Progressive disclosure: why many installed skills don't bloat every prompt

Anthropic documents three levels of loading, each with a different token cost. Level one is metadata: at the start of a session, the name and description from every installed skill's frontmatter get folded into the system prompt, at roughly 100 tokens per skill, regardless of whether that skill turns out to be relevant. Level two is the SKILL.md body itself, typically under 5,000 tokens, which Claude reads from the filesystem with a bash command only after matching the current request against a skill's description. Level three is everything else in the folder: additional markdown files, reference documents, scripts. None of it enters the context window until SKILL.md tells Claude to look at a specific file, and running a bundled script costs only the tokens of its printed output, since the script's own source is never read into context. [4][1]

Atlas interpretation: This is a different bet from writing one long system prompt that covers every capability a deployment might need, or pasting a large reference document into the conversation up front. Both of those approaches charge the full token cost on every turn, whether or not the current request touches that capability. Skills instead charge the small, fixed level-one cost per installed skill up front and defer everything else to the moment a task actually matches a skill's description. Simon Willison, writing the day Skills launched, framed the contrast against the Model Context Protocol: he pointed to GitHub's official MCP server as an example that, by his account, can consume tens of thousands of tokens describing its available tools before any of them is used, against a few dozen tokens per unused Skill. [3][1]

Bundled code, not just a described interface

Atlas interpretation: A tool or function definition, in the usual sense, describes an interface: a name, a set of parameters, and a description of what calling it does, so a model can decide when to invoke it and how to construct the call. It does not hand the model an implementation. A Skill can go further, because its bundled scripts are runnable code that Claude executes directly over bash rather than code Claude has to generate. Only the script's output, not its source, lands in the context window. That means an operation such as filling in a PDF form field or checking a file against a size limit runs the same deterministic way every time, instead of being regenerated by the model from scratch on each request. [4][2]

Anthropic frames this capability as something to treat with the caution due to installing software: a Skill's instructions and code run with whatever access Claude already has in that session, so a Skill from an untrusted source can direct tool use or code execution that does not match what it claims to do. Anthropic's stated guidance is to use Skills only from sources created in-house or obtained directly from Anthropic, and to audit bundled scripts, images and other resources before using anything else. [4]

One file format, three surfaces that don't behave identically

The October 16, 2025 announcement described Skills as one format that works across Claude.ai, the Claude API (paired with the code execution tool) and Claude Code, plus the Claude Agent SDK. On the narrow question of the file format, that holds: the same SKILL.md contract, with the same two required frontmatter fields, is what all of those surfaces read. [1]

Anthropic's own later documentation is explicit that format compatibility does not mean automatic availability everywhere. Custom Skills do not sync across surfaces: one uploaded to Claude.ai has to be uploaded again, separately, to use through the API, and the two are managed independently. Claude Code skips uploading entirely, since its Skills are plain directories on the filesystem, at ~/.claude/skills for a person or .claude/skills inside a project, discovered automatically. Runtime access also differs by surface: a Skill running in Claude Code has the same network access as any other program on the user's machine, a Skill running through the API executes inside a sandboxed container with no network access and no ability to install packages at runtime, and a Skill on Claude.ai gets network access that varies by account and admin configuration. Anthropic's four pre-built document skills, for PowerPoint, Excel, Word and PDF, are also not available inside Claude Code at all; they ship only on Claude.ai and through the API. [4]

Atlas interpretation: Read narrowly, "works across the apps, the API and Claude Code" is accurate: the spec is portable, and nothing about SKILL.md itself is surface-specific. Read as a claim that a skill installed once shows up, and behaves identically, everywhere, it overstates both the October 2025 launch and the documentation since. Sharing model, network access, and even which pre-built skills are available differ by surface, and a skill author has to account for that rather than assume portability of the file implies portability of behavior. [1][4]

Reception, and the move toward an open standard

Simon Willison, an independent developer who writes frequently on LLM tooling, published his assessment the same day Skills launched, calling them "maybe a bigger deal than MCP" and describing the format as conceptually simple: a markdown file with instructions, optionally accompanied by supporting documents and executable scripts. He also flagged the dependency this creates: Skills that run code presume an environment with real filesystem access and command execution, which is exactly the kind of sandbox that has to be secured carefully. [3]

Two months after launch, on December 18, 2025, Anthropic said it would make the Agent Skills specification an open standard so other tools could adopt it, added centralized Skill management for Team and Enterprise plan administrators, and published a directory of partner-contributed skills from companies including Atlassian, Canva, Notion, Figma, Cloudflare, Stripe and Zapier. [5]

Atlas interpretation: The pitch shifted within two months from a feature specific to Claude to a specification Anthropic wants other agent tools to adopt, echoing how the company handled the Model Context Protocol before handing its governance to the Linux Foundation roughly a year earlier. Whether Agent Skills becomes a shared standard the way MCP has is not something either announcement settles by itself; one analyst quoted in coverage of the December update was openly skeptical that a single vendor could set a standard unilaterally. [5]