The short answer

If you build reusable AI agent skills — the packaged instructions and resources that teach Claude, ChatGPT, or other assistants your workflows — treat them like a small software project. Use semantic versioning (a three-part number like 1.4.2 where each part signals a different kind of change), write a tiny changelog inside each skill, and migrate deliberately when a platform changes its format. That way your personal library survives every platform update without silent breakage.

This piece walks through when to bump a version, what a useful changelog looks like for skills, and how to keep your library healthy as Anthropic, OpenAI, and others evolve their skill formats.

Why skills need versioning at all

Skills are folders of instructions plus optional scripts and reference files. When you create one, you usually embed conventions that matter to your work: the structure of a release note, the tone of an outbound email, the order of steps in a deployment checklist, the exact fields a client intake form needs.

Those conventions will change. You will refine them. The platforms themselves will also change — Anthropic moved Agent Skills and the Skills API out of beta on the Claude API in August 2026, which is the kind of shift that can quietly affect how skills load, what fields they accept, and which endpoints they use. Without versioning, you cannot tell at a glance which copy of a skill is the live one, which one a colleague cloned last quarter, or which one will break on next month’s platform release.

A version number plus a short changelog turns each skill from a static file into something you can audit, roll back, and migrate.

When to bump: patch, minor, or major

The cleanest mental model for skills is the same one used by most software libraries: semantic versioning.

  • Patch (1.0.1) — typos, clarified wording, a missing example, a small fix that does not change what the skill does or how it is structured.
  • Minor (1.1.0) — added a new section, a new code example, a new reference file, or documented a newly released framework feature the skill now covers. Anything that adds capability without breaking what already worked.
  • Major (2.0.0) — restructured the frontmatter (the YAML block at the top of SKILL.md that tells the platform what the skill is and when to load it), changed required field names, removed a section that other workflows depended on, renamed key concepts, or moved the skill’s location. Anything a consumer would have to edit to keep working.

A practical rule of thumb from the community-style versioning policies that have started to appear around Claude skills: changes to the framework or platform you are documenting go in the skill’s name and description, not in a major version bump. Major versions are for changes to the skill itself, not to the world it describes.

If you find yourself about to rewrite the frontmatter description, or to rename the skill so it matches a new framework version, that is usually a sign to either update carefully as a minor release or, if the old behavior is no longer reachable, plan a major.

Writing a changelog readers actually follow

A good skill changelog is small, dated, and ruthlessly concrete. Two formats work well.

The first is a CHANGELOG.md file inside the skill folder, kept newest-first. Each entry gets the version, a date, and three to five bullets written in plain language. Readers should be able to skim the last three entries and know whether their workflow is affected.

The second is a short section near the bottom of SKILL.md itself, under a heading like “Revision history.” This keeps the changelog inside the file the assistant actually reads, which is convenient for one-person libraries but noisy once you have more than a handful of skills.

Whichever you pick, keep entries short and concrete:

## 1.2.0 — 2026-09-04
- Added "rollback steps" section to the deploy procedure.
- New example for the staging environment.
- Clarified when to skip the cache-bust step.

## 1.1.0 — 2026-07-22
- Documented the new v2 auth header in the API calls section.
- Added a troubleshooting entry for the "missing scope" error.

## 1.0.1 — 2026-06-30
- Fixed a typo in the release checklist.
- Tightened the frontmatter description so the skill loads more reliably.

Three details separate a useful changelog from a noisy one. First, always include the date — skills evolve faster than most code, and “recently” is not searchable. Second, describe the change in the reader’s terms, not in terms of what you edited in the file. “Added rollback steps” beats “expanded section 3.” Third, call out anything that is not backward compatible (see below) in a way that is impossible to miss.

Backward compatibility: the question that decides everything

Most skill updates should be backward compatible. The skill loads the same way, accepts the same frontmatter fields, and produces the same outputs for the workflows that already work. You are just adding a new example or fixing a typo. That is a patch or a minor.

A skill breaks backward compatibility when a reader has to edit something on their side to keep using it. The classic cases:

  • You renamed a required frontmatter field.
  • You removed a section that another skill or workflow explicitly referenced.
  • You changed the meaning of an existing instruction in a way that changes the output.
  • You restructured the folder so files the reader’s automation pointed at no longer exist.

In every one of those cases, the change is a major version bump, and the changelog entry should say so out loud. Something like:

