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 latest pointer

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:

1. Keep the old MAJOR alive as a deprecated version.
2. Announce the migration in the community with a post in Announcements or Tutorials.
3. Update your listing description with a migration guide.
4. 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.