Skip to content
Skills Library
DevOps & cloud · Automation

release

/release

Cut a new Marko release. Reads every PR merged since the last tag, audits their release-notes labels, recommends the next version number with reasoning, and — only after you confirm or override it — runs `./bin/release.sh`. **Use this skill whenever the user types /release or asks to cut, ship, publish, or tag a release.** Takes no arguments; the version is decided in conversation, not on the command line.

Repository
marko ↗
Licence
MIT
Last repository change
09.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 09.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Cut a new Marko release. Reads every PR merged since the last tag, audits their release-notes labels, recommends the next version number with reasoning, and — only after you confirm or override it — runs `./bin/release.sh`. **Use this skill whenever the user types /release or asks to cut, ship, publish, or tag a release.** Takes no arguments; the version is decided in conversation, not on the command line.

Original author description

Cut a new Marko release. Reads every PR merged since the last tag, audits their release-notes labels, recommends the next version number with reasoning, and — only after you confirm or override it — runs `./bin/release.sh`. **Use this skill whenever the user types /release or asks to cut, ship, publish, or tag a release.** Takes no arguments; the version is decided in conversation, not on the command line.

How it works

  1. Arguments
  2. Step 1 — Verify preconditions
  3. Step 2 — Read what is shipping
  4. Step 3 — Audit the labels
  5. Step 4 — Decide the version
  6. Step 5 — Present the recommendation, then stop
  7. Step 6 — Execute
  8. Step 7 — Report
  9. Guardrails
Original SKILL.md headings · 229 lines, 1,774 words
SKILL.md preview
---
name: release
description: >
  Cut a new Marko release. Reads every PR merged since the last tag, audits their
  release-notes labels, recommends the next version number with reasoning, and — only after
  you confirm or override it — runs `./bin/release.sh`.
  **Use this skill whenever the user types /release or asks to cut, ship, publish, or tag a release.**
  Takes no arguments; the version is decided in conversation, not on the command line.
---

# Cut a Marko release

`bin/release.sh` already automates everything mechanical: the full test suite, the
`develop` → `main` merge, changelog generation, the tag, the GitHub Release, and the
merge-back to `develop`. It does not decide *whether* to release or *what to call it*.
That judgment is this skill's only job.

Two things must be right before a tag is pushed, and both are listed as manual in
`.claude/release-process.md`:

1. **Every merged PR is labeled**, or its changes vanish into a generic "Other Changes"
   bucket in the release notes.
2. **The version number is correct**, because all 70 packages share it and Composer
   constraints downstream depend on it.

There is exactly **one approval gate**: present the recommendation, stop, and wait. Do not
tag on your own initiative — not even for an obviously-correct patch bump.

## Arguments

None. `/release` takes no arguments; the version is settled at the approval gate in step 5.

If the user does type something after `/release` anyway, treat it as an authoritative
override and skip straight to validating it (same checks as an override at the gate).

## Step 1 — Verify preconditions

```bash
git fetch --quiet --tags origin develop main
git status --short                        # must be empty
git rev-parse --abbrev-ref HEAD           # must be develop
git rev-list --count origin/develop..develop   # must be 0 (nothing unpushed)
git rev-list --count develop..origin/develop   # must be 0 (nothing unpulled)
php -v                                    # must be 8.5.x, else set PHP_BIN
command -v gh jq                          # both required by bin/release.sh
```

Also confirm there is something to release: `git log $(git tag --sort=-v:refname | head -1)..develop --oneline` must be non-empty.

If any check fails, say exactly which one and stop. Do not quietly fix it — an unpushed
commit or a dirty tree usually means work is still in flight, which is the user's call,
not yours.

If `php -v` is not 8.5, don't abandon the run — pass an explicit interpreter through to
the script instead: `PHP_BIN=/path/to/php8.5 ./bin/release.sh X.Y.Z`.

## Step 2 — Read what is shipping

```bash
LAST_TAG=$(git tag --sort=-v:refname | head -1)
git log "$LAST_TAG"..develop --pretty='%s' | grep -oE '#[0-9]+' | sort -u
```

Read every PR you found — title, body, and labels. Commit subjects alone will mislead you
about scope:

```bash
gh pr view <N> --json number,title,body,labels,url
```

**Flag any commit on `develop` with no `#NN` reference.** `bin/release.sh` builds the notes
by walking `git log` and resolving PR numbers, so an unreferenced commit is silently
omitted from both `CHANGELOG.md` and the GitHub Release. Surface these at the gate; the fix
is a follow-up commit that mentions the PR, not a hand-edited changelog.

