Agent Skills joins the Agentic AI Foundation: what changes for the SKILL.md you install, and what to do until versioning ships

Anthropic has handed Agent Skills to the Agentic AI Foundation, the Linux Foundation project it co-founded with Block and OpenAI last December. The announcement went out on 22 October and covers the name and logo, the GitHub organization and the agentskills.io domain. The foundation already hosts MCP, Block’s goose agent and OpenAI’s AGENTS.md convention. Lead maintainers are David Soria Parra and Mahesh Murag, with engineers from Anthropic, Google, OpenAI and others maintaining the standard as individuals. The post counts more than 70 platforms that load skills.

Two weeks ago, the supply-chain post ended on the missing registry and the missing versions. The donation does little about either yet. Below is what it does change, and what an installer can do in the meantime. The checks and outputs come from my own machine: Claude Code 2.1.309, codex-cli 0.163.0, Python 3.12.3.

What changes for a SKILL.md after the Agent Skills donation?

Nothing in the file. A skill is still a folder with a SKILL.md in it, YAML front matter on top, instructions below, optional scripts/, references/ and assets/ next to it. No field was added or removed, and nothing you have installed needs to be touched.

What changed is who decides the next version. Until this week the spec was an Anthropic-run repository with outside contributors. Now it is a foundation project with a multi-company maintainer group, so a format that 70 clients load no longer changes on one vendor’s schedule. On your disk, today, that is worth nothing.

Does the Agent Skills spec have versions you can pin?

Not yet. The announcement says Anthropic has proposed starting with a roadmap of versioned releases, a formal proposal process, and security guidance for people who write and install skills. Proposed is the word.

The repository agrees. agentskills/agentskills has no tags and no releases, and its last commit, at the time of writing, is from 9 August. There is no “spec 1.0” to say your skill conforms to. A skill’s own version is not defined either: the spec has no version field, only metadata, a free map of string keys to string values, with version: "1.0" shown as an example. No client I checked does anything with it. A skill author’s own tooling can, and that is the author keeping their labels consistent, not a pin you can rely on.

Even the reference validator says so about itself, in its README:

This library is intended for demonstration purposes only. It is not meant to be used in production.

So three different things get called a version here. The spec has none. A skill may carry a label in metadata. And the content you actually run is identified by a git commit, if it came from git at all.

How far can a copied SKILL.md drift from its source?

A long way, quietly. One third-party skill in my ~/.claude/skills is a plain git clone from April, sitting at its author’s commit of 31 March. I fetched it today:

SK=~/.claude/skills/<the-skill>
git -C "$SK" fetch -q origin
git -C "$SK" log --oneline HEAD..origin/main | wc -l
# 76
git -C "$SK" diff --stat HEAD origin/main | tail -1
# 14 files changed, 828 insertions(+), 558 deletions(-)

Upstream’s last commit is from 16 October. Four things in that diff are worth knowing before you pull any skill.

The description was rewritten. In Claude Code and Codex alike, the description is what the model reads to decide when a skill applies, so an update can change when a skill fires, not only what it does once it fires.

The version label moved. My copy declares version: 2.5.1 at the root of the front matter, where the spec has no such field. Upstream now writes version: "3.1.0" under metadata, as the spec suggests. Two copies of the same skill keep the label in two different places.

The folder grew. Upstream now ships .claude-plugin/plugin.json and a marketplace.json, a .cursor-plugin/plugin.json, an agents/openai.yaml for Codex, an AGENTS.md, and a Python script that checks the package. A skill that was one Markdown file now carries packaging for three clients and code.

And one of those files changes how Claude Code treats the folder. Its docs say that a .claude-plugin/plugin.json inside a personal or project skill folder lets Claude Code load that folder as a plugin, named <name>@skills-dir, “with its own agents, hooks, and MCP servers”. So a git pull in ~/.claude/skills can turn a prose skill into a plugin that can register hooks. This upstream’s manifest lists only its skill, and the repository has no hooks or MCP config; I checked. The next update might.

Read the full list of changed files first, then the diff of everything that runs or steers:

git -C "$SK" diff --name-status HEAD origin/main
git -C "$SK" diff HEAD origin/main -- SKILL.md scripts/ agents/ .claude-plugin/ AGENTS.md

How do you pin a third-party Agent Skill in Claude Code today?

By commit. There are two ways that hold, and a third that only looks like one.

The plain way is a git clone checked out at a known commit. Clone it outside any folder an agent scans, check out the commit, read it, and only then link it in, because Claude Code watches its skill folders and picks up a new one mid-session:

git clone https://github.com/<owner>/<skill> ~/src/skills/<skill>
git -C ~/src/skills/<skill> checkout --detach <40-character-commit>
# read it, then:
ln -s ~/src/skills/<skill> ~/.claude/skills/<skill>

It is a pin only if you write the commit down and update on purpose.

The stronger way in Claude Code is a plugin marketplace of your own that points at the skill’s repository with a sha. The marketplace reference takes a full 40-character commit, and when both ref and sha are set, Claude Code checks out the sha. With a real repository and commit in place of the placeholders, this passed claude plugin validate on my machine (one warning, for the missing marketplace description):

{
  "name": "pinned-skills",
  "owner": { "name": "me" },
  "plugins": [
    {
      "name": "<skill>",
      "source": {
        "source": "github",
        "repo": "<owner>/<skill>",
        "sha": "<40-character-commit>"
      }
    }
  ]
}

Put it at .claude-plugin/marketplace.json in a folder or repository you control, then claude plugin marketplace add ./my-skills and claude plugin install <skill>@pinned-skills. I validated the file; I did not run the install. The source can also be a git-subdir (one folder of a larger repository, same ref and sha fields) or an archive, a zip with a sha256 that the reference says Claude Code checks against the download.

