How to pin an agent skill to an exact version

By markdownregistry. Published September 27, 2026. Updated September 27, 2026.

Pin a skill by a fingerprint of its exact contents, not just by where it lives. Install it at an exact version with a tool that checks the files and records that fingerprint in a lockfile you commit. Then check for changes on purpose, and read what changed before you update. With the mdr tool that is mdr add, mdr outdated and mdr diff.

It matters because these files change. In the registry's own crawl, of 47,724 agent markdown files watched for at least 14 days, at least 19.9% changed on GitHub within 14 days of being collected (19.4% of SKILL.md files). We also looked at five Anthropic skills (skills chosen because they change often): of 75 byte-exact copies of them found in other repositories, 47 (62.7%) were an older version. An agent that loads a skill by its path reads whatever the file says today. The figures and how we measured them are in State of agent markdown, September 2026.

Every command below was run against the live registry on September 27, 2026, and the output is shown as it printed. Install the CLI from the mdr CLI page.

How do I pin an agent skill to an exact version?

Install it at an exact version, and record a fingerprint of its contents (a content hash), not just its path. With mdr, run mdr add owner/repo/skill@version. It installs that version's files from their source commit on GitHub and checks every file against its published fingerprint before writing anything. It records the version, the SHA-256 of SKILL.md and the source commit in mdr.lock. A skill with more than 200 files is refused, and nothing is written.

$ mdr add anthropics/skills/skill-creator@git:20260225.3d59511 --dir skills/skill-creator
installed anthropics/skills/skill-creator@git:20260225.3d59511  18 files (18 hash-verified)  audit A  to skills/skill-creator

This example installs into skills/skill-creator so every path below is easy to read. Without --dir, mdr installs where your agent loads skills: .claude/skills/<name> by default, or the matching directory for --agent codex, cursor or opencode.

A version label is the version (or metadata.version) in the skill's frontmatter, with a v added when it starts with a digit, or, when it declares none, the commit date and short hash, as here. A declared version can repeat across commits, so when two versions share a label, pin by content hash instead: mdr add owner/repo/skill@sha256:<prefix>. mdr info owner/repo/skill lists the recent versions with their date, commit and audit grade.

Is there a lockfile for agent skills like package-lock.json?

Yes. mdr writes mdr.lock, a small JSON file in the folder you run it from. It records each skill's version label, SHA-256 fingerprint, source commit and install path. Commit it to your repository. mdr install then downloads exactly those contents again and checks them, so it installs them exactly or fails. GitHub's gh skill works differently: it pins to a tag or commit and records a git tree SHA inside each SKILL.md, not in a separate lockfile.

{
  "version": 1,
  "registry": "https://markdownregistry.com",
  "entries": {
    "anthropics/skills/skill-creator": {
      "artifact": "art_hl7wjhua3foziup4",
      "kind": "skill",
      "label": "git:20260225.3d59511",
      "sha256": "ba8bebb2c085444120743af8dc859dd7c2592d6290e93aa5e1c08403109bdce7",
      "commit": "3d59511518591fa82e6cfcf0438d68dd5dad3e76",
      "path": "skills/skill-creator",
      "files": 18,
      "verified": 18,
      "installed_at": "2026-09-27T20:33:01.483Z"
    }
  }
}

The sha256 is the hash of the skill's SKILL.md at that version, and verified counts the files whose bytes were checked before anything was written. If any file does not match, nothing is written at all.

How do I check whether my installed agent skills are outdated?

Run mdr outdated. It lists every pinned skill whose SKILL.md changed on GitHub, with the new version and its audit grade. It exits with status 2 when one did, or when one was removed from GitHub, so an automated build can fail on it. For a public skill, a change to another file that leaves SKILL.md untouched is not detected. mdr verify --min-grade A fails when the registry can no longer find a pinned version or its grade is below the minimum.

$ mdr outdated
anthropics/skills/skill-creator  git:20260225.3d59511 to git:20260306.b0cbd3d  audit A  (2026-03-06)  mdr diff anthropics/skills/skill-creator
$ echo $?
2

