Versioning your capability the right way
Versioning your capability the right way
Buyers — especially agents — depend on your capability being stable. A breaking change pushed silently to latest can break production pipelines. This guide covers versioning best practices for ai-supply.store providers.
Use semantic versioning
ai-supply.store expects versions in semver format: MAJOR.MINOR.PATCH.
| Change type | Which number to bump |
|---|---|
| Breaking change (removed tool, changed schema) | MAJOR |
| New feature, backward-compatible | MINOR |
| Bug fix or security patch | PATCH |
Examples: 1.0.0 → 1.1.0 (new tool added) → 1.1.1 (bug fix) → 2.0.0 (tool renamed).
Every version triggers a fresh security scan
Uploading a new version starts a new scan pipeline. This is good: if a dependency released a CVE since your last upload, the scan will catch it. Keep this in mind:
- New versions may receive a different security score than the previous version.
- If the new scan results in
QUARANTINE, the new version is blocked — but the previous version remains live. - Always test locally before uploading.
Write a changelog entry
Every new version should include a changelog note in the listing description. Use a simple Markdown format:
## Changelog
### 1.2.0 — 2026-06-10
- Added `search_web` tool
- Improved error messages on rate-limit responses
### 1.1.1 — 2026-05-20
- Fixed null-pointer in `summarise` when input is empty
### 1.1.0 — 2026-05-01
- Initial public release
Buyers and agents read changelogs before upgrading — make yours useful.
Deprecating old versions
You can deprecate (but not delete) older versions from your dashboard. Deprecated versions:
- Remain installable via
npx ai-supply add <slug>@<version> - Display a deprecation warning to buyers
- Are excluded from the
latestpointer
Deprecation protects existing integrations while steering new installs to the current version.
Pinning versions for agents
Agents that install capabilities should always pin to a specific version to avoid unexpected breaking changes:
npx ai-supply add my-capability@1.1.0
Unpinned installs (npx ai-supply add my-capability) always resolve to latest. That's fine for humans experimenting, but risky for production agents.
Breaking changes and major versions
When you ship a MAJOR version:
- Keep the old MAJOR alive as a deprecated version.
- Announce the migration in the community with a post in Announcements or Tutorials.
- Update your listing description with a migration guide.
- Give a minimum 30-day overlap period before fully sunsetting the old major.
Version integrity
ai-supply.store stores a cryptographic hash of every uploaded artifact. Buyers can verify the hash with:
npx ai-supply verify <slug>@<version>
This ensures what they installed matches what you uploaded — even if the delivery network is compromised.
For guidance on what makes a capability safe to publish, see how security scanning works.