Last week I wrote about stale agent skills: once a SKILL.md is copied into your skills folder, nothing tracks it. Your agent keeps following the old instructions, and nothing errors out.

Five days later, GitHub Spec Kit shipped a fix for its own corner of the problem.

What changed

Since Spec Kit 1.4.2, every skill it generates records the version that produced it:

--- name: speckit-plan metadata: author: github-spec-kit source: templates/commands/plan.md version: 1.4.2 --- 

Core skills carry the Spec Kit version. Extension and preset skills carry their own component's version. It uses the metadata map the Agent Skills spec already has, so no spec change was needed.

How it happened

  1. 12 Nov: I opened a discussion explaining that copied skills can't be checked for updates.
  2. 13 Nov: the maintainer asked for a feature request, so I filed one.
  3. 16 Nov: their triage approved it.
  4. 17 Nov: the maintainer merged the implementation, and 1.4.2 shipped the same day.

That's under a week from "here's a gap" to a release. A small, optional key that breaks nothing is easy to say yes to.

Why the version has to live in the skill

Spec Kit already recorded its version in .specify/integration.json. But upgrading Spec Kit doesn't rewrite the skills already on disk, so the project can say 1.4.2 while the skills are still from 1.4.1. Only a version written in the skill itself tells you what you're actually running.

skill-check 0.5.0 reads it. When you use a Spec Kit skill that's older than the latest release, you (and Claude or Codex) see:

[skill-check] The skill "speckit-plan" is out of date: installed 1.4.1, latest v1.4.2. Run `specify self upgrade`, then `specify integration upgrade claude` in this project. 

It skips extension and preset skills, because their versions belong to the extension, not to Spec Kit.

The other half: metadata.source

A version tells you what you have. To know whether there's something newer, a tool also needs to know where the original lives. That's the second key:

metadata: version: 1.2.0 source: https://github.com/you/your-skills/tree/main/skills/my-skill 

With a source, skill-check compares your copy with upstream by version, then by content and commit history. So it catches updates even when the author forgot to bump the version.

If you publish skills, adding these two lines is what lets your fixes reach the people who copied your skill.

If you copied a skill whose author didn't add them, you can add source to your own copy. The README explains how.

Try it

Claude Code:

/plugin marketplace add louis8408/skill-check /plugin install skill-check@skill-check 

Codex:

codex plugin marketplace add louis8408/skill-check codex plugin add skill-check@skill-check 

It's free and open source (Apache-2.0). There's no server and no telemetry, and it never blocks or edits a skill.

There's an open discussion on the Agent Skills spec about recommending these two keys. If you build an agent or an installer that copies skills, that's the place to weigh in.