Add plugin-version skill and bump plugin versions to 0.2.1 (#379)

* Add plugin-version skill and bump plugin versions to 0.2.1

Adds a new `plugin-version` skill for bumping Claude plugin semver
versions whenever plugins or the marketplace are modified. Updates
CLAUDE.md to reference the skill. Bumps all plugin versions to 0.2.1
and marketplace metadata to 1.1.1 as the initial versioned release.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* format

* update plugins

* update local plugins

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: borisno2

.claude-plugin/marketplace.json

@@ -6,15 +6,15 @@
   },
   "metadata": {
     "description": "Official OpenSaaS Stack plugin marketplace for development and migration tools",
-    "version": "1.1.0",
+    "version": "1.1.1",
     "homepage": "https://stack.opensaas.au/"
   },
   "plugins": [
     {
       "name": "opensaas-stack",
       "source": "./claude-plugins/opensaas-stack",
       "description": "Feature-driven development assistant for OpenSaaS Stack. Build complete applications by describing what you want to build instead of configuring infrastructure.",
-      "version": "0.2.0",
+      "version": "0.2.2",
       "author": {
         "name": "OpenSaaS",
         "url": "https://opensaas.au"
@@ -29,7 +29,7 @@
       "name": "opensaas-migration",
       "source": "./claude-plugins/opensaas-migration",
       "description": "OpenSaaS Stack migration assistant with AI-guided configuration, schema analysis, and code generation support",
-      "version": "0.2.0",
+      "version": "0.2.2",
       "author": {
         "name": "OpenSaaS Team",
         "url": "https://github.com/OpenSaasAU/stack"

.claude/skills/plugin-version/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: plugin-version
+description: Bump plugin versions in the OpenSaaS Stack monorepo. Invoke whenever any file under claude-plugins/* or .claude-plugin/ is modified — skills, commands, agents, or marketplace config. Plugin versions must be bumped before committing so users who install the plugin get the updated version. Note: this is separate from pr-changeset, which handles npm packages — plugin versions are managed directly in plugin.json and marketplace.json.
+allowed-tools: Read, Edit, Bash, Grep, Glob
+---
+
+# Plugin Version Skill
+
+This skill bumps version numbers for Claude plugins and the marketplace manifest. Plugin versions live directly in JSON files (not changesets) — bumping them is what signals to the marketplace that something changed and triggers users to get the update.
+
+## Files This Skill Manages
+
+| Changed directory                    | Files to update                                                                                                                                             |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `claude-plugins/opensaas-stack/`     | `claude-plugins/opensaas-stack/.claude-plugin/plugin.json` (version) AND `.claude-plugin/marketplace.json` (plugins[name="opensaas-stack"].version)         |
+| `claude-plugins/opensaas-migration/` | `claude-plugins/opensaas-migration/.claude-plugin/plugin.json` (version) AND `.claude-plugin/marketplace.json` (plugins[name="opensaas-migration"].version) |
+| `.claude-plugin/` root files only    | `.claude-plugin/marketplace.json` (metadata.version only)                                                                                                   |
+
+## Versioning Rules
+
+### Patch (bug fixes only)
+
+- **Use for**: Bug fixes, typo corrections, documentation fixes, minor wording improvements in skill descriptions
+- **Bump**: `x.y.Z` → `x.y.Z+1`
+- **Description**: Maximum 2 lines
+
+### Minor (features or enhancements)
+
+- **Use for**: New skills, new commands, new agents, new MCP tools, enhancements to existing capabilities
+- **Bump**: `x.Y.z` → `x.Y+1.0` (reset patch to 0)
+- **Description**: Describe the new capability
+
+### Major (breaking changes)
+
+- **Use for**: Removed skills/commands/tools, changed invocation patterns, incompatible changes
+- **ONLY when explicitly requested by the user**
+- **Bump**: `X.y.z` → `X+1.0.0` (reset minor and patch to 0)
+
+## Instructions
+
+### Step 1: Identify Changed Plugin Directories
+
+Run git commands to detect which plugin areas changed:
+
+```bash
+git diff --name-only HEAD
+# or for staged changes:
+git diff --name-only --cached
+# or for all changes relative to main:
+git diff --name-only origin/main...HEAD
+```
+
+Look for paths starting with:
+
+- `claude-plugins/opensaas-stack/` → opensaas-stack plugin changed
+- `claude-plugins/opensaas-migration/` → opensaas-migration plugin changed
+- `.claude-plugin/` → marketplace root changed (check if any file other than version fields changed)
+
+### Step 2: Determine Version Bump Type
+
+For each changed plugin:
+
+- **Is this a bug fix or correction?** → Use `patch`
+- **Is this a new skill, command, agent, or capability?** → Use `minor`
+- **Does this remove or rename something users depend on?** → Use `major` only if user explicitly requested it; otherwise ask
+
+### Step 3: Read Current Versions
+
+For each affected plugin, read the current version:
+
+```
+Read: claude-plugins/<plugin-name>/.claude-plugin/plugin.json
+```
+
+The version is in the top-level `"version"` field.
+
+For the marketplace:
+
+```
+Read: .claude-plugin/marketplace.json
+```
+
+The marketplace metadata version is at `metadata.version`. Each plugin's marketplace entry version is at `plugins[i].version` where `plugins[i].name` matches the plugin name.
+
+### Step 4: Calculate New Version
+
+Given the current version string `"x.y.z"`:
+
+- **patch**: increment z → `"x.y.(z+1)"`
+  - `"0.2.0"` → `"0.2.1"`
+  - `"1.3.4"` → `"1.3.5"`
+- **minor**: increment y, reset z to 0 → `"x.(y+1).0"`
+  - `"0.2.0"` → `"0.3.0"`
+  - `"1.3.4"` → `"1.4.0"`
+- **major**: increment x, reset y and z to 0 → `"(x+1).0.0"`
+  - `"0.2.0"` → `"1.0.0"`
+  - `"1.3.4"` → `"2.0.0"`
+
+### Step 5: Edit the JSON Files
+
+For each changed plugin, make two targeted edits using the Edit tool.
+
+**Edit 1 — The plugin's own plugin.json:**
+
+Find the `"version"` field near the top of the file and replace just that value.
+
+Example in `claude-plugins/opensaas-stack/.claude-plugin/plugin.json`:
+
+```
+"version": "0.2.0",
+```
+
+→
+
+```
+"version": "0.2.1",
+```
+
+**Edit 2 — The matching entry in marketplace.json:**
+
+The `plugins` array in `.claude-plugin/marketplace.json` has one object per plugin. Find the object where `"name"` matches the plugin name and edit its `"version"` field.
+
+Example: find the block for `"name": "opensaas-stack"` and edit:
+
+```
+      "version": "0.2.0",
+```
+
+→
+
+```
+      "version": "0.2.1",
+```
+
+**Edit 3 (conditional) — Marketplace metadata.version:**
+
+Only bump `metadata.version` if files in the `.claude-plugin/` root directory were directly changed (e.g., `MARKETPLACE.md`, new fields added to `marketplace.json` structure, owner/metadata fields edited). Do NOT bump it just because plugin versions changed.
+
+### Step 6: Verify the Edits
+
+After editing, read back the affected files to confirm:
+
+- The version field shows the new version
+- No other fields were accidentally changed
+- Both plugin.json and the matching marketplace.json entry show the same new version number
+
+## Examples
+
+### Example 1: Patch — Fix a typo in a skill description
+
+Changed files: `claude-plugins/opensaas-stack/skills/some-skill/SKILL.md`
+
+Current version: `"0.2.0"` → New version: `"0.2.1"`
+
+Edit `claude-plugins/opensaas-stack/.claude-plugin/plugin.json`:
+
+- `"version": "0.2.0"` → `"version": "0.2.1"`
+
+Edit `.claude-plugin/marketplace.json` (in the `opensaas-stack` plugins entry):
+
+- `"version": "0.2.0"` → `"version": "0.2.1"`
+
+Do NOT change `metadata.version` — the marketplace structure itself did not change.
+
+### Example 2: Minor — Add a new skill to opensaas-migration
+
+Changed files: `claude-plugins/opensaas-migration/skills/new-skill/SKILL.md` (new file)
+
+Current version: `"0.2.0"` → New version: `"0.3.0"`
+
+Edit `claude-plugins/opensaas-migration/.claude-plugin/plugin.json`:
+
+- `"version": "0.2.0"` → `"version": "0.3.0"`
+
+Edit `.claude-plugin/marketplace.json` (in the `opensaas-migration` plugins entry):
+
+- `"version": "0.2.0"` → `"version": "0.3.0"`
+
+### Example 3: Changes to both plugins
+
+Changed files include both `claude-plugins/opensaas-stack/...` and `claude-plugins/opensaas-migration/...`
+
+Determine bump type independently for each plugin based on the nature of its changes. They can be bumped to different versions.
+
+Edit `claude-plugins/opensaas-stack/.claude-plugin/plugin.json` with its new version.
+Edit `claude-plugins/opensaas-migration/.claude-plugin/plugin.json` with its new version.
+Edit `.claude-plugin/marketplace.json` twice — once for each plugin's entry.
+
+### Example 4: Marketplace-only change
+
+Changed files: `.claude-plugin/marketplace.json` (added a new top-level field) or `.claude-plugin/MARKETPLACE.md`
+
+The marketplace structure itself changed, so bump `metadata.version`.
+
+Current: `"version": "1.1.0"` → New: `"version": "1.1.1"` (patch)
+
+Edit `.claude-plugin/marketplace.json` `metadata.version` field only.
+Do NOT change any plugin.json files — no plugin logic changed.
+
+## Common Mistakes to Avoid
+
+1. **Don't bump metadata.version just because plugin versions changed**
+   - Plugin version entries in marketplace.json are synced from plugin.json
+   - Only bump metadata.version when the marketplace file's own structure changed
+
+2. **Don't forget the marketplace.json plugin entry**
+   - When you bump a plugin.json, always also update the matching entry in marketplace.json
+   - The two must stay in sync
+
+3. **Don't use major unless explicitly requested**
+   - New skills and commands are minor, not major
+   - Ask the user if you think a major bump is warranted
+
+4. **Don't reset patch to 0 on a patch bump**
+   - patch: `0.2.3` → `0.2.4` (not `0.2.0`)
+   - minor: `0.2.3` → `0.3.0` (reset patch)
+   - major: `0.2.3` → `1.0.0` (reset both)
+
+5. **Don't edit unrelated fields**
+   - Use Edit tool with precise old_string/new_string targeting just the version line
+   - Verify after editing that only the version changed
+
+6. **Don't create changeset files**
+   - This skill edits JSON files directly
+   - Plugin versions are NOT managed by the npm changeset system
+
+## Workflow
+
+When working on plugin changes:
+
+1. Make your plugin code changes
+2. Before committing, invoke this skill to bump versions
+3. Verify the JSON files show the correct new versions
+4. Commit all changed files together (plugin code + plugin.json + marketplace.json)
+
+## Troubleshooting
+
+**Q: Both plugins changed but for very different reasons — do I use the same bump type?**
+A: No. Evaluate each plugin independently. One might be a patch and the other a minor bump.
+
+**Q: I added a new skill AND fixed a bug in the same plugin. Which bump type?**
+A: Use minor (the higher of the two).
+
+**Q: How do I know if marketplace metadata.version should be bumped?**
+A: Ask: "Did I change marketplace.json itself beyond just updating plugin version entries?" If you edited owner, metadata.description, added new top-level fields, or changed MARKETPLACE.md — yes. If you only updated plugin version numbers — no.
+
+**Q: What if I only changed README.md inside a plugin directory?**
+A: Still bump the plugin version (patch). Documentation is part of the plugin release.
+
+**Q: Should this skill be used alongside pr-changeset?**
+A: These are independent. `pr-changeset` handles npm packages in `packages/*`. This skill handles Claude plugins in `claude-plugins/*`. If a PR changes both, use both skills.
+
+## Important Notes
+
+- Plugin versions are semver strings stored directly in JSON — there is no automated tooling managing them
+- The marketplace.json `plugins[].version` fields must always match the corresponding plugin.json `version` fields
+- marketplace.json `metadata.version` is independent and tracks the marketplace manifest itself
+- Both plugin.json files and marketplace.json must be committed together in the same commit as the plugin changes

.claude/skills/pr-changeset/SKILL.md

@@ -1,19 +1,12 @@
 ---
 name: pr-changeset
-description: Create changesets for package changes in pull requests. Use whenever you modify code in any package (packages/*). Required before committing changes to packages. Handles versioning with patch for bug fixes, minor for features, and major only when explicitly requested.
+description: Create changesets for package changes in pull requests. Invoke whenever any file under packages/* is modified — including bug fixes, new features, and even documentation or typo changes. Changesets are required before committing; without one, the release pipeline won't know what changed or how to version it. Also trigger when the user asks about versioning, what changeset to create, or whether a change needs a changeset.
 allowed-tools: Write, Read, Bash, Grep, Glob
 ---
 
 # PR Changeset Skill
 
-This skill helps you create proper changeset files when making changes to packages in the monorepo. **You MUST use this skill whenever you modify code in any package.**
-
-## When to Use
-
-- **ALWAYS** when modifying files in `packages/*`
-- Before committing changes to any package
-- When creating or updating a pull request that affects packages
-- Even for small changes (typo fixes, documentation updates in packages)
+This skill creates the changeset file that tells the release pipeline what changed and how to version it. Every change to a package needs one — even small fixes — because changesets are how versions get bumped and changelogs get generated automatically.
 
 ## Versioning Rules
 

CLAUDE.md

@@ -9,6 +9,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **README files:** Each package and example has its own README for specific usage instructions
 - **Claude Skills:** Specialized skills for common tasks are in `.claude/skills/`
   - `pr-changeset`: **REQUIRED** - Use when modifying any package code to create proper changeset files
+  - `plugin-version`: **REQUIRED** - Use when modifying any Claude plugin code to bump plugin and marketplace versions
 
 ## Project Overview
 
@@ -1311,6 +1312,20 @@ Then follow the prompts to select packages and version bumps.
 2. Commit changes including the changeset file.
    Version bumping and publishing is handled automatically by changesets during release in a GitHub Action.
 
+## Publishing Plugins
+
+Claude plugins in `claude-plugins/*` use direct semver versioning in JSON files. Whenever you modify plugin code, skills, commands, agents, or marketplace root files, you must bump the version using the `plugin-version` skill.
+
+**IMPORTANT:** When working with Claude Code, you MUST use the `plugin-version` skill to bump plugin versions. It handles both the plugin's own `plugin.json` and the matching entry in `.claude-plugin/marketplace.json`.
+
+The `plugin-version` skill:
+
+- Detects which plugin directories changed (`claude-plugins/opensaas-stack/`, `claude-plugins/opensaas-migration/`, `.claude-plugin/`)
+- Determines patch vs minor bump (patch for fixes, minor for new capabilities, major only when explicitly requested)
+- Directly edits version fields in JSON — no changeset files
+- Keeps `plugin.json` and `marketplace.json` plugin entries in sync
+- Only bumps `marketplace.metadata.version` when the marketplace structure itself changed (not just plugin version numbers)
+
 - Data passed in as props to a component that is marked with `"use client"` must be serialised and must only contain the minimum data required to make that component work
 - Avoid the use of the `any` type, and do not use type casting. All types must be strongly typed to ensure type satefy - the `unkown` and `any` types must never exposed as an exteral type and are only to be used internally (within a package) where absolutely necessary
 

claude-plugins/opensaas-migration/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "opensaas-migration",
   "description": "OpenSaaS Stack migration assistant with AI-guided configuration, schema analysis, and code generation support",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "author": {
     "name": "OpenSaaS Team",
     "url": "https://github.com/OpenSaasAU/stack"

claude-plugins/opensaas-migration/skills/migrate-document-fields/SKILL.md

@@ -102,7 +102,7 @@ Write a comment in the code for any document fields that had existing content so
 ```typescript
 // NOTE: This field was migrated from Keystone document format.
 // Existing content may not render correctly until re-saved in the Tiptap editor.
-// See specs/keystone-image-migration.md for data migration guidance.
+// See specs/keystone-document-migration.md for data migration guidance.
 content: richText()
 ```
 

claude-plugins/opensaas-migration/skills/opensaas-migration/SKILL.md

@@ -1,22 +1,12 @@
 ---
 name: opensaas-migration
-description: Expert knowledge for migrating projects to OpenSaaS Stack. Use when discussing migration strategies, access control patterns, or OpenSaaS Stack configuration best practices.
+description: Expert knowledge for migrating projects to OpenSaaS Stack. Invoke whenever the user mentions migrating from KeystoneJS, Prisma, or an existing Next.js project; asks about access control patterns or opensaas.config.ts; or is troubleshooting any aspect of an OpenSaaS Stack migration. Don't wait for the user to say "migration" — trigger whenever the conversation touches these areas.
 ---
 
 # OpenSaaS Stack Migration
 
 Expert guidance for migrating existing projects to OpenSaaS Stack.
 
-## When to Use This Skill
-
-Use this skill when:
-
-- Planning a migration from Prisma, KeystoneJS, or Next.js
-- Designing access control patterns
-- Configuring `opensaas.config.ts`
-- Troubleshooting migration issues
-- Explaining OpenSaaS Stack concepts
-
 ## Migration Process
 
 ### 1. Install Required Packages

claude-plugins/opensaas-stack/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "opensaas-stack",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Feature-driven development assistant for OpenSaaS Stack. Build complete applications by describing what you want to build instead of configuring infrastructure.",
   "author": {
     "name": "OpenSaaS",

claude-plugins/opensaas-stack/skills/opensaas-builder/SKILL.md

@@ -1,6 +1,9 @@
-# OpenSaaS App Builder Skill
+---
+name: opensaas-builder
+description: Build applications and features on the OpenSaaS Stack. Use this whenever a user describes building an app, adding functionality, implementing a feature, or asks "how do I implement X" in an OpenSaaS Stack project. Also trigger when the user describes business requirements, data models, or use cases — even if they don't say "OpenSaaS" explicitly.
+---
 
-**When to invoke**: User describes wanting to build an application or add functionality to their OpenSaaS Stack app
+# OpenSaaS App Builder Skill
 
 ## Pattern Recognition