GitHub Release

Create a GitHub release for an npm package, triggering the npm-publish workflow.

Context Awareness

This skill can be invoked:

1. •From conversation context: Repo and version already known from prior discussion (most common)
2. •From working directory: If inside a specific repo directory
3. •Ambiguous: If in a parent workspace (e.g., @shellicar/) with no prior context

Priority Order

1. •Check conversation context first - If repo/version discussed earlier, use that
2. •Check working directory - If in a git repo with package.json, use that
3. •Ask user - If ambiguous (parent workspace, no context), ask which repo to release

Pre-conditions (Discovery)

1. Determine Repository

From context: Check if a repo was discussed in the conversation (e.g., "build-clean v1.2.1")

From working directory (if no context):

# Check if in a git repo
git rev-parse --git-dir 2>/dev/null

# Get repo name from git remote
git remote get-url origin | sed 's/.*github.com[:/]\(.*\)\.git/\1/' | cut -d'/' -f2

If in parent workspace (e.g., /home/stephen/repos/@shellicar):

Use AskUserQuestion to ask which repo to release, listing available repos.

2. Detect Convention

~/.claude/skills/git-pr/scripts/detect-convention.sh

Must be a GitHub repo (shellicar or shellicar-oss convention).

3. Get Version from package.json

# Monorepo (packages/*/package.json)
jq -r '.version' packages/*/package.json 2>/dev/null | head -1

# Single package (fallback)
jq -r '.version' package.json 2>/dev/null

4. Verify Pre-conditions

Before proceeding, verify:

• • On main branch
• • Working directory clean (no uncommitted changes)
• • CHANGELOG.md contains entry for this version
• • package.json version matches CHANGELOG version
• • Milestone exists for this version

# Check milestone exists
gh api repos/{owner}/{repo}/milestones --jq '.[] | select(.title == "{VERSION}")'

If any fail, inform user what's missing.

Main Steps

1. Check for Existing Release

# Note: @shellicar repos use VERSION without 'v' prefix
gh release view "${VERSION}" 2>/dev/null

If release exists, inform user and stop (or offer to view it).

2. Confirm with User

Use AskUserQuestion to confirm release creation:

• •"Create release" - Proceed with release
• •"Cancel" - Do not create release

3. Create Release with Auto-Generated Notes

# @shellicar convention: no 'v' prefix
gh release create "${VERSION}" \
  --title "${VERSION}" \
  --generate-notes

4. Review and Evaluate Release Notes

# Get the auto-generated release notes
gh release view "${VERSION}" --json body --jq '.body'

Evaluate the notes and provide a recommendation:

Consider:

• •Do the notes capture the key changes?
• •For security fixes: Is the CVE linked for searchability?
• •For breaking changes: Are they clearly highlighted?
• •Is important context missing?

Present the notes to the user with your assessment and recommendation:

**Auto-generated notes:**
[notes here]

**Assessment:** [Your evaluation - what's good, what's missing]
**Recommendation:** [Accept as-is / Suggest specific improvement]

Use AskUserQuestion for confirmation:

• •"Accept notes" - Continue to next step
• •"Edit notes" - Provide suggested improvement or custom notes

5. Monitor npm-publish Workflow

# Check workflow status
gh run list --workflow=npm-publish.yml --limit=1 --json status,conclusion,databaseId,displayTitle

Wait for the workflow to complete. Report success or failure.

If Workflow Fails

If the workflow fails due to a fixable issue (e.g., expired npm token, transient error):

1. •User fixes the issue manually (e.g., updates GitHub secret)
2. •Re-run the failed workflow:

gh run rerun <run-id>

1. •Continue monitoring until success

8. Confirm npm Availability

# Verify package is published
npm view @shellicar/{package-name} version

Confirm the new version is available on npm.

9. Close Milestone

After all checks pass, close the milestone:

# Get milestone number
MILESTONE_NUMBER=$(gh api repos/{owner}/{repo}/milestones --jq '.[] | select(.title == "${VERSION}") | .number')

# Close milestone
gh api repos/{owner}/{repo}/milestones/${MILESTONE_NUMBER} -X PATCH -f state=closed

Report milestone closed to user.

Integration with Other Skills

Typical flow:

maintenance-release → version-management → git-commit → git-pr → [PR merged] → github-release

When called after other skills, version context flows through the conversation - no need to re-discover.

CLI Reference

# Create release (no 'v' prefix for @shellicar repos)
gh release create "1.2.1" --title "1.2.1" --generate-notes

# Create with custom notes
gh release create "1.2.1" --title "1.2.1" --notes "Release notes here"

# View release
gh release view "1.2.1"

# List releases
gh release list

# Delete release (if needed)
gh release delete "1.2.1" --yes

Notes

• •Tag format: ${VERSION} (e.g., 1.2.1) - NO v prefix for @shellicar repos
• •Release title: Same as tag (version number only)
• •Release notes: Auto-generated by GitHub (--generate-notes)
• •The npm-publish workflow is triggered by release creation
• •Always confirm with user before creating release