Versioning and safe updates

Releases are immutable

Once @ns/slug@1.2.0 is published, its archive, manifest, file list and SHA-256 never change. The database refuses updates and deletions of release content, independently of the application. Publishing the same version again returns 409 version_exists.

What can change after publication:

To correct a release, publish a new version.

Version numbers

Strict semantic versioning, without build metadata.

• MAJOR — existing users must change something: removed or renamed behaviour, new required permissions or secrets.
• MINOR — additions that do not break existing use.
• PATCH — fixes.
• Prereleases (2.0.0-beta.1) are published like any version but never become latest while a stable version exists.

latest is the highest stable published version. Revoking it moves latest back to the best remaining one.

A change in what a package may do — new scripts, new network use, a new declared permission — deserves at least a minor bump and a line in the release notes. Installers compare what they agreed to before with what they are getting now.

Dependencies

"dependencies": [
  { "name": "@research/citation-check", "version": "^1.2.0" },
  { "name": "@research/latex-tools", "version": "1.0.3", "optional": true }
]

• version is a semver range (^1.2.0, ~1.2.0, >=1.0.0 <2.0.0, or an exact version).
• At publication, each required dependency must exist in the registry and have at least one published version that satisfies the range. Otherwise the release is rejected (dependency-unknown, dependency-unsatisfied). Optional dependencies produce a note instead.
• A package cannot depend on itself or list a dependency twice.
• The registry records dependencies and shows them. It does not resolve or install dependency trees for you in this version; install each one deliberately.

For reproducible work, pin exact versions. A range that was safe yesterday can match a new release tomorrow.

Bundles

A bundle is a named set of other artifacts. Because its purpose is reproducibility, every dependency must be an exact version:

{
  "type": "bundle",
  "dependencies": [
    { "name": "@research/citation-check", "version": "1.2.0" },
    { "name": "@research/latex-tools", "version": "1.0.3" }
  ]
}

A range in a bundle is a blocking error (bundle-unlocked-dependency). To move a bundle forward, publish a new bundle version with new pins.

Permissions

permissions in the manifest states what the package needs: filesystem:read, filesystem:write, network, shell, env, mcp, browser, credentials. They are shown on the artifact page and before install.

The scanner adds a finding when scripts appear to use the network or spawn processes but the manifest does not declare network or shell. Declare honestly: an under-declared package looks worse than one that asks for what it uses.

Updating safely, as a user

1. Read the release notes of the new version.
2. Compare: file list, declared permissions and findings are on each version's page.
3. Install the specific version: skills update @ns/slug --client claude-code or skills install @ns/slug@1.3.0 …. The CLI verifies the checksum, shows the destination, keeps the previous copy in ~/.skills-registry/backups/, and runs nothing.
4. If something is wrong, restore the backup or install the earlier version by number. Earlier versions stay downloadable unless revoked.

The .skills-registry.json file in an installed directory records which version and checksum you have.

Deprecation

Deprecating says "this still works, but use something else". It requires a reason, which is shown on the page, and confirmation. Downloads continue. It can be undone.

skills deprecate @ns/slug --reason "Superseded by @ns/new-slug, which supports the 2026 citation styles."

Archiving closes an artifact to new releases and removes it from listings; existing versions stay reachable by link.

Both need the artifacts:deprecate scope, which the default publisher token does not carry.

Revocation

Revoke a version that is harmful: a leaked secret, a malicious dependency, a destructive bug.

skills revoke @ns/slug@1.2.0 --reason "Shipped a script that deletes the wrong directory. Use 1.2.1."

• Downloads of that version return 410 Gone with your reason.
• The version stays in the history, marked revoked, with its checksum and metadata.
• latest moves to the best remaining version.
• It cannot be undone. Publish a fixed version.

If the revoked version contained a secret, revocation does not un-leak it. Rotate the secret.

History

Every artifact has a public history: creation, each publication, deprecation, revocation, with the publisher's display name and the time. It is drawn from an append-only audit log.