Release Skill

Complete npm release workflow that handles version bumping, git operations, and GitHub releases in the correct order to trigger automatic npm publishing.

Trigger Words

Use when user says: "release", "publish", "ship it", "create release", "npm publish", "/release"

Critical: Correct Order of Operations

The workflow MUST follow this exact sequence to ensure npm publishing works:

1. Version Bump (all files)
2. Build & Test
3. Git Commit (version changes)
4. Git Tag (annotated)
5. Push Commits to main
6. Push Tag to origin
7. Create GitHub Release (triggers npm publish)
8. Verify npm publication

Why Order Matters

• GitHub Actions trigger: The deploy.yml workflow only runs npm publish when github.ref starts with refs/tags/v
• Tag must exist on remote: If you create a GitHub release before pushing the tag, it fails
• Commits must be pushed first: The tag must point to a commit that exists on the remote

Pre-flight Checks

Before starting, verify:

# 1. Clean working directory (or only version-related changes)
git status

# 2. On main branch
git branch --show-current

# 3. GitHub CLI authenticated
gh auth status

# 4. Current versions in sync
echo "package.json: $(node -p "require('./package.json').version")"
echo "CLI source:   $(grep "const VERSION" src/cli/index.ts | grep -oP "'[^']+'" | tr -d "'")"
echo "README:       $(grep -oP 'v[0-9]+\.[0-9]+\.[0-9]+' README.md | head -1)"
echo "docs/index:   $(grep -oP '"softwareVersion": "[^"]+"' docs/index.html | grep -oP '[0-9]+\.[0-9]+\.[0-9]+')"

Version Locations

ALL of these MUST be updated to the same version:

Complete Workflow

Step 1: Determine Version

Ask user for version type if not specified:

• patch (X.Y.Z+1): Bug fixes
• minor (X.Y+1.0): New features
• major (X+1.0.0): Breaking changes

Or accept explicit version like "2.1.0".

Step 2: Update All Version Locations

Update each file with the new version (see Version Locations table).

Step 3: Update package-lock.json

npm install --package-lock-only

Step 4: Build and Test

npm run build
npm test

Verify CLI version:

node dist/cli.js --version

Step 5: Commit Version Changes

git add package.json package-lock.json src/cli/index.ts README.md docs/index.html
git commit -m "chore: release vX.Y.Z"

Step 6: Create Annotated Tag

git tag -a vX.Y.Z -m "Release vX.Y.Z"

Step 7: Push Commits First

git push origin main

Step 8: Push Tag

git push origin vX.Y.Z

Step 9: Create GitHub Release

gh release create vX.Y.Z \
  --title "vX.Y.Z" \
  --generate-notes

This triggers the GitHub Actions workflow which:

1. Runs tests on all platforms
2. Builds production bundle
3. Publishes to npm using OIDC trusted publishing

Step 10: Verify Publication

Wait 2-3 minutes, then verify:

# Check GitHub Actions status
gh run list --limit 1

# Check npm registry (after CI completes)
npm view @henkisdabro/mcp-selector version

Semantic Versioning Guide

Rollback Procedure

If something goes wrong:

# Delete local tag
git tag -d vX.Y.Z

# Delete remote tag (if pushed)
git push origin --delete vX.Y.Z

# Delete GitHub release (if created)
gh release delete vX.Y.Z --yes

# Revert commit (if needed)
git revert HEAD
git push origin main

Important Notes

• Never run npm publish locally - it won't work with trusted publishing
• The npm publish happens automatically via GitHub Actions OIDC
• Always release from the main branch
• Use --generate-notes for auto-generated changelog from PR titles
• The workflow file MUST be named deploy.yml for OIDC to work

npm Trusted Publishing

This project uses npm Trusted Publishing (OIDC) which means:

• No npm tokens stored in GitHub secrets
• Publishing only works through GitHub Actions
• The workflow must match the configuration on npmjs.com
• Repository: henkisdabro/Claude-Code-MCP-Server-Selector
• Workflow: deploy.yml

Quick Reference: Tag-Only Release

If version is already bumped and committed, just need to tag and release:

VERSION="X.Y.Z"
git tag -a "v${VERSION}" -m "Release v${VERSION}"
git push origin main
git push origin "v${VERSION}"
gh release create "v${VERSION}" --title "v${VERSION}" --generate-notes