SemVer Bumping Rules for Garden Skills: The Complete Contributor Guide

Garden Skills enforces strict Semantic Versioning where typo fixes require patch bumps, workflow changes require minor bumps, and breaking changes like renamed skills require major bumps.

Each skill in the Garden Skills repository operates as an independent package with its own manifest.json file that declares the current version. When contributing changes, understanding the specific SemVer bumping rules ensures your releases align with the automated validation in the release-skill GitHub Action.

SemVer Categories and Bump Rules

The contribution guidelines in CONTRIBUTING.md define exactly which changes trigger each version component increment.

Patch Bumps (x.y.z → x.y.(z+1))

Patch bumps cover backward-compatible, non-functional edits that do not alter execution flow. Apply a patch increment when you fix typos, add new optional references, or make micro-edits to SKILL.md. These changes maintain full compatibility with existing consumers.

Minor Bumps (x.y.z → x.(y+1).0)

Minor bumps signal added functionality or restructuring that does not break existing implementations. Trigger a minor version increment when you modify workflows in SKILL.md, restructure the references/ directory, or introduce new required steps. Consumers receive new capabilities without forced migration.

Major Bumps (x.y.z → (x+1).0.0)

Major bumps denote breaking changes requiring downstream users to adjust their code. Increment the major version when you rename a skill, remove files, or modify front-matter fields in ways that break dependent tooling. These releases explicitly signal incompatibility with previous versions.

Automated Release Validation

The repository's CI pipeline automatically validates every release through the release-skill GitHub Action. When you push a tag, the action compares the tag version against the version declared in the skill's manifest.json. If the versions drift—for example, a tag requesting 1.1.0 while the manifest remains at 1.0.0—the CI fails and blocks the release. This enforcement mechanism prevents version mismatches and ensures the manifest.json always reflects the released state.

Manual Version Bumping Examples

When preparing a release manually, update the version field in your skill's manifest.json and create a matching git tag.

Bump a patch version for typo fixes:

jq '.version = "1.0.1"' skills/web-design-engineer/manifest.json > tmp.json && mv tmp.json skills/web-design-engineer/manifest.json
git commit -am "chore(web-design-engineer): bump patch to 1.0.1"
git tag web-design-engineer-v1.0.1
git push origin main web-design-engineer-v1.0.1

Bump a minor version for workflow changes:

jq '.version = "1.1.0"' skills/web-design-engineer/manifest.json > tmp.json && mv tmp.json skills/web-design-engineer/manifest.json
git commit -am "feat(web-design-engineer): bump minor to 1.1.0"
git tag web-design-engineer-v1.1.0
git push origin main web-design-engineer-v1.1.0

Bump a major version for breaking changes:

jq '.version = "2.0.0"' skills/web-design-engineer/manifest.json > tmp.json && mv tmp.json skills/web-design-engineer/manifest.json
git commit -am "refactor(web-design-engineer): bump major to 2.0.0"
git tag web-design-engineer-v2.0.0
git push origin main web-design-engineer-v2.0.0

Helper Scripts and Automation

Most contributors use the interactive npm run release script instead of manual edits. This script automatically detects the required bump type based on your changes and executes the commit and tag operations while respecting the classification rules from CONTRIBUTING.md. Alternative npm scripts defined in package.json include release:dry for testing workflows without creating tags, and readme:sync for updating documentation.

After any release, the scripts/release/update-readme.mjs script automatically updates the "Download" links in the main README to reflect the new versions.

Key Files in the Versioning System

• CONTRIBUTING.md — Contains the full versioning policy, release workflow description, and troubleshooting guide for CI failures.
• manifest.json (per-skill) — Stores the current version for each skill; serves as the source of truth for the release-skill validation.
• scripts/release/update-readme.mjs — Auto-updates download links in the main README after successful version bumps.
• package.json — Defines the npm scripts (release, release:dry, readme:sync) that automate SemVer enforcement.

Summary

• Garden Skills treats every skill as an independent package with isolated versioning tracked in individual manifest.json files.
• Patch bumps cover typo fixes, optional reference additions, and micro-edits to documentation.
• Minor bumps cover workflow changes in SKILL.md, references/ restructuring, and new required steps.
• Major bumps cover breaking changes including skill renames, file removals, and breaking front-matter modifications.
• The release-skill GitHub Action enforces strict alignment between git tags and manifest.json versions, failing CI on any mismatch.

Frequently Asked Questions

What happens if my git tag version doesn't match the manifest.json version?

The release-skill GitHub Action will fail the CI pipeline and block the release from publishing. You must correct either the tag or the manifest.json version so they align exactly before pushing again, as documented in the troubleshooting section of CONTRIBUTING.md.

Can I manually edit the version in manifest.json?

Yes, you can manually update the version field using tools like jq or a text editor, but most contributors prefer the npm run release script which handles version detection and bumping automatically based on your change classification.

How do I know if my change requires a major version bump?

Any modification that breaks existing consumer implementations—such as renaming the skill directory, removing required files, or modifying front-matter fields that downstream tools depend on—requires a major bump according to the CONTRIBUTING.md guidelines.

Does Garden Skills use a single version for the entire repository?

No. Each skill maintains its own independent version in its respective manifest.json file, allowing individual skills to evolve at different rates without affecting the global repository state or forcing monolithic version increments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}