Independent AI intelligence Two editions daily · ET
Fervor AI
Menu

Analysis · October 22, 2026 · concept

Agent Skillsai-skillsclaude-codeagent-infrastructure

Agent Skills Aren't Local Files Anymore. Validate, Version and Pin Yours.

Anthropic handed the SKILL.md format to a neutral foundation. Here is how to validate, version and pin the skills already sitting in your repo.

A skill is the most boring file format in AI. It is a folder with a Markdown file inside, and the Markdown file has a name, a description and some instructions. That boring folder now runs on more than 70 agent platforms, and as of October 22 it no longer belongs to the company that invented it.

That combination is the interesting part. A format that is everywhere and owned by no one stops being a feature of one product and starts behaving like infrastructure. Infrastructure has rules. Most of the skills people have written so far were written as if there were none.

The result: a skill you wrote for one tool may fail to load in another, and nothing in the file tells either tool which version of the rules you followed.

What actually happened

On October 22, Anthropic donated Agent Skills to the Agentic AI Foundation, a group under the Linux Foundation. The handoff covers the standard itself, the name and logo, the GitHub organization and the agentskills.io domain.

If the foundation sounds familiar, it should. Anthropic, Block and OpenAI co-founded it in December 2025, when it took in MCP (the Model Context Protocol, the standard way agents connect to outside tools), Block's goose agent and OpenAI's AGENTS.md. Skills now sit next to those.

Anthropic's announcement comes with big numbers, and they are Anthropic's numbers: more than 70 integrating platforms, including ChatGPT, Cursor, GitHub Copilot and VS Code, 1 million published skills and nearly 280 million installs. Engineers from Anthropic, Google, OpenAI and other companies will maintain the standard as individuals, with David Soria Parra and Mahesh Murag as lead maintainers. You do not have to join the foundation to use the format or contribute to it.

Then there is the roadmap, which Anthropic describes as proposed: versioned releases, a formal process for proposing changes, and security guidance for people who write and install skills.

Read that list again. Versions, a change process and security guidance are the three things a standard needs before thousands of strangers depend on it. All three are still ahead.

A skill, in one paragraph

If you have not built one, here is the whole idea. A skill is a folder. Inside is a file called SKILL.md that starts with a small block of settings (YAML frontmatter, the --- fenced lines at the top) and then plain instructions. The folder can also hold scripts, reference docs and templates.

Agents load skills in three steps, which the spec calls progressive disclosure. At startup the agent reads only each skill's name and description, about 100 tokens per skill. When your request matches a description, it reads the full instructions. Only if the instructions point to a script or reference file does it open that file.

Think of it like a cookbook's index. The agent scans the index for every recipe, but only opens the page for the dish you asked for. That is why you can keep dozens of skills installed without filling the model's memory.

The six fields that travel

Here is the detail that turns "open standard" from a slogan into a constraint.

The specification defines exactly six frontmatter fields. Two are required:

  • name: up to 64 characters, lowercase letters, numbers and hyphens only, no leading, trailing or double hyphens, and it must match the folder's name.
  • description: up to 1,024 characters, saying what the skill does and when to use it.

Four are optional:

  • license: a license name or the name of a license file in the folder.
  • compatibility: up to 500 characters on what the skill needs, such as a product, system packages or network access.
  • metadata: a map of string keys to string values for anything else.
  • allowed-tools: a space-separated list of pre-approved tools, marked experimental, with support that varies by agent.

Now look at how one host treats extras. Claude Code's skills documentation says its skills follow the open standard and that Claude Code adds its own features on top, such as invocation control and subagent execution. The same page says that for claude.ai uploads, the Skills API and packaging, only the six spec fields are allowed, and any other field causes a hard error.

So the same vendor that wrote the standard ships a tool with extra fields and a second surface that rejects them. That is not hypocrisy. It is how every standard works: hosts add features, and the portable subset is whatever the spec says. But it means a skill written against one host's extensions is a local skill, whatever the folder name says.

The missing version

The spec has no field that says which version of the spec a skill follows. It has no version field for the skill itself either. The word "version" shows up in exactly one place: as an example key inside metadata, written as version: "1.0".

That was fine when one company owned the format and changed it carefully. It matters more now, for a plain reason. The roadmap promises versioned releases. The first time a versioned release tightens a rule (a stricter name pattern, a new required field, a change to how allowed-tools works), every host has to decide what to do with the million skills that predate it. A skill that says nothing about itself gets whatever guess the host makes.