$ mdr verify --min-grade A
✓ anthropics/skills/skill-creator  git:20260225.3d59511  audit A (>= A)  sha256:ba8bebb2c085

all 1 pinned entry verified at grade A or better

How do I see what changed in an agent skill before I update it?

Run mdr diff owner/repo/skill. It shows the lines that changed in the skill's SKILL.md, from the version you pinned to the latest one, when you are behind. Add two version labels to compare any pair. It does not show the skill's other files, such as scripts. To see those, compare the two source commits: mdr.lock records yours, and mdr info owner/repo/skill lists the short commit hash of each recent version.

$ mdr diff anthropics/skills/skill-creator
anthropics/skills/skill-creator: git:20260225.3d59511 to git:20260306.b0cbd3d  +8 -2
- description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, ...
+ description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, ...

The long description lines are cut short here; the real output prints them whole, followed by the other changed lines of SKILL.md. Between these two versions, two of the skill's Python scripts also changed upstream (improve_description.py by 51 lines added and 52 removed, run_loop.py by 4 removed), and mdr diff does not show them: run git diff 3d59511 b0cbd3d -- skills/skill-creator in a clone of the skill's repository to see them.

How do I update an installed skill without losing my local edits?

mdr does not merge local edits. mdr update overwrites every file the new version ships, so an edit inside one of them is lost, and it does not delete files, so a file removed upstream stays until you remove it. The safest course is not to edit an installed skill: if you need changes, copy it to a directory you own, under a new name, and maintain that copy. If you have already edited one, move the skill directory aside before updating (remove last time's backup first), run mdr update, then compare the two with git diff --no-index and carry your changes across by hand. mdr install overwrites local edits the same way.

$ rm -rf skill-creator.mine && mv skills/skill-creator skill-creator.mine
$ mdr update anthropics/skills/skill-creator
installed anthropics/skills/skill-creator@git:20260306.b0cbd3d  18 files (18 hash-verified)  audit A  to skills/skill-creator
$ git diff --no-index --stat skill-creator.mine skills/skill-creator
 .../skill-creator}/LICENSE.txt                     |   3 +-
 .../skill-creator}/SKILL.md                        |  12 ++-
 .../skill-creator}/scripts/improve_description.py  | 103 ++++++++++-----------
 .../skill-creator}/scripts/run_loop.py             |   4 -
 4 files changed, 60 insertions(+), 62 deletions(-)

We ran this on September 27, 2026 twice in a row (from 1ed29a0 to 3d59511, then the update shown here to the latest), with an edit to LICENSE.txt carried across after the first and a new edit to SKILL.md before the second: both edits were in skill-creator.mine afterwards and the new install was clean. If mdr update fails, move the directory back. Move the directory rather than copy it: a copy nests inside last time's backup on the next update, and it hides files that upstream removed, which a move lets the comparison show. The comparison lists your edits and every upstream change, including the two scripts mdr diff does not show; drop --stat to see the lines. A file that appears only in skill-creator.mine is either one you added or one upstream removed; mdr info and the source commits tell you which. git diff --no-index exits with status 1 when the two differ, which here is expected. We also tried carrying edits across automatically with a patch made from git history; it lost the edit in several ordinary histories (a second update, a shared lockfile, a squash merge), so we do not recommend it.

mdr, gh skill, or copying the files

GitHub's CLI added gh skill in April 2026, in public preview, with its own pinning, described in GitHub's changelog. Copying a skill's files into your repository is the third option. How they differ:

Use whichever fits how your team already works. What matters is that the pin records the exact bytes and that an update is a decision you make after reading the change.

Sources

• GitHub changelog: manage agent skills with GitHub CLI

Last checked September 27, 2026.

Read next

• Are agent skills safe? What to check before you install one
• Where to find agent skills: directories, marketplaces and package managers
• Every SKILL.md skill in the registry, most starred first
• State of agent markdown, September 2026

Try it

npx modelranch add anthropics/skills/pdf

That installs one skill pinned to its exact version. Every way to install the CLI is on the mdr CLI page.