AGENT SKILL

release-changelog-harness

For Changesets/Melos/release-plz, CHANGELOG hygiene, release CI, install.sh, and binary/GitHub Release distribution for CLIs and meta skill marketplaces. Not for repo quality baselines, ADRs, harness dogfood, or domain app feature work—use repo-quality-system-lifecycle or native product gates.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 13
Forks
2

01 前言 Front Matter

name
release-changelog-harness
type
governance
paths
[ "CHANGELOG.md", ".changeset/**", "package.json", "pnpm-workspace.yaml", "pubspec.yaml", "Cargo.toml", ".github/workflows/*release*", ".github/workflows/*publish*" ]
license
MIT
metadata
{ "author": "skill-steward", "version": "1.2.0", "category": "harness" }
description
For Changesets/Melos/release-plz, CHANGELOG hygiene, release CI, install.sh, and binary/GitHub Release distribution for CLIs and meta skill marketplaces. Not for repo quality baselines, ADRs, harness dogfood, or domain app feature work—use repo-quality-system-lifecycle or native product gates.

02 资源文件 5

03 SKILL.md 正文

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. Ordinary work: work discipline. The former plugin-marketplace-setup skill was removed in 0.6.0.

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:

  1. Notes in git — Changelog or changeset files are versioned; not release-notes-only in a web UI.
  2. 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.”
  3. Mechanical publish path — One documented command sequence in DX_FAQ; CI is the source of truth for “can ship.”
  4. Agent-readable output — Post-release, CHANGELOG.md (or per-package changelogs) reflects what shipped; agents can answer “what changed in vX?”
  5. Why is recorded — Non-obvious toolchain choice → short ADR or DESIGN_FAQ Q&A.
  6. 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          # or npx @changesets/cli
pnpm changeset version
pnpm install            # if lockfile must update
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

  • [ ] Agent can read “what’s unreleased” from git without GitHub API
  • [ ] CI fails when a version bump lacks notes
  • [ ] DX_FAQ lists commands copy-paste ready
  • [ ] No duplicate version sources (e.g. hand bump + bot bump)
  • [ ] If binaries: tag assets match version SSOT; latest GitHub Release points to the package version; install.sh defaults to latest and pinned examples use placeholders or generated checks

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
repository-governance-lifecycle ADRs, DESIGN_FAQ/DX_FAQ updates, and plan hygiene

Install

npx skills add arenukvern/skill_steward --skill release-changelog-harness

Sources

references/sources.md

04 同仓库更多 Skills

Arenukvern
Arenukvern/skill_steward

your-skill-name

Replace with what this skill does and when to use it. Include trigger phrases users say, e.g. "audit my API", "scaffold a skill"; activation-critical routing belongs here.

★ 13
Arenukvern
Arenukvern/skill_steward

skill-authoring-lifecycle

For creating or editing installable Agent Skills, eval cases, citations, and marketplace/registry readiness in this repo. Not for adopting consumer repos, governance ADRs, or release automation—use repo-quality-system-lifecycle, repository-governance-lifecycle, or release-changelog-harness.

★ 13
Arenukvern
Arenukvern/skill_steward

repository-governance-lifecycle

For ADRs, DESIGN/DX FAQ edits, north_star_impact, stale-plan hygiene, ethics, brand tone, MoE on governance conflicts, and doc-lattice changes that outlive one repair. Not for repo adopt/baseline, ecology compress/merge/retire, or product feature work—use repo-quality-system-lifecycle or native gates.

★ 13
Arenukvern
Arenukvern/skill_steward

repo-quality-system-lifecycle

For adopt/baseline, stewardship quality-contract audits, evidence and maturity proof, producer/consumer boundaries, repo ecology compress/merge/retire, and claim-honesty reviews. Not for ADR/FAQ-only governance, harness generalization after baseline, release CI, skill packaging, or routine product repairs with a known native gate.

★ 13
Arenukvern
Arenukvern/skill_steward

multi-agent-handoff

For baton handoffs, one-obligation moves between agents, and parent-lane or parallel-batch contracts when multiple subagents share work. Not for repo adopt, ADRs, ecology cleanup, or product implementation—use repo-quality-system-lifecycle, repository-governance-lifecycle, or native work.

★ 13
Arenukvern
Arenukvern/skill_steward

harness-engineering-lifecycle

For generalizing a proven local steward.yaml harness across producer-consumer repos, polyrepo CLI/MCP integration, and sibling-repo dogfood after a contract exists. Not for cold-start adoption, first steward.yaml, first quick probe, or skill packaging—use repo-quality-system-lifecycle or skill-authoring-lifecycle.

★ 13