| name | release-changelog-harness |
| description | Chooses ecosystem-native release and changelog tooling (Changesets, Melos, release-plz) plus binary distribution (GitHub Release tarballs, install.sh) when the product is an executable. Use for release CI, install.sh, versioning, CHANGELOGs, shipping MCP/CLI without clone, or meta repos that only ship skills via npx skills—not domain app tutorials. |
| license | MIT |
| type | governance |
| metadata | {"author":"skill-steward","version":"1.2.0","category":"harness"} |
| paths | ["CHANGELOG.md",".changeset/**","package.json","pnpm-workspace.yaml","pubspec.yaml","Cargo.toml",".github/workflows/*release*",".github/workflows/*publish*"] |
Release & changelog harness
Make releases understandable: every version bump has structured intent that agents and humans can read in git—not only in a maintainer’s head or a GitHub Releases textarea.
This skill is meta harness culture (which tool, which gates, which docs). It is not a full tutorial for every package manager.
Mixture of experts — critique your idea
| Expert lens | Verdict on “use JS Changesets everywhere” |
|---|
| JS monorepo maintainer | Strong default: .changeset/*.md + changeset version beats hand-editing five package.json files. |
| Dart / Flutter publisher | Weak fit as-is: pub uses tags + CHANGELOG.md; monorepos often use Melos version / changelog, not npm Changesets. |
| Rust / Go shipper | Use release-plz, cargo-release, or git-cliff—forcing Changesets adds alien workflow. |
| Agent operator | Wins when notes live as small structured files in git agents can read and PR—not prose-only in Slack. |
Multi-repo steward (~/mcp) | One legibility contract across siblings; different generators per ecosystem is fine. |
| Skill Steward charter | Teach when + gate + doc placement; link to upstream docs; do not paste 200-line configs into SKILL.md. |
Improved framing (use this):
Adopt the release legibility contract first; pick the ecosystem-native generator second (Changesets is one excellent generator for JS workspaces, not the universal hammer).
See mixture-of-experts.md for extended debate and anti-patterns.
Release legibility contract (normative)
Before picking a tool, agree the repo obeys:
- Notes in git — Changelog or changeset files are versioned; not release-notes-only in a web UI.
- Structured contributor input — Contributors add intent in a fixed shape (e.g.
.changeset/foo.md, conventional commit scope, or ADR note)—not “bump version when you remember.”
- Mechanical publish path — One documented command sequence in DX_FAQ; CI is the source of truth for “can ship.”
- Agent-readable output — Post-release,
CHANGELOG.md (or per-package changelogs) reflects what shipped; agents can answer “what changed in vX?”
- Why is recorded — Non-obvious toolchain choice → short ADR or DESIGN_FAQ Q&A.
- Install trust matches release truth — The latest GitHub Release, release assets, checksums, package versions, and install docs must agree; stale pinned install examples are release drift.
Ecosystem router (default patterns)
| Signal in repo | Default tooling | Notes |
|---|
pnpm-workspace.yaml / npm workspaces | @changesets/cli | Industry standard for JS monorepos; pair with GitHub Action. |
| Single Node package, high release cadence | release-please or Changesets | release-please = conventional commits → PR; Changesets = explicit human/agent intent files. |
Dart monorepo (melos.yaml) | Melos version + changelog | Align with pub publish order in DX_FAQ. |
| Single Dart package | CHANGELOG.md + git tag + dart pub publish | Keep entries agent-editable markdown. |
| Rust workspace | release-plz or cargo-release + git-cliff | Prefer automation that opens version PRs. |
| Product harness w/ binaries | release-please + tag CI + install.sh | Do not add a second version source; follow binary-release-contract.md |
| Meta + CLI binary (Skill Steward) | Changesets + single Release workflow + install.sh | Version PR updates git truth first; the release workflow tags, builds assets, creates/updates GitHub Release, and verifies latest/install trust per ADR 0014 |
Full matrix: ecosystem-tooling.md. Binary/install: binary-release-contract.md.
When to use this skill
- “We should use Changesets like the JS community”
- Release process is unclear, versions drift, or agents can’t tell what shipped
- Adding release CI, versioning policy, or monorepo publish workflow
- Auditing whether changelog tooling matches repo archetype (
repo-quality-system-lifecycle)
Workflow
1. Classify the repo
Use repo-quality-system-lifecycle archetypes (app, library, CLI/tool, plugin, harness, meta/governance). Meta and harness repos need legibility; app repos need legibility and runtime compatibility notes.
2. Choose generator (ADR if non-obvious)
| Question | If yes → |
|---|
| Multiple publishable JS packages? | Changesets (default) |
| Single package, commit-msg driven releases? | release-please |
| Maintainer writes explicit release notes per PR? | Changesets |
| Pub or Cargo primary? | Ecosystem table above—not Changesets |
Record choice in docs/decisions/NNNN-release-changelog-tooling.md when more than one option is reasonable.
3. Wire harness surfaces
| Surface | Action |
|---|
| DX_FAQ | Memory-palace block: add changeset, version, publish, verify tag |
| CI | Block publish/tag if changesets/changelog policy violated; for binaries, use one release owner or an explicit workflow_run/PAT handoff |
| AGENTS.md | One row in doc router—no full Changesets essay |
| CONTRIBUTING | “Every user-facing PR adds a changeset or CHANGELOG entry” |
4. Minimal Changesets shape (JS monorepos and private packages)
Contributor adds:
---
"package-name": patch
---
Short imperative summary agents can quote in release notes.
Private Packages and Public Tags
By default, Changesets ignores packages marked with "private": true in package.json. To allow version bumps for a private root package or private workspace modules, update .changeset/config.json to include:
"privatePackages": {
"version": true,
"tag": false
}
Use "tag": false when a custom release script owns the public vX.Y.Z tag. Use "tag": true only when Changesets itself should create package-scoped tags.
Maintainer flow:
pnpm changeset
pnpm changeset version
pnpm install
git commit -am "chore: version packages"
Publish: project-specific (changeset publish, GitHub Action, or npm provenance)—document exact commands in DX_FAQ, not here.
For automated Changesets releases, prefer:
merge feature PR with changeset
→ CI opens/updates Version PR
→ merge Version PR
→ same Release workflow creates vX.Y.Z, builds artifacts, creates/updates GitHub Release, verifies latest release state
If the tag is pushed with GITHUB_TOKEN, do not depend on a separate on: push: tags workflow to build assets; GitHub suppresses recursive workflow triggers for that token.
5. Choose distribution surface
| Ship unit | Pattern |
|---|
| Executable MCP/CLI | GitHub Release binaries + checksums + install.sh — binary-release-contract.md |
| Skills only | npx skills add owner/repo — no repo tarball for consumers |
| Libraries | pub.dev / npm / crates.io per ecosystem table |
Skill Steward: skills via npx skills; steward_cli precompiled AOT binaries via GitHub Releases & install.sh (ADR 0014).
6. Verify legibility
Anti-patterns
| Anti-pattern | Why it hurts |
|---|
| Changesets in a Rust-only repo | Wrong culture; contributors ignore it |
| Changelog only on GitHub Releases | Agents in repo context miss it |
| 1,000-line release doc in AGENTS.md | Crowds task context; belongs in DX_FAQ / ADR |
| Skipping changesets “because AI will write CHANGELOG at release” | Non-deterministic; no PR-time review |
| Version bumps without consumer-facing sentence | Users and agents can’t assess upgrade risk |
| Binary Releases without changelog in git | Users see version; agents miss intent |
Separate tag-triggered binary workflow after a GITHUB_TOKEN tag push | GitHub suppresses recursive workflow triggers; latest release/assets can silently lag |
| Static pinned install examples with real old versions | README/DX says one thing while GitHub Releases/install.sh say another |
git clone as end-user install for a server product | Use install.sh + Release assets (binary release pattern) |
Related skills
| Skill | Use for |
|---|
repo-quality-system-lifecycle | Repo archetype, mechanical gates, evidence path |
mcp-harness-repo-maintainer | Typed actions, probes, benchmarks, CLI/MCP parity |
repository-governance-lifecycle | ADRs, DESIGN_FAQ/DX_FAQ updates, and plan hygiene |
skill-source-citations | Durable release-tooling sources |
Install
npx skills add arenukvern/skill_steward --skill release-changelog-harness
Sources
references/sources.md
