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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.9 KB |
| references/templates.md | markdown | 5.1 KB |
references/templates.md
View on GitHub# Release Templates & Gotchas
## CHANGELOG: before → after
**Before** (work accumulates here):
```markdown
## [Unreleased]
### Added
- Feature X ...
### Fixed
- Bug Y ...
```
**After** (finalize for release `X.Y.Z` on date `YYYY-MM-DD`):
```markdown
## [Unreleased]
### Added
### Changed
### Fixed
## [X.Y.Z] - YYYY-MM-DD
<optional one-line summary of the release>
### Added
- Feature X ...
### Fixed
- Bug Y ...
```
Keep the empty `## [Unreleased]` scaffold on top so the next cycle has a home.
## Release notes for `gh`
Use the new version's CHANGELOG section verbatim. Extract it to a temp file:
```bash
# pull the section between "## [X.Y.Z]" and the next "## ["
awk '/^## \[X\.Y\.Z\]/{f=1} f&&/^## \[/&&!/X\.Y\.Z/{exit} f' CHANGELOG.md > /tmp/relnotes.md
# always append the docs footer — the release body is read at install-decision time
printf '\n---\n\nDocs, install guides, and the runtime compatibility matrix: <https://phxagents.dev>\n' \
>> /tmp/relnotes.md
gh release create vX.Y.Z --title "vX.Y.Z — <summary>" --notes-file /tmp/relnotes.md
```
## Upgrade warning block (Iron Law 9)
When the release requires anything beyond `/plugin update` — a new dependency,
a renamed manifest, a manual migration — **prepend** this block so it is the
first thing on the release page, above the changelog body:
```bash
cat > /tmp/relnotes.md <<'EOF'
> [!WARNING]
> **Upgrading from vN.x requires these commands in this order.** <one line on
> what breaks otherwise, in user-visible terms.>
>
> ```bash
> <exact commands>
> ```
EOF
awk '/^## \[X\.Y\.Z\]/{f=1} f&&/^## \[/&&!/X\.Y\.Z/{exit} f' CHANGELOG.md >> /tmp/relnotes.md
```
State the blast radius in what the user loses, not in mechanism. "The plugin
fails to load — all 36 `/phx:*` commands disappear" lands; "enters a
missing-dependency state" does not. v3.0.0 used the second phrasing, buried in
a `### Changed` bullet, and users still upgraded into a broken install
(issue #135).
Title format matches history: `vX.Y.Z — <short summary>` (em dash).
**The docs footer is not optional.** A release body is read at the exact moment
someone is deciding whether to install, and releases are the one promotion lever
in this project with a measured effect: v3.0.1 drove unique cloners 51 → 120 in
one day (2.4x), decaying to baseline over ~4 days. The repo is also the
higher-traffic discovery surface — Google sends ~4x more repo visitors than
phxagents.dev does — so every release body should point back to the docs site.
## Commit message shape (matches `git log`)
```
Release vX.Y.Z — <short summary>
<optional body: what changed, why it's this bump level>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
```
Release commits historically touch only `CHANGELOG.md` + `plugin.json`
(+ `README.md` when counts/banners change). Keep unrelated files out.
## `make ci` gate notes
`make ci` = `lint test validate eval-all`. The lint glob is `**/*.md` minus a
fixed `--ignore` list. Untracked non-source dirs (`social/`, `.rtk/`, scratch)
are NOT plugin docs — if they trip lint, add them to the `--ignore` list in the
`lint` / `lint-fix` Makefile targets rather than editing the promo/cache files
or shipping with a red gate. That fix is a standalone `chore(lint)` commit, not
part of the release commit.
If only specific changed files matter, lint them directly to confirm clean:
```bash
npx markdownlint CHANGELOG.md README.md plugins/.../changed.md
```
## Gotchas
- **Each release gets four tags.** `git tag vX.Y.Z` carries the GitHub release;
`claude plugin tag plugins/<name>` (verified on CC 2.1.284 with this marketplace
layout) creates `phx--vX.Y.Z`, `ecto--vX.Y.Z`, `lv--vX.Y.Z` — the scheme
dependency version ranges (`^3.1`) resolve against. Push all four together.
- **Users only get updates when `plugin.json` version changes** (install cache).
CHANGELOG/code changes alone are invisible to installed users.
- **The version lives in seven files, not one.** Five by hand
(`plugins/{elixir-phoenix,ecto,lv}/.claude-plugin/plugin.json`, `package.json`,
`package-lock.json`) and two generated from canonical
(`targets/codex/.codex-plugin/plugin.json`, `targets/pi/package.json`, refreshed
by `make generated-skills-sync`). A partial bump fails
`scripts/tests/test_codex.py`, which asserts the Codex manifest matches
canonical — caught in the v3.0.1 release. Regenerate `package-lock.json` with
`npm install --package-lock-only`; a hand-edit can hit an unrelated dependency
that happens to share the old version string.
- **Version consolidation**: phased per-branch bumps that never released should
collapse into ONE bump measured from the last released tag — don't release a
chain of intermediate patch versions.
- **Force-push is hook-blocked.** `block-dangerous-ops.sh` rejects
`git push --force`. If you truly need it, the user runs it via `!`.
- **Three-way match**: `plugin.json` version, the CHANGELOG `## [X.Y.Z]`
heading, and the `vX.Y.Z` tag must all agree. A mismatch ships a confusing
release.
- **Tag the release commit**, not an earlier one: create the tag AFTER the
`Release vX.Y.Z` commit so `git describe` resolves correctly.
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: 471k | 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: 198k | 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: 198k | 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: 198k | Updated | Claude CodeCodex | Verified | Install |