## Step 3 — Audit the labels

`.github/release.yml` buckets PRs into release-notes sections by label. Anything unlabeled
lands in "Other Changes"; anything mislabeled lands in the wrong section.

| Label | Section |
|-------|---------|
| `breaking` | Breaking Changes |
| `enhancement` | New Features |
| `bug` | Bug Fixes |
| `documentation` | Documentation |
| `refactor` | Refactoring |
| `testing` | Testing |
| `ci` | CI |
| `maintenance` | Maintenance |

`duplicate`, `invalid`, `wontfix`, `question`, `good first issue`, and `help wanted` are
excluded from the notes entirely — a release-worthy PR carrying only one of those is a
labeling bug.

Propose label corrections at the gate rather than applying them silently. When applying
them, note that `gh pr edit` silently fails on this repo (GraphQL Projects-classic bug) —
use the REST endpoint:

```bash
gh api repos/marko-php/marko/issues/<N>/labels -f "labels[]=bug"
gh api repos/marko-php/marko/issues/<N>/labels/enhancement -X DELETE
```

## Step 4 — Decide the version

Marko is in `0.x`: all 70 packages share one version, and `1.0.0` is the first release with
semver guarantees. Compute from the latest tag.

- **Patch** (`0.8.4` → `0.8.5`) — bug fixes, documentation, CI, refactors, tests, and
  additive changes that add no public API surface.
- **Minor** (`0.8.4` → `0.9.0`) — a new package, new public API, or any breaking change.
  While in `0.x` there is no separate major channel, so breaking changes ride the minor.
- **Major** (`1.0.0`) — never infer this. Only when the user says the API is stable.

### Labels do not decide the version

Labels route a PR into a release-notes section. They say nothing about the bump. The
`enhancement` label feeds a section titled "New Features" — that is a heading, not a minor
version. **Judge every `enhancement` on its own merits; do not let one in the batch
mechanically escalate a patch to a minor.**

Classify each PR by what a consumer can observe after `composer update`:

1. **Never leaves the monorepo** — `.claude/`, `bin/`, `.github/`, root `tests/`, repo docs.
   Only `packages/*` is copied into split repos, so nothing here can reach anyone's
   `vendor/`. **Irrelevant to the version, whatever its label.** Confirm mechanically:

   ```bash
   gh pr view <N> --json files -q '[.files[].path] | map(select(startswith("packages/"))) | length'
   ```

   A `0` means repo-internal tooling. This is the common case for maintainer-facing
   `enhancement` PRs — a new skill, a CI tweak, a release script improvement.

2. **Ships in a package but adds no callable surface** — CLI output or prompt wording, a
   docs page, an internal refactor, a new fake in `marko/testing` used only by our own
   suite. Nothing new for an app developer to call, extend, configure, or depend on.
   **Patch.** This includes internals added in service of a fix — a new exception factory,
   for instance, is *thrown* at consumers rather than built against, so it does not make a
   bug fix into a feature.

3. **Adds or changes surface a consumer builds against** — a new interface, method,
   attribute, config key, container binding, event, console command, or an entire package.
   Also anything that changes existing behavior an app could already be relying on.
   **Minor.**

Only tier 3 forces the minor. A batch of tier-1 and tier-2 work plus a bug fix is a patch,
even when several PRs carry `enhancement`.

Calibration example — the batch that shipped as `0.8.5`, which carried two `enhancement`
labels and was still correctly a patch:

| PR | Label | Tier | Why |
|----|-------|------|-----|
| #142, #144 | documentation | 1 | repo docs and skills, nothing under `packages/` |
| #143 | enhancement | 2 | a `devai:install` prompt tip — no new callable surface |
| #146 | enhancement | 1 | maintainer-only `/release` skill under `.claude/` |
| #145 | bug | 2 | unblocked `db:migrate`; its new exception factory is thrown, not built against |

**The tiebreaker for a genuinely mixed batch is Composer reachability.** In `0.x`, Composer
treats the *minor* as the breaking position: `^0.8.4` accepts `0.8.5` but refuses `0.9.0`. A
patch reaches every downstream project on a plain `composer update`; a minor sits unnoticed
until someone edits their constraint. So when the release exists to get a fix into users'
hands, and the rest of the batch is tier 1 or 2, prefer the patch. Do not use this as cover
for hiding tier-3 work in a patch — that earns the minor even if it means a slower rollout.

State the decision in one or two lines and cite the PRs driving it. Also check whether the
bug being fixed makes a released version unusable — that is the difference between "worth
releasing now" and "wait for more to accumulate", and the user should hear which one this
is.

