Versions and history

By default, new sessions pick up the latest available skill. In production, you may want to test how an update changes your agent's behavior before adopting it. Versions let you stay on a known release or accept only a chosen range of updates.

Give a skill a version

A versioned skill includes a full SemVer value in metadata.version, such as 1.0.0:

---
name: howdy
description: Greet someone with a friendly cowboy welcome.
metadata:
  version: "1.0.0"
---

When greeting someone, say "Howdy partner!" and offer to help.

The first build goes into release-1.0.0/:

npm exec -- remote-skills build --out-dir release-1.0.0

After editing the instructions and changing the version to 1.0.1, the next build can carry 1.0.0 forward with --prior-output:

npm exec -- remote-skills build --out-dir release-1.0.1 --prior-output release-1.0.0

release-1.0.1/ now contains both releases and is the complete output to host. The builder verifies release-1.0.0/ before carrying its files forward. Without --prior-output, it builds only the current source; it does not search other folders or the live host for older releases.

A version identifies fixed content. If the prior output already contains howdy@1.0.0, rebuilding that same version with changed instructions is an error. Giving the edited skill a new version, such as 1.0.1, keeps both releases unambiguous.

Select a compatible release

The SDK accepts a version range when loading a skill. This example allows updates within 1.0.x, selecting 1.0.1 from the two releases above:

import { createRemoteSkills } from "@remote-skills/client";

const client = createRemoteSkills({
  origins: { team: { url: "https://skills.example.com" } },
});

const session = await client.session("team");
try {
  const skill = await session.activate("howdy", "~1.0.0");
  console.log(skill.version); // 1.0.1 for the releases built above
} finally {
  await session.close();
}

The client chooses the newest stable release the publisher still offers that matches your range:

For a patch-only policy, ~1.4.2 is the useful distinction: SemVer range notation treats ^1.4.2 more broadly. Version labels communicate the publisher's intent; they do not guarantee that an update leaves your agent's behavior unchanged.

Prereleases such as 1.5.0-beta.1 are excluded unless the range explicitly opts into that prerelease series. If no offered release matches—or a version restriction is applied to an unversioned skill—the SDK returns version_unavailable.

Remove an old release

Publishers can stop offering an older release with --prune SKILL@VERSION during a build. Once that output is deployed, new online sessions choose from the remaining releases. If none matches a consumer's range, loading fails—even if the removed release was downloaded earlier. A range controls selection; it does not require the publisher to keep a release available forever. The CLI reference covers the command.

Running tasks are unaffected: an existing session keeps the release it selected. An application that explicitly allows an older cached catalog may also continue selecting that release until its stale-catalog allowance expires. Caching and updates explains that offline tradeoff.

The API reference describes the catalog fields and history limits for custom integrations.