Plugin Versioning Guide Skill

Plugin Versioning Guide

Agent Instructions

After completing your release steps (CHANGELOG, plugin.json, PR), always inform the user of their required next steps:

Merge the release PR

Create and push the version tag:

git checkout main && git pull
git tag vX.Y.Z
git push origin vX.Y.Z

Review/merge the marketplace PR (created automatically by the release workflow)

Do not assume the user knows the tag triggers the release workflow.

Semantic Versioning for Plugins

| Change Type | Version Bump | Example | |-------------|--------------|---------| | Breaking: hook behavior, removed features | MAJOR | 1.0.0 → 2.0.0 | | New: skill, command, agent, feature | MINOR | 1.0.0 → 1.1.0 | | Fix: bug fix, typo, docs | PATCH | 1.0.0 → 1.0.1 |

Release Checklist

Update CHANGELOG.md
- Move items from [Unreleased] to new version section
- Add release date
Update plugin.json version
```
{
  "version": "1.1.0"
}
```

Create release branch and PR

git checkout -b chore/release-v1.1.0
git add CHANGELOG.md .claude-plugin/plugin.json
git commit -m "chore: release v1.1.0"
git push -u origin chore/release-v1.1.0
gh pr create --title "chore: release v1.1.0" --body "Release v1.1.0"

Human merges PR, then tag

# After PR is merged by human:
git checkout main && git pull
git tag v1.1.0
git push origin v1.1.0

Automated steps (GitHub Action handles these)
- Creates GitHub Release with auto-generated notes
- Syncs plugin essentials to marketplace repo (plugins/python-dev-framework/)
- Updates version in marketplace.json
- Opens PR on marketplace repo
- Human reviews and merges marketplace PR

CHANGELOG Format

Follow Keep a Changelog:

## [Unreleased]

## [1.1.0] - 2025-01-15

### Added
- New plugin-versioning skill

### Changed
- Updated hook timeout from 10s to 15s

### Fixed
- Fixed edge case in branch name validation

Version Locations

| File | Field | |------|-------| | .claude-plugin/plugin.json | "version": "X.Y.Z" | | CHANGELOG.md | ## [X.Y.Z] - YYYY-MM-DD | | Git tag | vX.Y.Z |

Pre-release Versions

For beta or release candidate versions:

git tag v1.1.0-beta.1
git tag v1.1.0-rc.1

Pre-release tags follow semver format and can be used for testing before stable release.

Marketplace Distribution

On release, the GitHub Action syncs plugin files to the marketplace repo:

| Source | Destination | |--------|-------------| | .claude-plugin/ | plugins/python-dev-framework/.claude-plugin/ | | hooks/ | plugins/python-dev-framework/hooks/ | | skills/ | plugins/python-dev-framework/skills/ | | CLAUDE.md | plugins/python-dev-framework/CLAUDE.md | | .lsp.json | plugins/python-dev-framework/.lsp.json |

Note: The plugins/ directory in the marketplace repo is auto-generated. Do not edit directly.

Users install from the marketplace (bundled copy), not from this repo:

claude plugin install python-dev-framework@WorldCentralKitchen

Agent Skills: Plugin Versioning Guide

Install this agent skill to your local

Skill Files