oliver-kriska/claude-elixir-phoenix / .claude/skills/release
release
VerifiedCONTRIBUTOR TOOL - Cut a plugin release: bump plugin.json version, finalize CHANGELOG, update README if needed, gate on make ci, commit, tag vX.Y.Z, and create the GitHub release. Use when shipping a new plugin version. NOT distributed.
Plugin Release
Cuts a versioned release of the Elixir/Phoenix plugin. Drives the full
checklist from CLAUDE.md (Release + Versioning) so every release is
consistent. Contributor tooling — not shipped in the plugin.
Iron Laws — Never Violate These
- NEVER release on a red
make ci— the gate runs BEFORE committing. No green, no release. - FOUR TAGS PER RELEASE —
vX.Y.Zplusphx--vX.Y.Z,ecto--vX.Y.Z,lv--vX.Y.Zfromclaude plugin tag(what dependency ranges resolve against). Tag only the release commit. - THREE NUMBERS MUST MATCH —
plugin.jsonversion == CHANGELOG heading == git tag (vX.Y.Z). Verify before pushing. - CONFIRM BEFORE PUBLISHING — pushing the tag and
gh release createare outward-facing and hard to reverse. Stop and confirm with the user; show exactly what will be pushed/published first. - USERS ONLY UPDATE ON A
plugin.jsonBUMP — never ship CHANGELOG/code changes without bumping the version, or installed users get nothing (cache). - ALWAYS leave a fresh empty
## [Unreleased]— one[Unreleased]becomes one version heading; re-add an empty one on top. - NEVER force-push —
git push --forceis hook-blocked here. If history needs rewriting, the user runs it via!. - EVERY release body links the docs site — append the
https://phxagents.devfooter. Releases are this project's one measured promotion lever (v3.0.1: 51 → 120 cloners in a day). - UPGRADE-BREAKING RELEASES LEAD WITH THE WARNING — if users must do anything beyond
/plugin update, the release body opens with a> [!WARNING]block carrying the exact commands (see #135).
Step 0: Preconditions
- On
main, working tree clean except intended release files. If feature work is uncommitted, commit it first. - Determine version. Run
git describe --tags --abbrev=0 --match 'v*'FIRST (the annotatedphx--/ecto--/lv--tags would win otherwise) — the last released tag is the bump base, NOTplugin.json(which may carry an unreleased phased bump). Ifplugin.jsonis already ahead of the tag, apply the consolidation check below before picking a number. - Read current
plugins/elixir-phoenix/.claude-plugin/plugin.json. Pick bump from## [Unreleased]contents:- MAJOR — breaking change (removed command, workflow redesign)
- MINOR — new skill / agent / command / hook
- PATCH — bug fix, doc/reference update, description tweak
- Consolidation check (per memory): if several phased branch bumps never released, collapse to ONE bump from the last released tag — don't stack intermediate versions.
Step 1: Bump the version — five files by hand, two generated
A partial bump does not just cost users the update; it fails
scripts/tests/test_codex.py, which asserts the Codex manifest matches canonical.
Set "version" to X.Y.Z in:
plugins/elixir-phoenix/.claude-plugin/plugin.json— canonicalplugins/ecto/.claude-plugin/plugin.jsonplugins/lv/.claude-plugin/plugin.jsonpackage.json— Pi package metadata, tracks the plugin version since v3.0.0package-lock.json— runnpm install --package-lock-only, never hand-edit (an unrelated dependency can share the old version string)
Then regenerate the two templated manifests and bless their digests:
make generated-skills-sync # updates targets/codex + targets/pi manifests
make generated-skills-snapshots # re-bless after reviewing the diff
Confirm every file agrees before moving on:
grep -rn '"version"' plugins/*/.claude-plugin/plugin.json package.json \
targets/codex/.codex-plugin/plugin.json targets/pi/package.json
(Often already bumped during the feature work — confirm it matches the target.)
Step 2: Finalize CHANGELOG
In CHANGELOG.md:
- Rename
## [Unreleased]→## [X.Y.Z] - YYYY-MM-DD(today's date). - Insert a fresh empty section on top (see
${CLAUDE_SKILL_DIR}/references/templates.md). - Optionally add a one-line summary under the new heading (past releases do).
Step 3: README + intro (only if needed)
- Update
README.mdONLY if counts/version callouts changed: skill count, agent count (grep -nE "[0-9]+ (skills|agents|specialist)" README.md), or a version banner. A pure doc/reference PATCH usually needs no README change — verify, don't assume. - Check
plugins/elixir-phoenix/skills/intro/references/tutorial-content.mdcheat sheet if commands/skills/agents were added, removed, or renamed.
Step 4: Gate on make ci
Run make ci (lint + test + validate + eval-all). Must be green. If lint trips on
untracked non-source dirs (e.g. social/, .rtk/), that is not a code failure — exclude
them, don't ship around real failures. See ${CLAUDE_SKILL_DIR}/references/templates.md.
Step 5: Commit
git add CHANGELOG.md plugins/elixir-phoenix/.claude-plugin/plugin.json # + README if touched
git commit # message below
Commit subject (matches history): Release vX.Y.Z — <short summary>
End the message with the Co-Authored-By trailer (see CLAUDE.md).
Step 6: Tag
After the release commit, tag each plugin. claude plugin tag validates the
plugin, confirms plugin.json matches the marketplace entry, and refuses a
dirty tree or an existing tag — so a failure here means the release commit is
wrong, not the tag. Run it with --dry-run first if unsure.
for p in elixir-phoenix ecto lv; do claude plugin tag plugins/$p || break; done
git tag vX.Y.Z
git tag --list 'v*' '*--v*' --points-at HEAD # expect 4 tags
Step 7: CONFIRM, then publish (outward-facing)
Show the user the pending commit, tag, and release notes. On confirmation:
git push origin main
git push origin vX.Y.Z phx--vX.Y.Z ecto--vX.Y.Z lv--vX.Y.Z
gh release create vX.Y.Z --title "vX.Y.Z — <summary>" --notes-file <changelog-section>
Use the new CHANGELOG section as release notes (extract it to a temp file or --notes),
then prepend any upgrade warning (Iron Law 9) and append the docs footer before
publishing — a release body is read at the moment someone decides whether to install:
---
Docs, install guides, and the runtime compatibility matrix: <https://phxagents.dev>
See ${CLAUDE_SKILL_DIR}/references/templates.md for the one-line printf that
appends it to the extracted notes.
Step 8: Verify
gh release view vX.Y.Z
git describe --tags --abbrev=0 --match 'v*' # should print vX.Y.Z
Confirm to the user: released, tag pushed, GitHub release live.
Reference
${CLAUDE_SKILL_DIR}/references/templates.md— CHANGELOG/release-notes templates, gate snippets, gotchas
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |