Semver Range

• A semver range is a version-constraint syntax that describes a set of acceptable versions rather than pinning a single one. Guild uses it wherever versioned artifacts (skills, integrations, agents) reference other versioned artifacts.
• Guild follows the same semver-range conventions as npm. The caret (^1.4.0) allows compatible minor and patch versions but not the next major version. Exact versions (1.4.0) pin absolutely.
• Each new version of a Guild artifact must have a version number greater than the latest existing version. You cannot re-publish a version number.
• Semver ranges let dependencies pick up bug fixes and minor improvements automatically without breaking on major-version upgrades. Exact pins give you control at the cost of manual updates.

A semver range is a syntax for describing which versions of a package or artifact are acceptable, not just a single one. Instead of saying "use version 1.4.0 exactly," a semver range like ^1.4.0 says "any 1.x.y version that is at least 1.4.0." It is the language dependency systems use to balance stability and continuous improvement.

Semver itself — semantic versioning — is a convention where version numbers take the shape MAJOR.MINOR.PATCH. A major bump signals a breaking change. A minor bump adds functionality in a backward-compatible way. A patch bump fixes bugs without changing behavior. Semver ranges use this structure to say "give me anything that is compatible with what I asked for."

Guild follows the same semver conventions the npm ecosystem uses, so if you have worked with package.json before, the syntax will look familiar.

The caret operator: compatible minor and patch

A caret (^) allows updates that do not change the leftmost non-zero component. ^1.4.0 accepts 1.4.0, 1.4.1, 1.5.0, and any 1.x.y going forward, but rejects 2.0.0. It is the default for most dependencies because it captures bug fixes and new features without pulling in breaking changes.

Exact pins: absolute control

An exact version like 1.4.0 pins to that version and only that version. Nothing else will satisfy the constraint. Use this when you cannot afford any drift, or when you are debugging and need to isolate a specific behavior.

Tilde and other range operators

Semver has additional operators — the tilde (~) allows only patch-level changes within a minor version, comparators like >=1.4.0 <2.0.0 spell out the range explicitly, and hyphen ranges like 1.4.0 - 1.7.0 define inclusive spans. Most Guild dependencies work with caret or exact pins; the more elaborate operators exist for cases that call for them.

Versions must always move forward

In Guild, every new version of a skill, an integration, or another versioned artifact must have a version number greater than the latest existing version. You cannot re-publish a version number. This rule shows up on every guild skill version create call, on integration builds, and anywhere else Guild tracks version history.

Ranges make ecosystems work

If every dependency had to be pinned to an exact version, no fix or improvement would ever propagate without a manual update on every consumer. Semver ranges are the mechanism that lets published versions get better over time while keeping consumers safe from breaking changes.

Semver conveys intent, not just position

The version number is a claim about compatibility. A skill maintainer bumping from 1.4.0 to 1.5.0 is saying "this is backward-compatible." A bump to 2.0.0 is saying "this breaks things." Consumers pick a range that matches how much drift they can tolerate.

Guild versions live in a shared registry

Skills, integrations, and agents are all versioned inside Guild. When one artifact references another (an agent using a skill, an integration exposing operations at a specific version), the range syntax decides which versions of that other artifact are acceptable. Getting the range right at declaration time avoids a lot of debugging later.

Reproducibility is a range problem

Two people working on the same agent should get the same behavior. Ranges that are too loose can produce silent drift between environments. Ranges that are too tight force every update to be manual. Choosing well per artifact is what makes an ecosystem both stable and alive.

Publishing new versions in Guild

guild skill version create myorg~tone-guide \  --version-number 1.0.0 \  --description "Guides the agent to use brand-appropriate tone and messaging" \  --body-file tone-guide.md
guild skill version create myorg~tone-guide \  --version-number 1.1.0 \  --description "Adds specific guidance for internal announcements" \  --body-file tone-guide.md

Each new --version-number must be greater than the latest existing version. Skills follow semver, so 1.1.0 adds functionality in a backward-compatible way, 1.1.1 would be a bug fix, and 2.0.0 would signal a breaking change.

Common range choices

• ^1.4.0 — accept any 1.x version at or above 1.4.0. Default for most cases.
• ~1.4.0 — accept 1.4.x patches but not 1.5.0. Use when you want new patches but not new features.
• 1.4.0 — exact pin. Use when reproducibility matters more than staying current.
• >=1.4.0 <2.0.0 — explicit range. Equivalent to ^1.4.0, useful when you want to be explicit.

Publishing versioned integrations

guild integration version build <id_or_name> --version-number 1.0.0guild integration version publish <id_or_name> --version-number 1.0.0

Integrations follow the same semver rules. Build a version to validate it, then publish to make it available. Version numbers only move forward.

Prefer caret ranges unless you have a reason not to

The default should be ^X.Y.Z for most dependencies. It captures fixes and minor improvements without pulling in breaking changes. Exact pins should be a deliberate choice, not a habit.

Version numbers only move forward

Guild rejects any attempt to publish a version number that is less than or equal to the latest existing one. If you need to fix a shipped version, publish a new one at a higher number and update anything pinned to the old one.

Major versions are contracts, not marketing

A bump from 1.9.0 to 2.0.0 is a signal to every consumer that something breaking has changed. Do not use major versions to announce features. Reserve them for actual breaking changes, or the semver contract stops meaning anything.

Ranges are only as good as the discipline of publishers

Semver ranges work when the people cutting versions honor semver. A patch bump that changes behavior in a breaking way defeats the whole system. When you publish a Guild artifact, use minor bumps for backward-compatible additions and reserve major bumps for real breaks.

Guild is a control plane for AI agents, a place to build, deploy, and govern the agents your teams run in production. Versioned skills, integrations, and agents mean the ecosystem can move without breaking, and semver ranges are the syntax that keeps drift under control.

• The Skills guide covers how versioned skills are created and consumed.
• The full CLI commands reference lists every version-related flag.
• Explore the Guild CLI and the rest of the platform at guild.ai.