# Release

> Plugin release workflow skill for version bumping, git tagging, and GitHub release creation. Use when releasing plugin versions with automated CHANGELOG generation and version synchronization. Use when this capability is needed.

- Skill: `tomevault-io/release-56` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/release-56`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/release-56/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/release-56

---


# SKILL: Plugin Release Workflow

> **Purpose**: Execute plugin release workflow with version bumping, git tagging, and GitHub release
> **Target**: Plugin maintainers releasing new versions

---

## Quick Start

### When to Use This Skill
- Release new plugin version
- Bump version (patch/minor/major)
- Create git tag and GitHub release

### Quick Reference
```bash
# Standard release (patch version, CI handles GitHub release)
/999_release

# Minor version
/999_release minor

# Force local GitHub release
/999_release patch --create-gh

# Dry run (preview)
/999_release patch --dry-run
```

---

## What This Skill Covers

### In Scope
- Version synchronization (plugin.json, marketplace.json)
- Git tagging and pushing
- CHANGELOG auto-generation from commits
- GitHub release creation (optional)
- Pre-flight validation

### Out of Scope
- Plugin architecture → @CLAUDE.md
- Git workflow patterns → @.claude/skills/git-master/SKILL.md
- Migration guide → MIGRATION.md

---

## Core Concepts

### Single Source of Truth

**plugin.json** is the PRIMARY version source:
```json
{
  "version": "4.2.0"  // Always update this file
}
```

**Auto-synced file** (DO NOT edit manually):
- marketplace.json - Plugin entry version

### Release Workflow

**Pre-flight** → Version bump → CHANGELOG → Git tag → GitHub release

1. **Pre-flight Checks**: Validate jq, git, working tree, plugin manifests
2. **Version Bump**: Update version files atomically
3. **CHANGELOG**: Auto-generate from git commits (conventional commit format)
4. **Git Operations**: Commit, tag, push to remote
5. **GitHub Release**: Optional (local or CI/CD)

### CI/CD Integration

**Hybrid model**: Local tagging + CI/CD release creation
- Local: Bump version, create tag, push
- CI: Validates versions, creates GitHub release

**Benefits**:
- No API rate limits
- No authentication setup
- Runs on GitHub's infrastructure

---

## Execution Steps (Summary)

### Parse Arguments
- `VERSION_BUMP="${1:-patch}"` - Default: patch
- `--dry-run` - Preview changes
- `--skip-gh` - Skip local GitHub release (default)
- `--create-gh` - Force local GitHub release

### Phase 1: Pre-flight Checks
- Verify jq installed
- Check git working tree is clean
- Validate plugin manifest (single plugin standard)
- Check marketplace.json version sync
- Validate plugin.json fields (no unsupported fields like `agents`)

### Phase 2: Version Bump
- Read current version from plugin.json
- Parse version components (MAJOR.MINOR.PATCH)
- Calculate new version based on bump type
- Check for existing tag
- Update plugin.json (PRIMARY source)
- Update marketplace.json (sync all version fields)
- Verify version consistency

### Phase 3: Auto-Generate CHANGELOG
- Get previous tag
- Parse git commits since previous tag
- Categorize by conventional commit type (feat, fix, docs, etc.)
- Group into categories (Added, Changed, Fixed, Documentation)
- Insert at top of CHANGELOG.md

### Phase 4: Git Operations
- Preview changes (if --dry-run)
- Stage version files
- Commit with conventional commit format
- Create annotated tag
- Push commit and tag to remote

### Phase 5: GitHub Release (Optional)
- Check if gh CLI installed
- Extract CHANGELOG section for version
- Create GitHub release using gh CLI
- Skip by default (CI/CD handles it)

---

## Further Reading

**Internal**: @.claude/skills/release/REFERENCE.md - Full release workflow implementation details, troubleshooting, CI/CD integration, version tracking | @.claude/skills/git-master/SKILL.md - Git operations and commits | @.claude/commands/999_release.md - Release command

**External**: [Semantic Versioning](https://semver.org/) | [Conventional Commits](https://www.conventionalcommits.org/) | [Keep a Changelog](https://keepachangelog.com/)

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/changoo89) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->