Skip to main content
Agent skill

Ship Release

The Massing release discipline — how to ship a verified, CI-green version-numbered release direct to main. Invoke whenever finishing a shippable change (feature, fix, doc). Covers version bump (both files), CHANGELOG/roadmap notes, the ruff/lint CI gotchas, tag, push, and CI/CodeQL verification.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Ship Release when an AI agent needs a reusable SKILL.md workflow for this job: The Massing release discipline — how to ship a verified, CI-green version-numbered release direct to main. Invoke whenever finishing a shippable change (feature, fix, doc). Covers version bump (both files), CHANGELOG/roadmap notes, the ruff/lint CI gotchas, tag, push, and CI/CodeQL verification.

When not to use it

Skip Ship Release when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/ship-release
# Save SKILL.md to ~/.claude/skills/ship-release/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/ship-release/SKILL.md. For a shared project, commit the folder at .claude/skills/ship-release/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Ship Release skill for this task: Use Ship Release when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
59/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Ship a Massing release

`main` is unprotected and ships version-numbered releases via **direct commits** (no PR gate). Each shippable change is its own release. Follow this exactly.

## 1. Verify before you ship - **Backend (services/api, services/data):** run the affected `test_*.py` (see the `backend-tests` skill) and **ruff exactly as CI does**: ``` cd services/api && python -m ruff check src/ ../data/src/ ``` A file-level `ruff check <file>` from elsewhere does NOT pick up `services/api/ruff.toml` (isort/I001) and gives false "passed". Prefer `ruff check --fix` to auto-sort imports; put third-party imports in their own group after stdlib. - **Web (apps/web):** `export PATH="/c/Program Files/nodejs:$PATH"` then `npm run typecheck && npm run lint && npm run build` (Node 20; Node 18 breaks the build). Run `npx vitest run <path>` if unit tests cover the change. - **Frontend UI:** the dev-preview geometry loader stalls at "preparing geometry", so verify rail UI via the `verify-frontend` skill (force `buildToolsPanel` by dispatching `aec:persona`), and flag any flow you couldn't exercise end-to-end.

## 2. Bump the version — BOTH files ``` git fetch origin --quiet # avoid the version race (a background release may have taken the next number) sed -i 's/"version": "0.3.X"/"version": "0.3.Y"/' apps/web/package.json apps/web/src-tauri/tauri.conf.json ``` Confirm `origin/main` is where you branched (`git log origin/main --oneline -1`). If it advanced, rebase and bump to the next free number.

## 3. CHANGELOG + roadmap - Prepend a `## vX.Y.Z — <title>` entry to `CHANGELOG.md` (newest at top). - Add a `✅ … SHIPPED vX.Y.Z` note to the relevant `docs/roadmap.md` item. - Keep competitor names OUT of shipped docs; interop names (Revit, Bonsai, Procore) are fine.

## 4. Commit, push, tag Commit with the trailer `Co-Authored-By: Claude Opus 4.8 <[email protected]>`. Then, guarding against a race: ``` if [ "$(git rev-parse origin/main)" = "$(git rev-parse HEAD~1)" ]; then git push origin HEAD:main && git tag vX.Y.Z && git push origin vX.Y.Z else echo "RACE — rebase + rebump"; fi ```

## 5. Verify CI + CodeQL - A "CI" workflow run showing `success` does NOT mean the **API test gate** ruff step passed, or that CodeQL is clean. Check both. - After each push run the `security-monitoring` skill's CodeQL check (open **alerts**, not run status). - The API test gate is slow (~15–20 min); each commit is independently verified locally, so keep shipping. Watch the first release carrying a new test file to confirm it's green in CI.

See memory: `main-fast-release-cadence`, `ruff-ci-config-gotcha`, `backend-test-runner`, `codeql-monitoring`, `web-build-needs-node-20`.

Intended uses

  • Use Ship Release when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.