How to Version and Update Your OpenClaw Skills

Publishing a skill on the OpenClaw Bazaar is only the beginning. As frameworks evolve, best practices shift, and users report issues, you need a reliable system for shipping updates without breaking existing installations. This guide covers semantic versioning for OpenClaw skills, publishing updates, handling breaking changes, and changelog practices that keep your users happy.

Why Versioning Matters for Skills

When someone installs your skill from the OpenClaw Bazaar skills directory, they are trusting that it will work with their project. If you push an update that changes behavior without warning, their agent might start producing different output, breaking their workflow.

Versioning solves this by giving both you and your users a shared language for communicating what changed and how significant the change is.

Semantic Versioning for OpenClaw Skills

OpenClaw skills follow semantic versioning (semver) using the format MAJOR.MINOR.PATCH. Here is what each number means in the context of a skill:

• MAJOR (e.g., 2.0.0): Breaking changes that alter the agent's behavior in ways that could disrupt existing workflows
• MINOR (e.g., 1.1.0): New instructions, additional code examples, or expanded coverage that does not change existing behavior
• PATCH (e.g., 1.0.1): Typo fixes, clarifications, and minor wording improvements

Setting Your Initial Version

Every new skill starts at version 1.0.0. Set this in your skill's frontmatter:

---
name: react-testing-vitest
description: React Testing Library patterns with Vitest
version: 1.0.0
author: your-github-username
tags: [react, testing, vitest]
---

Resist the temptation to start at 0.x.x. Users on the Bazaar expect skills to be functional when they install them. Starting at 1.0.0 signals that your skill is ready for production use.

Publishing Updates

When you are ready to ship an update, the process has three steps: bump the version, update the changelog, and publish.

Step 1: Bump the Version

Edit your skill.md frontmatter to reflect the new version number:

---
name: react-testing-vitest
description: React Testing Library patterns with Vitest
version: 1.1.0
author: your-github-username
tags: [react, testing, vitest]
---

Step 2: Update the Changelog

Add a CHANGELOG.md file to your skill's directory. Follow the Keep a Changelog format:

# Changelog

## [1.1.0] - 2026-03-29

### Added
- Instructions for testing async components with \`waitFor\`
- Code examples for mocking API calls with MSW
- Coverage for Vitest snapshot testing patterns

## [1.0.0] - 2026-03-15

### Added
- Initial release with core React Testing Library patterns
- Vitest configuration instructions
- Accessible query preferences (getByRole over getByTestId)

Step 3: Publish the Update

Push your changes to the skill's GitHub repository, then run the publish command:

openclaw skill publish --bump minor

This validates the version bump, checks the changelog, and pushes the update to the Bazaar. Users who have your skill installed will see a notification the next time they run openclaw skill list.

Handling Breaking Changes

Breaking changes deserve special care. A breaking change is anything that alters the agent's existing behavior in a way that could surprise users. Common examples include:

• Removing instructions that users relied on
• Changing preferred patterns (e.g., switching from jest to vitest conventions)
• Restructuring the skill so that existing configurations no longer apply
• Renaming the skill or changing its primary scope

The Breaking Change Workflow

When you need to ship a breaking change, follow this workflow:

# 1. Create a migration guide
touch MIGRATION.md

# 2. Update the changelog with a "Breaking" section
# 3. Bump the major version
openclaw skill publish --bump major

Your MIGRATION.md should include concrete before-and-after examples:

# Migration Guide: v1.x to v2.0

## Breaking Changes

### Test structure convention changed

**Before (v1.x):** Tests used \`describe/it\` blocks
**After (v2.0):** Tests use \`describe/test\` blocks

### Action required
Update existing test files to use \`test\` instead of \`it\`:

Before:
\`\`\`typescript
it('should render the component', () => {
  // ...
});
\`\`\`

After:
\`\`\`typescript
test('renders the component', () => {
  // ...
});
\`\`\`

Deprecation Warnings

For major changes, consider a two-step approach. First release a minor version that includes deprecation notices in the instructions:

> **Deprecated:** The \`fireEvent\` pattern will be removed in v2.0.
> Use \`userEvent\` instead. See the migration guide for details.

Then ship the major version with the actual removal. This gives users time to prepare.

Version Pinning

Users can pin a specific version of your skill to avoid unexpected updates:

openclaw skill install react-testing-vitest@1.2.0

They can also use range syntax to accept only patches:

openclaw skill install react-testing-vitest@~1.2.0

Or accept minors but not majors:

openclaw skill install react-testing-vitest@^1.2.0

Encourage users to pin to a major version (^1.0.0) at minimum so they get improvements without breaking changes.

Changelog Best Practices

A good changelog is one of the most useful things you can maintain. Follow these practices:

1. Write for humans, not machines. Describe what changed in terms of agent behavior, not file diffs.
2. Group changes by type. Use Added, Changed, Deprecated, Removed, Fixed, and Security sections.
3. Include dates. Every version entry should have a release date.
4. Link to issues. If a change addresses a reported issue, reference it.
5. Keep it in the repo. The changelog should live alongside the skill files so users can read it before updating.

Example of a Well-Written Changelog Entry

## [1.3.0] - 2026-03-29

### Added
- Instructions for testing React Server Components
- Code examples for parallel data fetching patterns

### Changed
- Updated Vitest config examples to use v3.x API
- Improved clarity of async testing instructions

### Fixed
- Agent no longer suggests deprecated \`cleanup\` calls (auto-cleanup is default in RTL 15+)

Automating Version Management

If you maintain multiple skills, automate the version bump and changelog process. Create a simple script in your skill repo:

#!/bin/bash
# scripts/release.sh

BUMP_TYPE=${1:-patch}
CURRENT_VERSION=$(grep 'version:' skill.md | sed 's/version: //')

echo "Current version: $CURRENT_VERSION"
echo "Bump type: $BUMP_TYPE"

# Validate changelog has an entry for the new version
if ! grep -q "## \[Unreleased\]" CHANGELOG.md; then
  echo "Error: No [Unreleased] section in CHANGELOG.md"
  exit 1
fi

# Run the publish command
openclaw skill publish --bump "$BUMP_TYPE"

echo "Published successfully!"

Make it executable and run it when you are ready to release:

chmod +x scripts/release.sh
./scripts/release.sh minor

Summary

Versioning your OpenClaw skills properly is a sign of respect for your users. Use semver to communicate the scope of changes, maintain a human-readable changelog, and handle breaking changes with migration guides. Your users on the Bazaar will thank you for it.

Browse the Skills Directory

Find the right skill for your workflow. The OpenClaw Bazaar skills directory has over 2,300 community-rated skills — searchable, sortable, and free to install.

Browse Skills →

Built a Skill? List It on the Bazaar

If you have built a skill that others would find useful, publish it on the Bazaar. Reach thousands of developers and get feedback from the community.

Learn how to publish →