skills-release

name	skills-release
description	> Use when this capability is needed.

Skills Collection Release Workflow

Purpose

Automate the release process for this skills repository:

• Pre-flight validation and safety checks
• Conventional commit analysis with version bump recommendation
• Version update in both config JSON files
• Git commit, tag, and push with user approval gates

When to Use This Skill

Use this skill when the user:

• Asks to "release", "tag", or "version" this skills collection
• Wants to bump the skills plugin version
• Needs to create a release tag for the repo

Do not use for npm packages — use /npm-release instead.

Bundled Scripts

This skill includes three helper scripts in the scripts/ directory:

1. release-prepare.sh — Validates git status, branch, config files, and version consistency
2. release-analyze.sh — Analyzes commits since last tag, counts by type, recommends bump
3. release-execute.sh — Bumps version, commits, tags, and pushes to remote

Run scripts from the skill directory:

bash scripts/release-prepare.sh
bash scripts/release-analyze.sh
bash scripts/release-execute.sh 1.1.0

Release Workflow

Follow these steps in order. Stop immediately if any step fails.

Step 1: Pre-flight Checks

Run the preparation script to validate everything:

bash scripts/release-prepare.sh

This checks:

• Current branch is master or main
• Working tree is clean (no uncommitted changes)
• .claude-plugin/plugin.json and .claude-plugin/marketplace.json exist
• jq is available
• Versions in both files match

If checks fail, report the problem and suggest a fix. Do not proceed.

Step 2: Analyze Commits

Run the analysis script to understand what changed:

bash scripts/release-analyze.sh

This will:

• Find the last release tag (or handle first release)
• List all commits since that tag
• Count commits by conventional type using anchored regex
• Detect breaking changes (type!: suffix or BREAKING CHANGE in body)
• Show file change statistics
• Print a version bump recommendation

Version bump criteria:

Bump	When
Major	Breaking changes — type!: prefix or BREAKING CHANGE body
Minor	New features — any feat: commits
Patch	Everything else — fix:, docs:, refactor:, chore:, etc.

Step 3: Confirm Version with User

Present the analysis summary and ask the user to choose a version bump.

Use the AskUserQuestion tool with these options:

AskUserQuestion:
  question: "Recommended: {{RECOMMENDATION}}. Which version bump for v{{CURRENT}} → v{{NEXT}}?"
  header: "Version"
  options:
    - label: "Major (v{{MAJOR}})"
      description: "Breaking changes — skill removals, renames, config restructuring"
    - label: "Minor (v{{MINOR}})"
      description: "New features — new skills, significant enhancements"
    - label: "Patch (v{{PATCH}})"
      description: "Fixes, docs, refactoring, chore, CI, tests"
    - label: "Cancel"
      description: "Abort the release"

Replace {{CURRENT}} with current version, and compute {{MAJOR}}, {{MINOR}}, {{PATCH}} by incrementing the appropriate segment (reset lower segments to 0).

If user selects Cancel, stop the workflow.

Step 4: Bump Version

Update both config files using jq. The execution script handles this:

bash scripts/release-execute.sh {{VERSION}}

Important: In step 4, only run the version bump portion. The execution script also commits, tags, and pushes — but we need a user approval gate before pushing. So instead of running the full script, perform the bump manually:

VERSION="{{VERSION}}"
PLUGIN_JSON=".claude-plugin/plugin.json"
MARKETPLACE_JSON=".claude-plugin/marketplace.json"

# Update plugin.json
jq --arg v "$VERSION" '.version = $v' "$PLUGIN_JSON" > "$PLUGIN_JSON.tmp" && mv "$PLUGIN_JSON.tmp" "$PLUGIN_JSON"

# Update marketplace.json
jq --arg v "$VERSION" '.plugins[0].version = $v' "$MARKETPLACE_JSON" > "$MARKETPLACE_JSON.tmp" && mv "$MARKETPLACE_JSON.tmp" "$MARKETPLACE_JSON"

Verify both files were updated correctly by reading them back.

Step 5: Commit Version Bump

Stage and commit the version bump:

git add .claude-plugin/plugin.json .claude-plugin/marketplace.json
git commit -m "Release v{{VERSION}}"

Step 6: Create Git Tag

Tag the release commit:

git tag v{{VERSION}}

Step 7: User Approval Before Push

CRITICAL: Always pause here for user approval.

Present a summary and ask for confirmation.

Use the AskUserQuestion tool:

AskUserQuestion:
  question: "Ready to push v{{VERSION}} to remote?"
  header: "Push"
  options:
    - label: "Yes"
      description: "Push commits and tag to remote"
    - label: "No"
      description: "Keep local commit and tag, do not push"

If user selects No, inform them:

• The commit and tag remain local
• To undo: git reset --hard HEAD~1 && git tag -d v{{VERSION}}

If user selects Other, follow their instructions.

Step 8: Push Release

Only after user approves:

git push && git push --tags

After pushing, get the remote URL and print:

Release v{{VERSION}} pushed successfully.
GitHub Releases: https://github.com/enonic/ai-agents-skills/releases

Error Handling

If any step fails:

1. Stop the workflow immediately
2. Report the error clearly
3. Suggest corrective action
4. Do not proceed to next steps

Common Issues

Uncommitted changes:

• Suggest: git stash then retry, or commit changes first

Wrong branch:

• Suggest: git checkout master then retry

Version mismatch between files:

• Fix manually or bump both to the same version before releasing

No tags found:

• First release: The analyze script handles this and recommends MINOR

Tag already exists:

• The execute script will refuse to create a duplicate tag
• Either delete the old tag or choose a different version

Keywords

release, version, bump, tag, skills, publish, deploy, ship, new version, create release

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.