Skip to main content
skill CX Codex

release-beta — Claude Code skill: what it does, how to install

release-beta handles beta pre-releases with commit analysis, bilingual release notes, and strict quality checks.

MIT 1 installs ★ 214 updated 2026-10-28

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Thank-you-Linus/Linus-Dashboard --skill release-beta -a claude-code
Open on GitHub

What release-beta does

The skill manages a structured six-phase workflow for beta pre-releases. It inspects package.json to detect the release scenario. When cutting the first beta after a stable version, it runs npm run analyze:commits to classify changes as major, minor, or patch, prompting for approval. If an incremental beta already exists, it bumps the counter automatically.

The process generates bilingual release notes in English and French, cleans up noise, and applies strict gates. It executes 17 quality checks via scripts/check-release-ready.sh and runs 15 smoke tests using npm run test:smoke. Any failure stops execution immediately. Release operations support --dry-run to stop before pushing, while runs are tracked in .opencode/logs/.

A strict requirement forbids the v prefix in git tags: tags must look like 1.4.1-beta.1. Using a v prefix will cause GitHub Actions workflows to fail.

What it helps with

  • determine semantic version bump types from commit history
  • generate clean bilingual release notes for pre-releases
  • execute seventeen pre-release repository health checks
  • run fifteen smoke tests before publishing tags
  • create and push git tags formatted without a v prefix

Example prompts for the agent

  • Prepare a new beta pre-release from the current stable branch
  • Run the beta release workflow with --dry-run
  • Check release readiness and publish the next incremental beta

How to install release-beta

1Skills CLI (Vercel)

npx skills add Thank-you-Linus/Linus-Dashboard --skill release-beta -a claude-code

2Manually: put the files in place

~/.claude/skills/release-beta/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/release-beta/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about release-beta

How to install release-beta in Claude Code?

Run npx skills add Thank-you-Linus/Linus-Dashboard --skill release-beta -a claude-code. The definition will be placed in ~/.claude/skills/release-beta/SKILL.md.

What does release-beta do?

It orchestrates pre-releases by checking version state, evaluating commits, producing release notes, and running automated tests before tagging.

Why is the v prefix banned in git tags?

GitHub Actions workflows in this setup expect raw versions like 1.4.1-beta.1. Adding a v prefix causes automated jobs to fail.

Source text

SKILL.md · MIT
---
name: release-beta
description: Create a beta pre-release for community testing with intelligent version detection. Use when creating beta releases, publishing pre-releases, or preparing versions for community testing.
---

# Create Beta Pre-Release

Create a **BETA pre-release** for community testing.

Current version: Check `package.json` for current version.

## ⚠️ CRITICAL TAG FORMAT RULE

**NEVER use 'v' prefix in git tags!**

- ✅ CORRECT: `1.4.1-beta.1`
- ❌ WRONG: `v1.4.1-beta.1`

The GitHub workflows expect tags WITHOUT 'v' prefix. Using 'v' will cause workflow failures.
All scripts (`bump-version.sh`, `create-prerelease.sh`) already create tags without 'v'.
**Never create tags manually** - always use the scripts.

## Intelligent Workflow

The workflow adapts automatically based on the current version:

**First beta after stable release** → AI analyzes commits and suggests version type (patch/minor/major)
**Incremental beta** (beta.2 → beta.3) → Automatically increments without user validation

---

## Phase 1: Version Detection & Analysis

**Automatically detect release type:**

1. **Detect release type:**
   - Current version: `1.4.0` → **First beta** (requires AI analysis)
   - Current version: `1.4.0-beta.2` → **Incremental beta** (auto-increment to beta.3)

2. **For first beta after stable:**
   - Run commit analysis: `npm run analyze:commits`
   - Analyze commit types (feat, fix, BREAKING CHANGE)
   - Count semantic changes
   - Determine version bump type (patch/minor/major)

3. **For incremental beta:**
   - Skip analysis (already determined)
   - Auto-increment beta counter

---

## Phase 2: Version Type Decision (First Beta Only)

### AI Semantic Analysis Rules:

**MAJOR (X.0.0):**
- Commits contain `BREAKING CHANGE:` in footer
- Commits use `!` after type (e.g., `feat!:`, `fix!:`)
- API incompatible changes detected
- Database schema changes
- Major architecture refactoring

**MINOR (X.Y.0):**
- New features detected (`feat:` commits)
- Backward-compatible additions
- New components, views, cards
- Significant enhancements

**PATCH (X.Y.Z):**
- Only bug fixes (`fix:` commits)
- Documentation updates (`docs:`)
- Small improvements/refactoring
- Translation updates
- Dependency updates

**AMBIGUOUS:**
- Mixed signals (e.g., 5 feat + 1 BREAKING)
- Unclear impact
- → Ask user to decide manually

### Present Validation Prompt:

Present detailed analysis with:
- Current version
- Proposed version
- Commit breakdown (feat, fix, breaking, etc.)
- AI reasoning with confidence level
- Key commits (most impactful)
- User decision options:
  - [1] APPROVE - Proceed with AI suggestion
  - [2] DOWNGRADE TO PATCH - Override AI
  - [3] UPGRADE TO MAJOR - Override AI
  - [4] VIEW COMMITS - Show full commit list
  - [5] CANCEL - Abort safely

---

## Phase 3: Release Notes Generation & Editing

**Automatically:**

