Versions & Releases

Every skill has a single editable draft plus a history of immutable releases. Claude Code loads the release you've promoted to stable — never the draft (unless a skill is flagged experimental). You can promote any release, roll back instantly, and restore an old release back into your draft to keep building from it. Agents, workflows, commands, and guardrails version exactly the same way — see Agent versions, Workflow versions, Command versions, and Guardrail versions below.

The model

Skill versioning borrows git's mental model:

Git	Skill versioning
Working directory	Draft — the live, always-editable skill content
Commits (immutable)	Releases — frozen snapshots, each with a title and optional notes
A tag like `stable`	Stable — a movable pointer to the one release everyone runs
`git restore`	Restore to draft — copy a release back into the working copy

Releasing copies the draft into history — it doesn't consume it. Your draft keeps drifting ahead while past releases stay frozen. Versioning is format-agnostic: it works the same for structured and markdown skills.

Creating a release

On a skill's Versions page, click New Release to freeze the current draft into a new immutable version. The release modal captures:

Title — required, up to 80 characters (e.g. "Tighten review rules").
Notes — optional markdown release notes.

Each release gets a monotonic version number (v1, v2, v3…) for display. The very first release is automatically promoted to stable.

Promote & roll back

Promote points the stable pointer at a release. Use it to ship a freshly-created release, or point it at an older release to roll back instantly. Promote touches only the stable pointer — your draft and your full history are untouched. The currently-promoted release is marked with a Stable badge.

Restore to draft

Restore to draft copies a chosen release's content back into your live draft so you can build forward from it again. This touches only the draft — it never moves the stable pointer and never deletes or rewinds any release.

Nothing is lost

Restoring overwrites your current draft, so SuperClawd auto-snapshots the draft into a new release first ("saved as v6 before reverting"). History is append-only — your old releases always remain.

How releases are served

When Claude Code fetches your skills, each skill resolves like this:

It serves the skill's stable release — the promoted snapshot.
If a skill has no promoted release, it is skipped entirely. There is no fallback to the draft — a skill becomes servable only once it has a stable release.
The one exception is Experimental mode: a skill flagged experimental serves its live draft when the CLI session is also experimental.

Release before you expect a skill to load

A brand-new skill that you've only edited (never released) will not load in normal mode. Create a release and it auto-promotes to stable on the first one.

Agent versions

Agents (your workspace's Claude Code subagents) use the exact same versioning model: a single editable draft, an append-only history of immutable releases — each with a required title and optional notes — and a movable stable pointer. Promote, roll back, and restore-to-draft all behave identically, and the first release of an agent auto-promotes to stable.

The one difference from skills is shape: an agent is a flat snapshot of the whole subagent definition. When Claude Code fetches your catalog, a released agent is served whole — the full definition at once — rather than resolved piece by piece on demand. Serving follows the same rule as skills:

An agent serves its promoted stable release.
An agent with no promoted release is skipped entirely — there is no fallback to the draft.
An agent flagged experimental serves its live draft when the CLI session is also experimental (see Experimental mode).

Existing agents were given a v1

When agent versioning shipped, every existing agent was automatically captured as a stable v1, so nothing stopped being served. From there, the usual draft → release → promote flow applies.

Workflow versions

Workflows version the same way, with one wrinkle: a release snapshots the whole graph — every node and every edge — as one immutable version. The same single editable draft, append-only release history (each with a required title and optional notes), and movable stable pointer apply, and promote, roll back, and restore-to-draft behave identically. The first release of a workflow auto-promotes to stable.

When Claude Code fetches your catalog, a workflow's released graph is served through the workflow catalog plus on-demand details, and serving follows the same rule as skills:

A workflow serves its promoted stable release — the frozen graph.
A workflow with no promoted release is skipped entirely — there is no fallback to the draft.
A workflow flagged experimental serves its live draft graph when the CLI session is also experimental (see Experimental mode).

Existing workflows were given a v1

When workflow versioning shipped, every existing workflow was automatically captured as a stable v1 — its current graph — so nothing stopped being served. From there, the usual draft → release → promote flow applies.

Command versions

Commands version the same way, and a release snapshots the command's body and its arguments together as one immutable version — so the executed prompt and the argument definitions always travel as a single unit. The same single editable draft, append-only release history (each with a required title and optional notes), and movable stable pointer apply, and the first release of a command auto-promotes to stable.

A command serves through two paths — a catalog stub (the slash command's name and argument hint) and an on-demand fetch of the body when it's invoked — and both honor the same release/experimental gate, so the argument hint a user sees and the body that actually runs always come from the same version:

A command serves its promoted stable release — body and arguments frozen together.
A command with no promoted release is skipped entirely — there is no fallback to the draft.
A command flagged experimental serves its live draft — body and arguments — when the CLI session is also experimental (see Experimental mode).

Existing commands were given a v1

When command versioning shipped, every existing command was automatically captured as a stable v1 — body and arguments — so nothing stopped being served. From there, the usual draft → release → promote flow applies.

Guardrail versions

Guardrails version the same way, and a release snapshots the rule's description, match, action, and message together as one immutable version. The same single editable draft, append-only release history (each with a required title and optional notes), and movable stable pointer apply, and the first release of a guardrail auto-promotes to stable. Because guardrails are enforced for the whole team, the release gate lets you test a draft rule in an experimental session before it goes live for everyone:

A guardrail enforces its promoted stable release in every member's session.
A guardrail with no promoted release is not enforced — there is no fallback to the draft.
A guardrail flagged experimental enforces its live draft when the CLI session is also experimental (see Experimental mode).

Guardrails can also be shared via unlisted, revocable share links (once they have a stable release) and exported / imported as JSON — see Guardrails and Community Guardrails.

Existing guardrails need a first release

Unlike commands, guardrail versioning shipped with no backfill: a guardrail created before versioning has no stable release and won't enforce until you publish and promote it once. Publish a release (it auto-promotes to stable) to start enforcing it again.

The Versions page

Each skill has a dedicated Versions page where all of this lives. Reach it from the Versions button on the skill detail page (and on the markdown body page), or the Versions item in the skill list's 3-dots menu. The page shows:

The New Release button.
A paginated release list reading v{n} · title · date with the author.
Promote on any release (including older ones to roll back), with a Stable badge on the current one.
Restore to draft on any release.
A banner explaining how serving currently works for this skill.

In the skill list, badges are composable: a Stable or Draft badge shows the release state, and an amber Experimental badge appears when the skill is flagged. Admins and maintainers manage versions; members have read-only access.

A promoted stable release is also what makes a skill shareable — see Sharing & Imports.