Versioning & Yanking

Semantic Versioning

All skill versions must follow Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH

• MAJOR — Breaking changes (e.g., removed instructions, changed MCP server interface)
• MINOR — New features, added instructions (backward compatible)
• PATCH — Bug fixes, typo corrections, clarifications

Examples: 1.0.0, 2.1.0, 0.5.3, 1.0.0-beta.1

Version rules

• Each version number can only be published once — you cannot overwrite an existing version
• Versions must increase — you cannot publish 1.0.0 after 1.1.0
• Pre-release versions are supported (e.g., 1.0.0-beta.1)
• The version field in shipables.json is the source of truth

Publishing a new version

1. Make your changes to SKILL.md, scripts, references, etc.
2. Update version in shipables.json
3. Run shipables publish

# After making changes:
shipables publish

Dist-tags

By default, every publish is tagged as latest. You can publish under a different tag:

shipables publish --tag beta
shipables publish --tag next

Users can install tagged versions:

shipables install my-skill@beta

Yanking (unpublishing)

Yanking withdraws a version from the registry. Yanked versions:

• Don't appear in search results
• Can't be installed by default
• Reserve the version number — you can't reuse it

72-hour window

You can only yank a version within 72 hours of publishing. After that, the version is permanent.

This protects downstream users — if someone depends on your skill, yanking it could break their workflow.

How to yank

shipables unpublish my-skill@1.0.0

Or with force to skip confirmation:

shipables unpublish my-skill@1.0.0 --force

What to do instead of yanking

If you discover a problem after the 72-hour window:

1. Publish a patch version with the fix (e.g., 1.0.1)
2. Update the SKILL.md to note the issue in the previous version
3. Users running shipables update will get the fixed version

Version resolution

When a user installs without specifying a version:

shipables install my-skill

The registry resolves to the latest non-yanked version tagged as latest.

When a specific version is requested:

shipables install my-skill@1.2.0

That exact version is installed (if it exists and hasn't been yanked).