npm packages went through the same phase. For years a package said what it needed in loose terms and installs drifted until lockfiles became normal. Skills are at the start of that curve, with far less tooling.

Put this into practice

Four changes, cheapest first. None of them needs anything the spec does not already allow.

1. Run the reference validator

The standard's GitHub repo ships a small Python tool called skills-ref (it needs Python 3.11 or later). Its README calls it a demonstration library, not production software, which is fine for a local check. Install it from the repo:

git clone https://github.com/agentskills/agentskills.git
cd agentskills/skills-ref
python -m venv .venv && source .venv/bin/activate
pip install -e .

Then point it at a skill folder:

skills-ref validate ~/.claude/skills/my-skill

It checks that the frontmatter is valid and follows the naming rules. Two failures to look for first: a name that does not match the folder, and a name with capital letters. Fix those first; they are what breaks a skill when you copy it into another tool.

The same tool has skills-ref read-properties, which prints a skill's frontmatter as JSON, and skills-ref to-prompt, which generates the prompt block (in XML) that an agent loads for a set of skills. The second one is a good test of your description: if you would not pick your skill from that block, neither will the agent.

2. Make the skill describe itself

Add the optional fields the spec already allows. A portable skill's header can look like this:

---
name: release-notes
description: Drafts release notes from merged pull requests and the changelog. Use when the user asks for release notes or a changelog summary.
license: MIT
compatibility: Requires git and the GitHub CLI (gh), plus network access
metadata:
  version: "1.2.0"
  spec-checked: "agentskills.io specification, October 2026"
---

The version key follows the spec's own example. The spec-checked key is my own convention, not part of the standard; the spec says hosts can use metadata for anything and suggests unique key names. Its job is simple: when versioned releases arrive, you will know which skills were checked against which rules.

3. Keep host-only features out of shared skills

If a skill uses Claude Code extras, keep it in your personal or project skills folder (~/.claude/skills/ or .claude/skills/, per Claude Code's docs) and say so in compatibility. If you plan to publish it, strip it down to the six fields first. Two versions of a skill is annoying. A published skill that throws a hard error on upload is worse.

4. Pin skills you did not write

Pinning means locking a dependency to one exact commit, so it cannot change under you. Many skills install straight from a repo's main branch. Cloudflare's security audit skill, for example, documents the install command npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit. The command names no tag or commit, and the README does not say whether the installer records which revision it fetched.

For anything that touches code or credentials, install from a commit you have read instead:

git clone https://github.com/<owner>/<repo>.git /tmp/skill-src
cd /tmp/skill-src && git checkout <commit-sha>
cp -r <skill-folder> ~/.claude/skills/

Then write that commit hash down somewhere you will see it, such as a line in your repo's README or the skill's metadata. It is a manual lockfile. It is ugly. It is also the only pinning the format gives you today.

Before you copy, open the scripts/ folder. The spec lets skills bundle executable code, and an agent will run it if the instructions say so.

What this will not fix

Be clear about the limits.

The validator checks format, not behavior. A skill can pass every rule and still tell an agent to do something careless. And the skills-ref README says plainly that the library "is intended for demonstration purposes only," not for production use. Treat it as a linter, not a gate.

The foundation move changes who maintains the rules, not who checks the skills. Nothing in the announcement describes reviewing or signing published skills. Security guidance is on the proposed roadmap, which means it does not exist yet.

The metadata conventions above are conventions. No host reads spec-checked. A future spec release might add a real version field with different rules, and then you will have to migrate. That migration will still be easier if your skills already say what they are.

And the adoption numbers are Anthropic's own. They are probably directionally right; the format clearly spread. But 280 million installs counts downloads, not skills anyone reviewed.

The shift

For two years, a skill was a prompt with a folder around it. You wrote it for the agent in front of you and edited it when it misbehaved.

As of this week it is a file format with a governing body, dozens of readers and a roadmap. Files in a format like that get validated, versioned and pinned, or they break in ways nobody notices until a host updates.

You do not have to wait for the foundation to finish its roadmap. Pick the three skills you rely on most, run the validator on them tonight, and give each one a version. That is twenty minutes of work, and it is the difference between a skill that travels and one that only works on your laptop.

Sources: Anthropic, Donating Agent Skills to the Agentic AI Foundation (October 22, 2026) · Anthropic, Agentic AI Foundation announcement (December 9, 2025) · Agent Skills specification · agentskills/agentskills and skills-ref · Claude Code skills docs · cloudflare/security-audit-skill README. Spec and repos read October 22, 2026.