Skip to main content
command CX Codex

publish — Claude Code command for extension releases

The publish command guides a VS Code extension release, from QA checks and changelog updates to versioning and pushing a tagged commit. A separate file is available for Codex.

MIT ★ 110 updated 2026-11-10

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/publish.md
Open on GitHub

What publish does

Before a release, publish checks the Git worktree and current version, then requires a passing QA report for the current HEAD. It stops when there are uncommitted changes. Next, it asks for a version, reviews commits since the previous tag, and prepares a changelog section. Its checklist also covers the README, screenshots, and the website build.

The command updates CHANGELOG.md and package.json, runs npm version, commits the listed files, creates an annotated tag, and pushes both to origin. Its scope is the VS Code extension. Changes under apps/speckit-extension/ use /publish-speckit-ext instead. If the QA gate fails, the workflow only proceeds after the user explicitly overrides it.

What it helps with

  • check release readiness before committing
  • draft changelog entries from commits since the prior tag
  • update the extension version and documentation
  • validate release screenshots and build the website
  • push the release commit and tag to origin

Example prompts for the agent

  • Prepare a release for the VS Code extension and run the release checks first.
  • Draft the changelog from commits since the previous tag, then run the release checklist.
  • Update the extension to the version I provide and push its commit and tag to origin.

How to install publish

Manually: put the files in place

.claude/commands/publish.md

Call it with /publish. For all projects use ~/.claude/commands/

Questions about publish

How do I install publish in Claude Code?

Copy the command file to .claude/commands/publish.md, then invoke it with /publish.

What does publish do?

It guides a VS Code extension release: checks QA and Git status, updates the changelog and version, runs release checks, then commits, tags, and pushes the release.

Can publish release the spec-kit extension?

No. Use /publish-speckit-ext for apps/speckit-extension/; publish is for the VS Code extension.

Source text

publish.md · MIT
---
allowed-tools: Bash(git *), Bash(npm version:*), Bash(node:*), Edit, Read, Write
description: Publish a new version of the extension
---

## Context

- Current git status: !`git status --porcelain`
- Current version: !`node -p "require('./package.json').version"`
- Current branch: !`git branch --show-current`
- Recent tags: !`git tag --sort=-version:refname | head -5`

## Your task

> **Scope: the VS Code extension only.** For the **spec-kit extension** (`apps/speckit-extension/`) use `/publish-speckit-ext` — it has its own README/CHANGELOG/`extension.yml` version and a `speckit-ext-v*` tag (a `v*` tag here would wrongly publish to the Marketplace). The Claude Code mod and the Copilot canvas ship with `/publish-mod` and `/publish-canvas`; `/publish-all` runs every flow in order.

Help the user publish a new version of the extension by:

0. QA gate. Apply the Release gate in `.claude/commands/release-qa.md` before anything else: a `QA Report*.md` in the vault for the current HEAD with `verdict: ship` and no open FAIL. If it does not pass, stop and tell the user to run `/release-qa`; continue only on their explicit override. Skip it when `/publish-all` already ran it in its preflight.
1. First check if there are uncommitted changes. If yes, abort with a warning.
2. Ask the user for the new version number (show current version).
3. Get the previous version tag and analyze commits since then to generate a changelog.
4. Update CHANGELOG.md by adding a new section at the top (after the header) with:
   - `## [X.X.X] - YYYY-MM-DD` format, then one plain lead sentence for the release
   - The format in `.claude/commands/changelog-entry.md` ("Changelog voice"): the big features under `### Highlights`, one `#### <Feature title>` block each with its `<!-- area: …; pr: …; media: … -->` comment, and every other entry as one bullet under Added / Fixed / Changed / Security ending with its full PR link and an `<!-- area: … -->` tag
   - `CHANGELOG.md` keeps `[Unreleased]` and the two latest releases. Cut every older release section and paste it at the top of `apps/website/src/data/changelog-archive.md`, above the newest one there, unchanged. A test fails when the changelog holds a third release.
