Skills: Fifteen Folders That Onboard the Model

Fifteen Folders, Three Drawers Deep

In the directory tree available to this very conversation, there are fifteen folders, each containing a file named SKILL dot M D, each describing a small body of curated knowledge that a model can choose to load when it judges the description relevant. Eight of those folders sit under slash mnt slash skills slash public; they were shipped by Anthropic. Six sit under slash mnt slash skills slash user; Pär wrote them. One sits under slash mnt slash skills slash examples; it is a meta skill for creating other skills.

The names give away the topology. Among Pär's six: parpod for writing podcast scripts, which is the skill being read right now to produce this very file; arebladet for drafting newspaper articles in Swedish for the local paper; director-lab for running Director introspection sessions; qwen-image-edit-portrait for portrait edit prompting; scaleway-vps-deployment for shipping FastAPI apps to a particular VPS; road-trip for the long-charging-stop mode where the conversation shape changes to render-first, explain-after. Among Anthropic's eight: docx, xlsx, pptx, pdf for the four common document formats; file-reading and pdf-reading for input-side discipline; frontend-design for U I work; product-self-knowledge for asking the right kind of question about Anthropic's own products before answering them from memory.

Nobody pasted any of these into the system prompt of this conversation. They are simply available. The model knows about them by name and description, and that is all. If the description matches what the conversation is doing, the model reads the rest of the SKILL dot M D file and starts following its instructions. This is the skills mechanic. It looks small from the outside. It changes a lot in practice.

Three Levels of Disclosure

The structure is a folder. The folder contains, at minimum, a file called SKILL dot M D, with YAML frontmatter at the top. The frontmatter requires two fields: name and description. The name is short and lowercase. The description is a sentence or two, written by the skill author, declaring what the skill does and when Claude should use it.

The Anthropic documentation calls this a three-level progressive disclosure. The first level is the frontmatter; it lives in the system prompt of every session that has skills enabled, and that is all that lives there. The second level is the body of SKILL dot M D; it is loaded into context only when Claude judges the description relevant to the current task. The third level is anything bundled with the skill: a scripts folder for executable code, a references folder for additional documentation, an assets folder for templates or icons. Third-level content is loaded only when the SKILL dot M D body actively points at it.

The cost model follows the levels. Frontmatter is cheap and always present. The body is loaded once per relevant task, and lives in the context window from then on. Third-level files cost only when the model goes looking for them. A well-shaped skill keeps the body lean and pushes the rare or specialized detail into linked files. The progressive disclosure is, in practice, a budget discipline imposed on the skill author by the architecture.

The description field deserves its own attention. Anthropic's own skill-creator skill has an explicit warning baked into its instructions: Claude tends to undertrigger. That is, when given a skill description that is calmly written, Claude often decides the skill is not relevant when in fact it is. The fix is to make descriptions a little pushy. The example from Anthropic's own docs: instead of writing "how to build a simple fast dashboard", write "how to build a simple fast dashboard. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they do not explicitly ask for a dashboard." The push is calculated, and the audit is a twenty-query evaluation set, mixing queries that should trigger with queries that should not. The skill-creator skill ships an evaluation loop that runs this check on your description before you commit it.

The disclosure model becomes concrete the moment a real task hits it. Suppose Pär asks an Anthropic-hosted Claude session to draft a board memo for the bath house association as a Word document. Without the docx skill, the model writes prose that looks like a memo but produces a document that opens with subtle formatting damage: wrong heading styles, broken numbered lists, font fallback. With the docx skill loaded, the model first reads the SKILL dot M D body, which says: do not invent the styling, use python-docx with the supplied template, here is the exact pattern for heading styles, here is the rule for inserting tables. The output is dramatically more aligned with what a real Word document is supposed to look like. The difference between the two outcomes is one skill load, costing a few hundred tokens at the moment of relevance. Pär paid for that few hundred tokens, and saved an hour of opening the file in LibreOffice and re-formatting it by hand. That is the cost-benefit shape of a well-tuned skill, made concrete.

Where Skills Run

Skills run in four places, and the loading model differs slightly in each.

In Claude Code, skills are filesystem-based. The C L I scans tilde slash dot claude slash skills for user-wide skills, and dot claude slash skills inside the current project for project-specific skills, plus any plugins that ship skills, plus the built-in bundle. The model that the C L I runs reads the frontmatter on startup. There is no upload step. Just files in a folder.

In Claude dot A I, skills are uploaded as zip files through the settings page, under the features section. The Pro, Max, Team, and Enterprise tiers support custom skills, provided code execution is enabled for the session. Skills uploaded to Claude dot A I are individual to each user; they are not shared across an organization, and administrators cannot centrally manage them. That gap is what the next episode will cover under Skills for Enterprise.

In the Claude API, skills are uploaded as a zipped folder through the Skills API. The same skill that runs in Claude Code can be packaged and uploaded; the API call that creates a message references the uploaded skill by identifier. The model reads frontmatter, decides whether to load the body, then proceeds. The mechanic is the same. The substrate is the cloud rather than the local filesystem.

On Claude Platform on Amazon Bedrock and on Microsoft Foundry, skills upload through the same Skills API. Pre-built skills, which means the docx, xlsx, pptx, and pdf skills that Anthropic publishes, are available out of the box across Claude dot A I, the Anthropic API, Bedrock, and Foundry. Custom skills must be uploaded separately on each surface; the documentation is explicit about this. A skill uploaded to Claude dot A I does not automatically appear in the API. A skill uploaded to the API does not automatically appear on Claude dot A I. The skill itself is portable because the format is portable. The deployment is not.

