# Release > Create a new versioned release with changelog, git tag, and GitHub Release Use when this capability is needed. - Skill: `tomevault-io/release-101` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/release-101` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/release-101/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/release-101 --- Follow these steps to create a new release: ## 1. Review unreleased changes Read `CHANGELOG.md` and show the user all items under `[Unreleased]`. Ask the user to confirm these are the changes they want to include in the release. If the `[Unreleased]` section is empty, stop and inform the user there is nothing to release. ## 2. Suggest version number Look at the previous version in `CHANGELOG.md` (e.g. `[2.0]`) and analyze the unreleased changes to recommend a version bump: - **Major** (e.g. `2.0` → `3.0`) — breaking changes, architectural rewrites, or incompatible API changes - **Minor** (e.g. `2.0` → `2.1`) — new features, enhancements, or non-breaking additions - **Patch** (e.g. `2.1` → `2.1.1`) — bug fixes only, no new features Explain the reasoning and let the user confirm or override the suggested version. ## 3. Update project documentation ### CHANGELOG.md - Rename `## [Unreleased]` to `## [] - ` (format: `YYYY-MM-DD`) - Add a new empty `## [Unreleased]` section above it - Preserve all existing content below ### docs/TODO.md Read `docs/TODO.md` and update it to reflect the release: - Mark completed tasks as `[x]` - Update phase status labels (e.g. `⬜ TODO` → `🚧 IN PROGRESS` → `✅ COMPLETE`) - Update the V2 Progress Tracking section - Update test counts or other metrics - Update the V2 Success Criteria checklist if applicable ### docs/SPEC.md Read `docs/SPEC.md` and update it if the release includes changes that affect the specification: - Update acceptance criteria checkboxes - Reflect any architecture, feature, or dependency changes - Update the document version and last updated date in the metadata section - Skip if the release is purely internal ### package.json versions Set the `version` field to the new version in: - `issuer/package.json` - `verification/package.json` ## 4. Regenerate documentation Run `npm run docs:generate` to rebuild the HTML documentation from the updated markdown files. ## 5. Run tests Run `npm test` from the repo root to ensure everything passes before releasing. If tests fail, stop and inform the user. ## 6. Build assets Run `npm run build` in both `issuer/` and `verification/` directories. Then create zip archives: - `zip -r issuer-v.zip issuer/dist` - `zip -r verification-v.zip verification/dist` ## 7. Stage, commit, and push Stage the modified files (`CHANGELOG.md`, `docs/TODO.md`, `docs/SPEC.md`, `issuer/package.json`, `verification/package.json`) by name. Ask the user which alias to use: - **`git cai`** — AI-attributed commit (sets author to "AI Generated (hhkaos)" and prefixes the message with "AI: ") - **`git ch`** — Regular commit with the user's default git identity Commit with message: `release: v` Then push with `git push`. ## 8. Create git tag Run `git tag v` and `git push --tags`. ## 9. Create GitHub Release Use `gh release create` to create the release on GitHub: ``` gh release create v \ --title "v" \ --notes "" \ issuer-v.zip \ verification-v.zip ``` The `--notes` should contain the full changelog entries for this version (the Added, Changed, Fixed, Removed sections) formatted in markdown. ## 10. Clean up Remove the temporary zip files: - `rm issuer-v.zip verification-v.zip` Confirm the release is live by showing the GitHub Release URL. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/hhkaos) — claim your Tome and manage your conversions.