The third way is metadata.version. It looks like a pin and is a label: nothing checks it against the contents.

How do you check a SKILL.md against the Agent Skills spec?

With skills-ref, the reference library in the spec repository. It is also on PyPI, but I installed it from a clone at the commit I was reading, so the rules match the spec text. It needs Python 3.11 or newer:

git clone https://github.com/agentskills/agentskills
git -C agentskills checkout --detach 69ef37e9424c0a7ea9dd2293b559e43ec8176379
python3 -m venv .venv && .venv/bin/pip install ./agentskills/skills-ref
for d in ~/.claude/skills/*/; do .venv/bin/skills-ref validate "$d"; done

The loop is a listing, not a gate: read its output, not its exit code. On my folder roughly one skill in four failed, and most of the failures were in skills I wrote myself. They came in three kinds.

A description with an unquoted colon in it. A line like description: ... sibling: same CLI ... is not valid YAML: the parser reads the second colon as a new key and stops with mapping values are not allowed here. Wrap the description in quotes or use a | block.

A version at the root of the front matter. The validator allows only name, description, license, compatibility, metadata and allowed-tools, and rejects anything else.

A description over 1,024 characters, the spec’s limit.

One more entry failed without being a skill: the synced folder, where Claude Code puts the skills enabled on a claude.ai account. It holds skills; it has none of its own. The docs warn that local edits in it can be overwritten by the next sync, which makes it a second writer into the folder, after you.

Every one of my failing skills still shows up in Claude Code, and nothing in the session flags them. Claude Code ignores a front matter field it does not recognize “without reporting an error”. For YAML that does not parse, the docs say the skill loads “with empty metadata, so /skill-name still works but Claude can’t match against your description”. A skill you invoke by hand keeps working, and the automatic trigger dies without a word. The strict paths are elsewhere: a claude.ai upload, the Skills API or Anthropic’s package_skill.py fail with a hard error on any field outside the six. So “works in Claude Code” is the weakest test a skill can pass. Run the validator before you hand one to anyone, yourself in another tool included.

Where do Claude Code and Codex look for Agent Skills?

In different folders. Claude Code reads personal skills from ~/.claude/skills, project skills from .claude/skills in the start directory and every parent up to the repository root, plus plugins, managed settings and --add-dir directories. Its skills page does not mention .agents. Codex reads ~/.agents/skills for the user and .agents/skills from the working directory up to the repository root, plus /etc/codex/skills and its bundled skills. The spec’s own client guide calls .agents/skills “a widely-adopted convention for cross-client skill sharing” and suggests scanning it next to a client’s own folder. Claude Code, by its docs, doesn’t.

Both loaders document symlinks, so keep the skill in one place and link it into the other:

mkdir -p ~/.agents/skills
ln -s ~/src/skills/<skill> ~/.agents/skills/<skill>

A symlink fixes discovery and nothing else. Fields that only one client understands mean nothing to the other: Codex reads its UI and invocation settings from agents/openai.yaml, Claude Code reads its extras from the front matter. The skill above ended up shipping a manifest per client to cover the gap. So much for one format.

What should Agent Skills security guidance cover first?

The trust boundary, because the clients already disagree on it.

The spec’s client guide has one paragraph on it: project-level skills may come from an untrusted repository, so a client should load them only once the user has marked the folder as trusted, or a fresh clone can “silently inject instructions” into the agent. The Claude Code docs, on allowed-tools, say this:

Workspace trust doesn't gate this field. Claude Code applies a project skill's
allowed-tools even in a -p run in a folder you've never trusted.

The grant lasts only for the turn that invokes the skill, and it is not a ceiling: tools not on the list stay callable under your normal permissions. The docs tell you to review the allowed-tools of skills checked into a repository before running Claude Code there, and point at a managed setting that withholds the field from repository skills. It is the same shape as what a cloned repo’s settings file can run: the file arrives with the clone, and a headless run asks no one. Meanwhile the spec marks allowed-tools as experimental, with support that “may vary”, and the Codex skills page does not mention it.

My read: a shared format whose only permission field means something different in each client is the first thing a security guide has to settle. Signing and hash pinning matter, but they answer “is this the file I meant to install”. The open question is what the file may do once installed, and today the answer depends on which agent opened the folder.

Until that guide exists, the first five minutes with a skill you did not write look like this:

S=path/to/skill
sed -n '1,/^---$/{p}' "$S/SKILL.md" | sed -n '2,$p'   # the whole front matter, allowed-tools included
find -H "$S" ! -name '*.md' ! -path '*/.git/*' \( -type f -o -type l \)   # files and links that are not prose
find -H "$S" \( -name '__pycache__' -o -name '*.pyc' \)   # caches next to code
ls "$S/.claude-plugin" 2>/dev/null                       # does it load as a plugin?
git -C "$S" log -1 --format='%H %ad' && git -C "$S" status --short   # the commit, and anything not in it

If you run only one line, run the last. If status prints anything, what runs is not the commit you think you are trusting.

How do you follow changes to the Agent Skills spec?

Watch the repository, not the blog. Spec changes land as pull requests in agentskills/agentskills, and the announcement says feedback on proposed changes goes through the project’s Discord. The first tagged release is the moment the roadmap stops being a proposal.

The foundation has done this twice already. MCP arrived as a protocol with dated spec versions, and AGENTS.md as a file convention with no versions at all. Skills sit between the two: more than a convention, because a skill can bundle code, and less than a protocol, because nothing yet says which version of the format a client implements.