5. Run the release checklist before anything is committed, and stop on a failure:
   - `npm run clips:check` must report 0 broken. A broken count is a 404 on the published Marketplace listing.
   - The README install and first-run steps still match what ships, and the README "VS Code" badge matches `engines.vscode` in `package.json`.
   - Re-render any screenshot whose UI changed in this release. Overwrite in place; never rename or delete a screenshot file.
   - Give each highlight its screenshots on the site's changelog. Name them in the highlight's comment (`media: builder-move-hook, builder-side-panel`) and add one entry per shot under the release's `vscode@<version>` key in `content/media/changelog.json`: `file` (a generated still under `docs/screenshots/generated/`, or a real-app screenshot copied to `apps/website/public/changelog/`), `alt`, a one-line `caption`, and a `highlight` box `{x, y, w, h}` in the image's own pixels when there is a clear changed area. Several shots make a carousel. Do it after the version heading exists.
   - Make each shot with `node tooling/scripts/release-shot.mjs <storyId> <outBase> "<label>" <selector>` while Storybook runs: a 16:9 frame cropped to the change, readable on a phone, with a sketchy marker label on a yellow highlight and a yellow outline drawn in. Ship the `.marked.png` and leave `highlight` out of its entry, so the site does not draw a second box.
   - The site builds: `cd apps/website && npm run build && npx astro check`. The build fails on a media id with no entry, a missing alt or file, a shot no highlight names, and a key that matches no release.
   - If the release touches `apps/speckit-extension/`, say so: the spec-kit extension ships separately with `/publish-speckit-ext`, and changes there (Auto folding, the writer) reach users only through it.
6. Update documentation files with the new version:
   - Update version references in README.md if it has any
7. Update package.json version using `npm version X.X.X --no-git-tag-version`.
8. Commit CHANGELOG.md, README.md, `content/media/changelog.json`, package.json and package-lock.json with message "chore: bump version to X.X.X".
9. Create an annotated tag `vX.X.X` with message "Release vX.X.X - See CHANGELOG.md for details".
10. Push both the commit and tag to origin.
11. Inform the user that GitHub Actions will handle the rest.

Make sure to handle errors gracefully and provide clear feedback at each step.

© alfredoperez · MIT · alfredoperez/speckit-companion

Similar slash commands

All slash commands for DevOps and infrastructure →

From the same set83

The whole set →
speckit.git.commit speckit.git.commit is a Claude Code command that stages and commits changes after Spec Kit commands, according to project configuration. CX Codex +1 ★ 110repo stars speckit-git-commit The speckit-git-commit skill stages and commits project changes around Spec Kit commands. Use it when Git history should be updated from the project’s Spec Kit settings. CX Codex +1 ★ 110repo stars bench-capture bench-capture — a command for Claude Code and Codex that captures benchmark scores after a size runs through three cells, appends them to history, regenerates the report, and resets the cells for the next round. CX Codex +1 ★ 110repo stars speckit.companion.living-validate speckit.companion.living-validate is a command for Claude Code that checks living specs and feature deltas without editing files. It flags missing scenarios, unlinked headings, and syntax issues. CX Codex +1 ★ 110repo stars release-loop release-loop is a command for Claude Code and Codex that moves a batch of changes through fixes, QA, and release. It prepares a report and waits for approval before publishing. CX Codex +1 ★ 110repo stars bench-wave bench-wave runs an end-to-end benchmark round for a pipeline-diet wave across two Companion cells and logs the metrics into a markdown plan. Useful for measuring speed, token counts, and driver feedback. CX Codex +1 ★ 110repo stars speckit.git.feature The speckit.git.feature command creates and checks out a Git feature branch from a specification. Configure sequential or timestamp numbering and shape branch names with a template. CX Codex +1 ★ 110repo stars speckit-git-feature speckit-git-feature is a Claude Code skill that creates a Git branch from a task description within a Spec Kit project and reads its configuration. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open