1. **Generate release notes** (`bash scripts/generate-release-notes.sh`)
2. **AI-powered editing:**
   - Remove noise (version bumps, merges, CI commits, deps updates)
   - Enhance features/fixes (bold title + detailed description)
   - Translate to French (same detail level)
   - Fill beta testing instructions
   - Remove TODO markers
3. **Format for GitHub** (`bash scripts/format-release-notes.sh`)

---

## Phase 4: Quality Validation (BLOCKING)

**All must pass:**

**A. Release notes validation** (`scripts/validate-release-notes.sh`)
- Required sections EN/FR
- No TODO
- Beta testing filled
- Bold features

**B. Code quality (17 checks)** (`scripts/check-release-ready.sh`)
1. Git clean 2. Branch main 3. Up-to-date 4. Deps installed 5. Lint 6. Type-check 7. Build 8. Version consistency 9. No FIXME 10. CHANGELOG 11. manifest.json 12. hacs.json 13. No secrets 14. Python syntax 15. README 16. LICENSE 17. Smoke tests ready

**C. Smoke tests (15 tests)** (`npm run test:smoke`)

---

## Phase 5: Final Approval & Publication

Present final approval with:
- Version and bump type
- Changes summary (features, bug fixes)
- Beta testing checklist
- Validation results
- What happens if approved

User options:
- [1] APPROVE - Publish beta release
- [2] REQUEST CHANGES - Modify release notes
- [3] VIEW FULL NOTES - See complete file
- [4] CANCEL - Abort

---

## Phase 6: Publication (Only after approval)

**For first beta with explicit version type:**

1. **Bump version** (`bash scripts/bump-version.sh beta <patch|minor|major>`)
   - Example: `bash scripts/bump-version.sh beta minor` → 1.5.0-beta.1
2. **Update release notes** with final version
3. **Commit + tag** (`git commit` + `git tag`)
4. **Push** (`git push && git push --tags`)
5. **Report success** with monitoring links

**For incremental beta:**

1. **Bump version** (`bash scripts/bump-version.sh beta`)
   - Auto-increment: 1.5.0-beta.2 → 1.5.0-beta.3
2. **Update release notes** with final version
3. **Commit + tag** (`git commit` + `git tag`)
4. **Push** (`git push && git push --tags`)
5. **Report success** with monitoring links

**GitHub Actions automatically:**
- Builds project
- Runs smoke tests
- Creates ZIP
- Creates pre-release
- Sends Discord notification to @Beta Tester
- Cleans up RELEASE_NOTES.md

---

## Quality Standards

**Release notes:** EN+FR equal quality, no TODO, detailed explanations, specific beta testing, user-focused, clean

**Code:** 17 checks passed, 15 smoke tests passed, lint+type-check passed, build succeeded

**Version decision:** AI analyzes commits semantically, presents detailed justification, user validates when needed

---

## Options

### Dry Run
```
--dry-run
```
Runs everything, creates commit+tag locally, **STOPS before push**. Nothing published.
To undo: `git reset HEAD~1 && git tag -d X.Y.Z-beta.N`

### Skip Approval (Final approval only)
```
--skip-approval
```
Shows summary but **auto-approves final publication**. Still requires version decision validation if first beta. ⚠️ Use with caution.

---

## Logs

Every release logged to: `.opencode/logs/release-beta-{timestamp}.log`

Contains: timestamps, commit analysis, AI reasoning, user decisions, git hashes, URLs, duration

---

## Common Errors

**Validation fails** → Fix issues, re-run command
**Smoke tests fail** → Check `npm run test:smoke`, fix, re-run
**Build fails** → Run `npm run build`, fix errors, re-run
**Push fails** → `git pull --rebase`, re-run
**Tag exists** → `git tag -d X.Y.Z-beta.N` or re-run (auto-increments)
**Ambiguous commits** → AI asks you to decide manually between patch/minor/major

---

## Related Commands

**After beta testing:**
- ✅ Beta successful → Use release-stable skill (finalizes beta → stable)
- 🐛 Issues found → Fix, then use release-beta skill again (increments beta.N automatically)
- 🚨 Critical issue → Use release-rollback skill

---

## Version Detection Logic Summary

| Current Version | Detection | AI Analysis | User Validation | Result |
|----------------|-----------|-------------|-----------------|--------|
| `1.4.0` (stable) | First beta | ✅ Yes | ✅ Required | `1.5.0-beta.1` (if MINOR) |
| `1.4.0-beta.2` | Incremental | ❌ No | ❌ Not required | `1.4.0-beta.3` |
| `1.4.0-beta.5` | Incremental | ❌ No | ❌ Not required | `1.4.0-beta.6` |

---

## Important

- **First beta:** AI analyzes commits, presents detailed reasoning, requires your validation
- **Incremental beta:** Automatic increment, no analysis, faster workflow
- All validations are blocking (must pass)
- Idempotent (safe to re-run)
- Logs everything
- Time: 5-10 min (first beta) or 3-5 min (incremental)

**Scripts Used:**
- `scripts/analyze-commits.sh` - Commit analysis (first beta only)
- `scripts/bump-version.sh beta [patch|minor|major]` - Version bumping
- `scripts/generate-release-notes.sh` - Release notes generation
- `scripts/format-release-notes.sh` - Formatting
- `scripts/validate-release-notes.sh` - Validation
- `scripts/check-release-ready.sh` - Code quality checks

© Thank-you-Linus · MIT · Thank-you-Linus/Linus-Dashboard

Similar skills

All skills for Git and GitHub →

Project sponsors

Companies that keep this analytics open