Claude-superpowers releasing-plugin-versions

Use when releasing a new plugin version, bumping versions, creating git tags, or publishing GitHub releases for this marketplace

install

source · Clone the upstream repo

git clone https://github.com/ivan-magda/claude-superpowers

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/ivan-magda/claude-superpowers "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/releasing-plugin-versions" ~/.claude/skills/ivan-magda-claude-superpowers-releasing-plugin-versions && rm -rf "$T"

manifest: .claude/skills/releasing-plugin-versions/SKILL.md

source content

Releasing Plugin Versions

Critical Distinction

metadata.version

≠ plugin version. These are DIFFERENT things:

Field	What It Tracks	When to Update
`plugins[].version`	Individual plugin version	Every plugin release
`metadata.version`	Marketplace catalog structure	Adding/removing plugins ONLY

Common mistake: Thinking metadata.version should "stay in sync" with plugin versions. It should NOT.

Plugin Version Locations (Update ALL 4)

When releasing a plugin (e.g., swift 1.2.0 → 1.3.0):

plugins/swift/.claude-plugin/plugin.json

→

"version": "1.3.0"

.claude-plugin/marketplace.json

→

plugins[].version: "1.3.0"

```
plugins/swift/README.md
```
→ Version section:
```
1.3.0
```
```
README.md
```
(root) → Available Plugins table:
```
1.3.0
```

Release Commands

# 1. Stage changes
git add -A

# 2. Commit
git commit -m "Release swift v1.3.0

- Description of changes"

# 3. Tag (format: v1.3.0, NOT swift-v1.3.0)
git tag v1.3.0

# 4. Push
git push && git push origin v1.3.0

# 5. GitHub release
gh release create v1.3.0 --title "v1.3.0" --notes "## Changes

- Change 1
- Change 2

**Full Changelog**: https://github.com/OWNER/REPO/compare/v1.2.0...v1.3.0"

Tag Format

Use

v1.3.0

, NOT

swift-v1.3.0

. Check existing tags:

git tag --sort=-v:refname | head -5

When NOT to Update metadata.version

Releasing a new plugin version ❌
Fixing plugin bugs ❌
Adding features to existing plugins ❌
Updating plugin documentation ❌

When TO Update metadata.version

Adding a NEW plugin to the catalog ✓
Removing a plugin from the catalog ✓
Changing marketplace owner/name ✓