One important data discipline note: Agent Skills are not covered by zero data retention. Skill definitions and execution data are retained according to Anthropic's standard data retention policy. For teams that need zero data retention end to end across every feature, this is the gap that has to be planned around. The skill format works the same; the privacy envelope around it does not.

There is also a standard hiding in the format. The Agent Skills specification is open, published at agentskills dot I O, and Anthropic frames Claude Code's skill behaviour as one implementation of that standard rather than as a proprietary feature. Anthropic also maintains a public repository at github dot com slash anthropics slash skills, with seventeen or more open-source skills covering creative design, document creation, technical workflows, and enterprise communication. The four pre-built document skills, docx and xlsx and pptx and pdf, are the ones that ship across every surface. The other thirteen are available for installation from the public repository, which means the cost of adopting any of them is zero and the cost of forking any of them is also zero. The open standard plus the open repository together turn the skill format into something closer to a small package library than a vendor feature.

Author-Curated, Model-Loaded

So you wrote a folder. Big deal.

That is the fair pushback, and it deserves a direct answer. A SKILL dot M D file is, structurally, a markdown document. Anyone who has written a R E A D M E has written something almost the same shape. What makes a skill more than a R E A D M E is two specific things. The description at the top is structured for matching against a description-matching mechanism the model runs at session startup. The body is structured to be read by a model that will then act on it, rather than by a human who will then forget half of it. The first point is operational. The second is editorial. Together they make a skill a different kind of artefact than a R E A D M E, even though they look very similar from a hex dump.

The deeper point is about authorship. The previous episode sat at one corner of this picture: the model writes, the model reads, the substrate is a directory the model curates. The episode before that sat at another corner: the model emits an argument, the application executes the call, the substrate is a function the developer wrote. Skills sit at a third corner. A human writes the skill, once. The model reads the skill, every time the description matches. The substrate is a folder, and that folder might be on a developer's laptop, in a zip on Anthropic's Files API, on Bedrock, on Foundry, or shared across a team through Skills for Enterprise.

The three primitives have three different authorship models, and that is the structural distinction worth holding onto. Tools are application-authored, model-invoked, application-executed. Memory is model-authored, model-invoked, application-stored. Skills are human-authored, model-invoked, application-loaded. None is a substitute for the others. They sit at different corners of the same coordinate system, asking the same three questions: who writes, who reads, who acts. The answer is different in each corner, and the answers add up to the surface the developer ends up working against.

The win for skills, structurally, is that the investment cost is paid by the author once and the benefit accrues every load. A well-shaped skill written by one person can be loaded by ten thousand sessions across four surfaces. The cost of writing it is fixed. The cost of loading it is metered: frontmatter tokens in the system prompt plus body tokens at the moment of relevance. The ratio improves with use. This is the build-versus-load distinction, drawn at the level of where the work actually happens.

Skills compose with the other primitives in honest ways. A skill can declare tools that defer-load when the skill itself loads. A skill that is referenced repeatedly can be cached as a stable prefix. A skill can read files into a memory directory and write progress back into that directory. None of these compositions is forced. They are options the skill author has, and the discipline is to pick the ones the skill actually needs, not the ones that sound impressive in a slide.

The Folder Pär Is Writing Inside Right Now

[happy] The skill is writing the episode about the skill. That is fine.

The parpod skill, the one Pär wrote and saved under slash mnt slash skills slash user slash parpod slash SKILL dot M D, is the reason this episode is structured the way it is. That file specifies: title format, chapter rules, voice block syntax, sound effect placement guidelines, forbidden words and phrases, length guidelines, two delivery paths. It is loaded into this conversation right now because the description matches: the user asked for the next PärPod episode. The model read the frontmatter at the start, judged it relevant, read the body. Everything in this script up to this paragraph is being shaped by what is in that file.

The PärPod Builder running on builder dot parpod dot net could ship that same skill, packaged through the Skills API, available to anyone using Builder through the API surface. Right now, the skill lives on Pär's Mac and in the Anthropic-hosted environment Pär uses for episode production; the Builder back end could expose it as a skill any consumer of the Builder API loads automatically. That is the unlock the Skills API actually enables for a project like this. The substrate Pär already built can ride along into surfaces Pär does not directly control, without those surfaces needing to know in advance that the skill exists.

This is also where the weird reference earns its place. Pär has a parallel project called Kasslerfrämjandet, with a single-page web manifesto at kassler dot html, written in the same Pärception brand kit as everything else: Space Grotesk font, magenta accent colour, dry self-deprecating tone, anti-buzzword commitments. That H T M L file and the parpod SKILL dot M D sit in the same brand portfolio, on the same disk, written by the same person, in roughly the same week. They are both curated artefacts that someone built once and made available for reuse. A skill is not metaphysically different from a small website or a brand kit or a kontoplan. It is a curated thing on a substrate, with a description on the outside and the actual content on the inside, available to whoever has the access to read it. The shape happens to fit a model's loading pattern. That is what makes it a skill instead of just another file in a portfolio.

What changes across surfaces is the loading mechanic. What stays the same is the shape: a folder, a SKILL dot M D, frontmatter that says when, body that says how, optional files that say more. Skills are how knowledge crosses sessions. Memory tools are how state crosses sessions. Tools are how actions cross sessions. Three different bridges, all riding on the same filesystem-shaped substrate, all available to a single model that knows which bridge it is currently on.