Skip to content

oliver-kriska/claude-elixir-phoenix / .claude/skills/release

release

Verified

CONTRIBUTOR 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.

FileKindSize
SKILL.mdskill md6.9 KB
references/templates.mdmarkdown5.1 KB
---
name: release
description: |
  CONTRIBUTOR 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.
argument-hint: "[patch|minor|major] | [X.Y.Z]"
effort: medium
---

# 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

1. **NEVER release on a red `make ci`** — the gate runs BEFORE committing. No green, no release.
2. **FOUR TAGS PER RELEASE** — `vX.Y.Z` plus `phx--vX.Y.Z`, `ecto--vX.Y.Z`, `lv--vX.Y.Z` from `claude plugin tag` (what dependency ranges resolve against). Tag only the release commit.
3. **THREE NUMBERS MUST MATCH** — `plugin.json` version == CHANGELOG heading == git tag (`vX.Y.Z`). Verify before pushing.
4. **CONFIRM BEFORE PUBLISHING** — pushing the tag and `gh release create` are outward-facing and hard to reverse. Stop and confirm with the user; show exactly what will be pushed/published first.
5. **USERS ONLY UPDATE ON A `plugin.json` BUMP** — never ship CHANGELOG/code changes without bumping the version, or installed users get nothing (cache).
6. **ALWAYS leave a fresh empty `## [Unreleased]`** — one `[Unreleased]` becomes one version heading; re-add an empty one on top.
7. **NEVER force-push** — `git push --force` is hook-blocked here. If history needs rewriting, the user runs it via `!`.
8. **EVERY release body links the docs site** — append the `https://phxagents.dev` footer. Releases are this project's one measured promotion lever (v3.0.1: 51 → 120 cloners in a day).
9. **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 annotated `phx--`/`ecto--`/`lv--` tags would win otherwise) — the last
  released tag is the bump base, NOT `plugin.json` (which may carry an
  unreleased phased bump). If `plugin.json` is 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:

1. `plugins/elixir-phoenix/.claude-plugin/plugin.json` — canonical
2. `plugins/ecto/.claude-plugin/plugin.json`
3. `plugins/lv/.claude-plugin/plugin.json`
4. `package.json` — Pi package metadata, tracks the plugin version since v3.0.0
5. `package-lock.json` — run `npm 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`:

1. Rename `## [Unreleased]` → `## [X.Y.Z] - YYYY-MM-DD` (today's date).
2. Insert a fresh empty section on top (see `${CLAUDE_SKILL_DIR}/references/templates.md`).
3. Optionally add a one-line summary under the new heading (past releases do).

## Step 3: README + intro (only if needed)

- Update `README.md` ONLY 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.md` cheat 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
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexUnverifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall