I have a folder on my machine called skills, and until yesterday I thought of it as a Claude thing. Then Anthropic announced it is donating the Agent Skills standard to the Agentic AI Foundation, and I had to admit I’d never actually read the spec. I’d just copied the shape of the first skill I saw and kept going.
So I read it. It’s short. That turns out to be the whole story, and it’s also the reason I’m a little suspicious of the excitement around this news.
Here’s what was announced, what a skill is at the file level, and what I’d do differently now that the standard has a neutral owner. If you want to know who’s writing this, I build automation for clients, and you can see the kind of work on my portfolio.
What Anthropic actually announced
Per Anthropic’s post from October 22, the company is donating the Agent Skills standard to the Agentic AI Foundation (AAIF), which sits under the Linux Foundation. Anthropic says it co-founded the AAIF with Block and OpenAI last year, and that it donated the Model Context Protocol to the same place.
The donation covers more than the text of the spec. Anthropic lists the Agent Skills name and logo, the GitHub organization, and the agentskills.io domain. It also says you can keep using the standard or contribute without joining the AAIF, which matters if you’re a solo developer who doesn’t want a membership form.
On the numbers, the post says more than 70 agent platforms have integrated skills since the standard was published in December 2025, and names ChatGPT, Cursor, GitHub Copilot and VS Code. It says 1 million skills have been published and nearly 280 million installed. Those are Anthropic’s figures, and I can’t verify them. A million skills sounds like a lot until you remember that a skill can be a folder with one short markdown file, so the count says more about how cheap they are to make than how good they are.
Maintenance goes to engineers from Anthropic, Google, OpenAI and other companies, acting as individuals, with David Soria Parra and Mahesh Murag as lead maintainers. Simon Willison’s short note on the news points out he guessed this destination last December.
What a skill is, file by file
The specification says a skill is a directory with, at minimum, a SKILL.md file. Optional folders are scripts/, references/ and assets/. That’s it. No manifest language, no build step, no registry you must publish to.
The SKILL.md starts with YAML frontmatter. Two fields are required. The name must be 1 to 64 characters, lowercase letters, numbers and hyphens, no leading or trailing hyphen, no double hyphens, and it has to match the parent directory name. The description must be 1 to 1024 characters and should say both what the skill does and when to use it. Optional fields are license, compatibility, metadata and an experimental allowed-tools.
Here is the smallest valid one, close to the spec’s own example:
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
---
# PDF processing
Steps go here, in plain markdown.
I want to underline the description field, because it’s the part I’d have gotten wrong if I’d kept guessing. The agent doesn’t read your whole skill up front. The spec describes progressive disclosure, so the agent sees the name and description first and loads the body when the task seems to match. A vague description like “Helps with PDFs” is, in the spec’s own words, a poor example. If the description is lazy, the skill never fires, and you’ll blame the model.
A description that fires, and one that doesn’t
This is the part that pays back fastest, so here’s a concrete pair. Say you wrote a skill that turns a client’s raw invoice export into a clean CSV.
The lazy version of the description is “Helps with invoices.” Ask yourself when an agent would load that. A user says “tidy up this spreadsheet”, and nothing in the description mentions spreadsheets, exports or CSV. The skill sits there unused.
The better version names the input, the output and the trigger: “Converts a raw invoice export (CSV or XLSX) into a cleaned CSV with one row per line item. Use when the user mentions invoices, billing exports, line items or accounting spreadsheets.” It’s longer, and it gives the agent words to match against.
The spec’s limit of 1024 characters is generous. I’d use maybe a third of it. Past two or three sentences you start describing the skill’s steps, and those belong in the body, which only loads once the skill has been picked.
Names get less attention but deserve a minute. They must match the directory, so renaming a folder to tidy up your repo can silently break a skill. I’d keep names boring and literal, like invoice-cleanup, and resist the urge to be clever.
Reading the spec as a client-work person
Most of my day involves small teams who want one thing automated and don’t care about standards bodies. For them, the useful fact is that a skill is a plain folder. It can live in git, get code reviewed, and be copied between machines without a package manager. That’s a better story than most plugin systems I’ve dealt with.
It also means the same skill can, in principle, travel between tools. Anthropic’s post lists several platforms that have integrated skills. I haven’t tested portability across them, and I’d expect small differences in how each loader treats optional fields, so I’d test one skill in two tools before promising a client anything.
Why a neutral owner changes my planning
Until now, writing a skill felt like writing for one vendor’s product that happened to be documented well. If the vendor changed direction, my folder of skills was a bet on their roadmap.
Moving the standard to a foundation doesn’t make that risk vanish, but it changes the odds. The name, the repository and the domain no longer belong to the company with the most to gain from steering them. Anthropic has proposed a starting roadmap of versioned releases, a formal proposal process, and security guidance for people who write and install skills.
Versioned releases are the one I care about most. When I read the spec page, I didn’t see a version number I could pin a skill against. If you have ever debugged a behaviour that changed because a loader quietly started parsing frontmatter differently, you know why a numbered spec is worth more than another feature.
I’m also holding the promise loosely. Foundation governance tends to be slower than one company shipping on its own schedule, and the post itself talks about process first: a proposal process, versioned releases, a Discord for feedback. I’d plan on stability, not on a burst of features.
The part nobody should skip: scripts are code you run
The spec allows a scripts/ directory with executable code. That’s a feature, and it’s also the sentence I’d highlight for any team installing skills from strangers. A skill isn’t a prompt. A skill can ship a program, and your agent may be allowed to run it.
The proposed roadmap mentions security guidance for people who write and install skills, which tells me the maintainers know this. The allowed-tools field is marked experimental in the spec, so don’t treat it as a security boundary yet.
My rule for now is boring. I read every file in a skill before I install it, scripts first, the same way I’d read an install script piped from curl. For anything that touches client data, I run the agent inside a container with no access to the host Docker socket, for reasons I wrote up in why I stopped mounting docker.sock into agent sandboxes. The same logic applies here: a skill from a stranger deserves the same suspicion as a package from a stranger.
The marketplace point is worth saying plainly. When 280 million installs are claimed and anyone can publish, some of that traffic will be people copying a skill they never opened. I would be surprised if nobody has already tried to hide something nasty in a scripts/ folder.
What I would do this week
Four small things, none of them heroic, and the first one is the cheapest.
Open the spec and read it. It takes ten minutes, and you’ll find out whether your existing skills even validate. Check that each name matches its folder name and has no uppercase letters or double hyphens. Then rewrite your three worst descriptions so each says what the skill does and when to use it, in those words. Finally, audit anything in a scripts/ folder you didn’t write yourself.
If you maintain skills for a team, add a one-line compatibility note to any skill that needs git, Docker or network access. The spec says most skills don’t need that field, and it’s there for exactly the ones that do. That small note saves a colleague from a confusing failure on a machine that lacks a dependency.
I’ll revisit this when the first versioned release lands. If the spec gets a number I can pin, I’ll move my own folder over and write down what broke.
