How to Version and Pin Agent Skills Across a Team

Quick answer
Commit team skills to the repository so every checkout runs the same version and every change is reviewable.
Give each skill a version in its frontmatter metadata and record changes in the repository, because the format has no built-in version field.
Pin registry installs to an exact revision; a moving reference means nobody reviewed what is running today.
Review skill changes like code: new commands, new file access, and widened descriptions are all functional changes.
Keep one owner per skill and a short changelog, or the folder becomes an untested second codebase.

Where should a shared skill live?

In the repository it governs. A skill that encodes how releases work for this project belongs beside the code, under the same review process. That gives every checkout the same behaviour and makes the skill part of the diff when the process changes.

Skills used across many repositories need a separate repository, with a pinned version in each project. Copying the folder into each project is simple and goes stale immediately; a shared repository keeps one source and forces an explicit upgrade.

How do you version a skill that has no version field?

Use the optional metadata block in the frontmatter, or a CHANGELOG beside the skill, and treat the pair as the version. The specification does not define a versioning scheme, so the team convention is what makes upgrades meaningful.

Increment for changes that alter behaviour: a new command, a new file read, a widened trigger description, or a changed verification step. Cosmetic edits to wording can share a version, but they still need review if they change what the agent does.

---
name: add-migration
description: Create and verify a Postgres migration. Use when a change alters a table, column, or index.
metadata:
  version: 2.1.0
  owner: platform-team
---

## Changelog
- 2.1.0  verify the down migration before reporting success
- 2.0.0  use the project migration tool instead of raw SQL
- 1.0.0  initial version

How do you roll out an update without breaking everyone?

Stage it. Run the new version in one repository or one branch, compare the output against the old version on the same task, and only then update the shared reference. A skill change is a behaviour change for every agent that loads it.

Keep the old version reachable until the migration is done. If a skill starts causing bad diffs, reverting to the previous pinned version should be one commit, not a hunt through a registry.

What does review look like?

The same review as code, with attention to capability. New shell commands, broader file reads, new network calls, and wider trigger descriptions are the changes that matter. A reworded step that does the same thing is not.

Ask the author to demonstrate the skill on a real task and include the resulting diff in the pull request. It is the cheapest evidence that the instructions work and that the agent follows them.

Where this bites vibecoders
Generated skill libraries tend to be one folder copied into five repositories with small edits that nobody tracks. When one copy gains a fix, the others silently diverge. Pick one source of truth before the third copy exists.

Where AI coding assistants get this wrong

Copying skill folders between repositories with no version or owner.
Installing from a registry reference that can change without a diff.
Updating a shared skill without testing it on a real task.
Changing a trigger description without treating it as a behaviour change.
Leaving no rollback path to the previous version.
Letting a skill folder exist outside version control.

Checklist

Choose one source of truth per skill.
Record a version and an owner in the frontmatter.
Keep a short changelog for behaviour changes.
Pin the version each project uses.
Test the update on a real task before rollout.
Keep the previous version revertible in one commit.

FAQ

Does the Agent Skills specification define versioning?

It defines the format, not a release scheme. The optional metadata field is where teams put a version, and the specification’s proposal process is expected to add guidance over time. Until then, the convention is yours to define and document.

Should personal skills be pinned too?

Yes, for the same reason. A personal skill that changes under you is a behaviour change you did not review. Keeping your own skills in a git repository costs little and gives you a diff when something starts behaving oddly.

How do I know which skills a project uses?

List them in the repository, next to the AGENTS.md or in a short skills section. An agent may also load user-level skills you cannot see, which is why any behaviour that matters should be encoded in project-level skills.

What is the smallest useful process?

Skills in the repository, one owner, a changelog line per behaviour change, and review like code. That is enough to avoid silent divergence and to answer “what changed?” when output quality drops.