## Step 5 — Present the recommendation, then stop

Show, concisely:

1. **What is shipping** — a table of PRs since the last tag, with labels **and the tier you
   assigned each one**. Showing the tiers is what makes the version recommendation
   auditable: the user can disagree with one classification rather than the whole call.
2. **Label fixes needed** — or explicitly "labels are clean".
3. **Recommended version + rationale** — including whether this is urgent enough to ship
   now. If any `enhancement` in the batch did *not* escalate the bump, say so explicitly and
   why, rather than leaving the user to wonder whether it was overlooked.
4. **What will happen on approval** — merge `develop` into `main`, run the full suite
   *including* the `integration-destructive` group, generate `CHANGELOG.md`, commit, tag,
   push, create the GitHub Release, merge back to `develop`.

**Be precise about the failure state — do not promise a clean abort.** `bin/release.sh`
checks out `main` and merges `develop` *before* it runs the tests. A test failure therefore
leaves the local repo checked out on `main` with the merge already made. Nothing is pushed,
no tag exists, and `CHANGELOG.md` is untouched — but it is not a no-op. Recovery is
`git checkout develop`, fix the failure, and re-run; the merge is idempotent. Mention this
when describing what will happen, and note that re-running while still on `main` trips the
Step 1 branch precondition.

Then wait. If the user overrides the version, validate it before running: `X.Y.Z` with no
`v` prefix and no pre-release suffix, strictly greater than the latest tag, and not an
existing tag. If it looks wrong, say so once — then defer if they confirm.

## Step 6 — Execute

From `develop`, with a clean tree:

```bash
./bin/release.sh <version>
```

Expect this to run for several minutes — the destructive integration group builds real
installs. Let it finish; do not run it in the background and do not re-run it after a
partial failure without reading the error first. If it failed in the test phase you are now
on `main` — `git checkout develop` before retrying.

## Step 7 — Report

Give the user the version shipped and the GitHub Release URL, then point at the two
asynchronous things that finish after the tag:

- Split workflow: <https://github.com/marko-php/marko/actions>
- Packagist: <https://packagist.org/packages/marko/>

If the script aborted, relay its error verbatim and stop.

## Guardrails

- **Never tag without explicit approval of a specific version number.**
- **Never hand-edit `CHANGELOG.md`.** `bin/release.sh` generates and commits it; a manual
  edit produces a duplicate section and a redundant commit.
- **Never run the script from a branch other than `develop`**, and never commit directly to
  `main` — the script owns that merge.
- **Never narrow the test suite to get past a failure.** No `--exclude-group`, no skipping.
  A failing destructive-integration test means the release would ship a broken install.
- Never invent a release-notes entry for something you did not find in a merged PR.
- Never round the version up to make a release look bigger. Never bump the minor merely
  because several PRs landed, or because one of them is labeled `enhancement` — only tier-3
  surface changes force it.
- If nothing user-facing merged since the last tag, say so and ask whether to proceed
  instead of manufacturing a reason to tag.

Versions

RepositoryScoreLicence
This page · marko-php/marko100MIT
josephfung/curia100MIT
max-sixty/worktrunk100MIT
gtapps/hermitd100MIT
gtapps/hermitd100MIT
anthony-chaudhary/fak100Apache-2.0
tractorjuice/arc-kit100MIT
drvoss/everything-copilot-cli100MIT
sma1lboy/rove100MIT

Database snapshot: 13.11.2026 · package version 449943fdaeae (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100release-publish
    Prepare and publish a ClawWork desktop release or prerelease. Use when: user says "release", "publish beta", "发版", "发布 beta", "发 beta", "cut a release", or asks to ship a version tag.
  • 100cut-release
    Cut a new agnostic-ai release end to end. Use when the user wants to ship a new version (tag + GitHub Release).
  • 100releasing
    Full release lifecycle — version bump, CHANGELOG, rich release notes, tag, publish. Use when user says "release", "tag and release", "publish version", "cut a release", "new version".
  • 100create-release
    Use when the user asks to "create a release", "cut a release", "tag a version", "publish release notes", or ship a new versioned GitHub release for the current repo.
  • 95prepare-release
    End-to-end release automation — reads commits since last tag, infers semver bump, drafts changelog, creates release PR, merges it, waits for CI green, tags, and monitors the Docker build to completion. Use when the user says: prepare release, cut a release, bump version, create…
  • 96tag-release
    Use when asked to tag or cut a patch, minor, or major release.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.