## 2.0.0 — 2026-10-15 — BREAKING
- Renamed frontmatter field `summary` to `description`. Old
  `summary` values are ignored; update your SKILL.md.
- Moved examples out of `SKILL.md` into `references/examples.md`.
  Workflows that read examples from the skill root must be updated.

This is also where a one-sentence migration note earns its keep. Tell the reader exactly what to do, not just what changed.

When to update a skill vs. create a new one

This is the question indie founders hit the moment a platform release changes the format.

Update the existing skill when the change is local: a new field, a clarified behavior, a renamed concept. Your changelog entry, your version bump, and your readers can all absorb it in one pass.

Create a new skill when the change is structural: a different frontmatter schema, a different folder layout, a different way of declaring when the skill should load. Trying to bend the old skill into the new shape usually produces a file that works on one platform and silently fails on another. A separate skill, with its own version starting at 1.0.0, lets you keep the old one running while you migrate users at your own pace.

A useful test: if you would have to write a paragraph at the top of the changelog explaining a multi-step migration, that is a new skill, not an update.

A practical migration plan for your personal skills library

Most founders accumulate skills in a single folder, then panic the day Anthropic or OpenAI ships a breaking change. A small routine keeps that panic cheap.

  1. Inventory. Once a quarter, list every skill you have, what it does in one sentence, and the last version that touched a breaking change. A plain markdown table is fine.
  2. Pin a baseline. For each skill, record the platform versions and frontmatter schemas it was tested against. When a platform announces a change, you know exactly which skills are in scope.
  3. Read the platform changelog first, then your skill changelog. When Anthropic graduated Agent Skills and the Skills API out of beta, the immediate visible change was small — a beta header stopped being required — but the SDK (software development kit) migration that followed changed how skills get loaded in some flows. Reading both notes before touching any file saves you from patching the wrong layer.
  4. Migrate in this order. Fix the frontmatter and required fields first, because those break loading entirely. Then the folder structure, then the references and scripts, then prose-level instructions. Run your skill against a representative task after each layer.
  5. Keep the old version reachable. Until you have tested the new one end-to-end, do not delete the old skill file. Rename it to my-skill.v1.md or move it into an archive/ folder. If the migration reveals a real-world regression, you can roll back in seconds.
  6. Bump the version, write the changelog, then ship. The discipline of writing the changelog entry before you ship forces you to describe the change the way a reader will experience it, which is usually the most useful description anyway.

A worked example

Say you have a skill called release-notes that turns a commit list into a customer-facing release note. It started at 1.0.0, and over three months you added a “known issues” section (1.1.0), a fix to a date-format bug (1.1.1), and a clearer frontmatter description (1.1.2).

Then the platform you target introduces a new optional frontmatter field, audience, that you want to start using to mark skills as internal vs. external. You add it, document it, and ship 1.2.0. Backward compatible, no migration needed.

Six months later, the platform renames audience to visibility and makes it required for skills that touch customer-facing content. That is a breaking change for any reader whose automation explicitly sets audience. You ship 2.0.0 with a clearly labeled BREAKING entry, a migration note (“find-and-replace audience: with visibility: in your overrides”), and you keep 1.2.0 in archive/ for one release cycle.

That is the whole loop. The skill now has a history a reader can trust.

Frequently asked questions

Do I need to version a skill that only I use? Yes, but you can keep the discipline light. A single Last updated: line at the top of SKILL.md plus a one-line note about what changed is enough to keep your future self honest.

Where should I store the version number? Inside the skill’s folder, either as a VERSION file with the three-part number, or as a version field in the frontmatter if the platform supports it. The Claude Skills API, for example, exposes a latest_version field per skill, which means version identifiers are part of how skills are addressed there.

How often should I bump versions? Whenever the change matches one of the rules. There is no value in batching three unrelated changes into one minor release; your future self will not remember which change broke which workflow.

What if a platform changes the frontmatter schema overnight? Treat that as a major version bump for every affected skill. Use the migration plan above, keep the old version archived, and resist the urge to rewrite all skills in one sitting. A staged migration is faster in practice than a big-bang one.

Is semantic versioning overkill for plain prompt instructions? For one-off prompts, yes. For anything you reuse across projects, across clients, or across platform updates, no. The cost of writing 1.4.2 is trivial; the cost of not knowing which copy of a skill you are running compounds quickly.

Sources