# 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](https://markdownregistry.com/reports/state-of-agent-markdown-2026-09). | Kind | Watched 14+ days | Changed within 14 days | Share | | --- | --- | --- | --- | | SKILL.md | 42,581 | 8,272 | 19.4% | | AGENTS.md | 2,623 | 730 | 27.8% | | CLAUDE.md | 1,333 | 309 | 23.2% | | DESIGN.md | 634 | 34 | 5.4% | | Cursor rules | 296 | 36 | 12.2% | | llms.txt | 257 | 106 | 41.2% | How often agent markdown changed upstream within 14 days of being indexed, by kind (lower bounds; only files watched for at least 14 days count). Registry crawl, data frozen September 27, 2026; method and downloads in [the report](https://markdownregistry.com/reports/state-of-agent-markdown-2026-09). 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](https://markdownregistry.com/cli). ## 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/` 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:`. `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](https://github.blog/changelog/2026-04-16-manage-agent-skills-with-github-cli/). Copying a skill's files into your repository is the third option. How they differ: | | mdr | gh skill | Copying the files | | --- | --- | --- | --- | | Pin to an exact version | Yes: a version label, checked against a SHA-256 | Yes: --pin to a tag or a commit | Only by never touching the copy | | Where the pin is recorded | mdr.lock, one file for the project | Tracking fields in each SKILL.md | Nowhere | | Integrity | Every file checked against its published hash before anything is written | Records the source's git tree SHA and compares it on update | None | | See that upstream moved | mdr outdated, when SKILL.md changes (exit 2 for CI) | gh skill update (--dry-run to only check), from the whole directory's tree SHA; pinned skills are skipped | No signal | | Read the change first | mdr diff of SKILL.md between any two versions | gh skill preview before installing | Compare by hand | | Audit grade on each version | Yes, deterministic checks | Not described | No | | Agents it installs for | Claude, Codex, Cursor, opencode | Many, including Copilot, Claude Code, Cursor, Codex and Gemini CLI | Any | 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](https://github.blog/changelog/2026-04-16-manage-agent-skills-with-github-cli/) Last checked September 27, 2026. The page: https://markdownregistry.com/guides/pin-agent-skills