Release
Ship a version with a durable CHANGELOG for agents and separate user-facing GitHub release notes without duplicating bullets between them.
Overview
release is an agent skill most often used in Ship (also Operate, Build) that produces separate CHANGELOG.md and curated GitHub release notes so agents can orient on history without conflating durable records with user-fa
Install
npx skills add https://github.com/boshu2/agentops --skill releaseWhat is this skill?
- Writes two artifacts per release: append-only CHANGELOG.md and dated docs/releases/*-notes.md
- Changelog optimized for future agents—coverage, evidence links, four archaeology questions without reading the diff
- Release notes optimized for GitHub feed readers—plain English, scannable in ~15 seconds
- Explicit rule: never copy bullets between changelog and release notes
- Pairs with release-notes.md reference for user-facing shape and tone
- Two distinct artifacts per release: CHANGELOG.md and docs/releases/*-notes.md
- Changelog framed to answer four orientation questions without reading the diff
Adoption & trust: 819 installs on skills.sh; 384 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You tag a release but agents and users get either a marketing blurb or an unreadable diff dump, so nobody can quickly see what materially changed or why.
Who is it for?
Solo builders shipping agent-maintained repos who want changelog-as-orientation-layer and clean GitHub Releases in one ritual.
Skip if: Teams that only need a one-line version bump with no docs, or repos that do not use CHANGELOG.md / docs/releases conventions.
When should I use this skill?
When cutting a release, writing CHANGELOG.md, or preparing GitHub Release notes in an AgentOps-managed repo.
What do I get? / Deliverables
Each release lands with an append-only changelog for archaeology and a distinct notes file for GitHub—ready for tagging and publish without duplicated bullets.
- Updated CHANGELOG.md
- docs/releases/YYYY-MM-DD-v<version>-notes.md
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Release is the canonical shelf in Ship because versioning, tagging, and publishing release artifacts happen at the launch moment of a build cycle. Launch prep is where changelog orientation and curated notes must exist before tags and GitHub Releases go live.
Where it fits
Cut v1.4.0 with CHANGELOG entries linked to issues and a short notes file for the GitHub Release body.
Document a hotfix release so the next agent knows what production behavior changed without reading the full diff.
Close a feature epic by recording shipped scope in the changelog with evidence links for future archaeology.
How it compares
Use instead of pasting git log or PR titles into a single README blurb—structured dual artifacts, not a monolithic release paragraph.
Common Questions / FAQ
Who is release for?
Indie and solo builders using AgentOps (or similar agent workflows) who cut versions and need both durable history for the next coding agent and scannable notes for GitHub readers.
When should I use release?
At Ship when preparing a version tag and GitHub Release; in Operate when documenting what shipped for incident or iteration context; in Build when closing an epic and recording evidence-linked history for contributors.
Is release safe to install?
It is a documentation and release workflow skill—review file-write scope in SKILL.md and check the Security Audits panel on this Prism page before granting broad filesystem access in your agent.
SKILL.md
READMESKILL.md - Release
# Changelog as a Research Artifact > A changelog is not marketing copy and not a diff dump — it is an orientation layer for the next agent (or human) who has to navigate the project's history. This reference describes how to produce a changelog that survives that role. Read alongside [`release-notes.md`](release-notes.md), which covers the user-facing notes file separately. The `/release` skill produces two distinct artifacts per release: `CHANGELOG.md` (the durable history) and `docs/releases/YYYY-MM-DD-v<version>-notes.md` (the curated GitHub Release body). They have different audiences, different shapes, and different lifetimes. --- ## Two artifacts, two audiences | Artifact | Audience | Lifetime | Optimised for | |---|---|---|---| | `CHANGELOG.md` | Future agents, contributors, archaeology | Permanent, append-only | Coverage, evidence links, navigability | | `docs/releases/*-notes.md` | GitHub feed readers, casual users | Per-release | Plain-English impact, scannable in 15 seconds | The single biggest mistake is to copy one into the other. The release notes are a curated, jargon-stripped distillation; the changelog is the durable record of what shipped. The `/release` skill enforces this by writing two files in two steps — never duplicate the bullets between them. --- ## What the changelog has to answer A useful changelog lets another agent answer four questions without reading the diff: 1. What materially changed in this version? 2. When did it ship (release vs plain tag)? 3. Why did it change (which workstream / issue drove it)? 4. Which commits are the right entry points for deeper inspection? If a section in your changelog cannot answer any of these, it is padding. --- ## Structured sections A changelog entry per version follows the [Keep a Changelog](https://keepachangelog.com/) shape (Added / Changed / Fixed / Removed / Deprecated / Security). The section names are non-negotiable for tooling; the content style adapts to the project. For larger releases, layer a thematic structure on top: ```markdown ## [1.7.0] - 2026-05-03 ### Added - <capability-level entries with workstream links> ### Changed - <capability-level entries> ### Fixed - <each fix with the issue ID it closed> ``` For a release that lands a multi-week epic, prefer a short narrative paragraph above the Added/Changed sections that names the capability wave. Without that paragraph, the bullets read as a flat diff dump and lose the reason the changes belong together. --- ## Breaking-change callouts Breaking changes need a structural callout, not just a `BREAKING:` prefix buried in a bullet. Two patterns work: **Inline callout block** — a bold lead-in inside the section, with the migration step as a sub-bullet: ```markdown ### Changed - **BREAKING:** `ao goals init` now requires `--mode {yaml,md}`. Existing invocations without `--mode` will fail. - Migration: pass `--mode md` to retain the previous default. ``` **Dedicated section** — for releases with multiple breaking changes, a `### Breaking Changes` block above Added with a numbered list of "what broke / how to migrate" pairs. Either pattern surfaces the change to a downstream consumer who is grepping the file for "BREAKING" before upgrading. Burying breaking changes inside narrative is the most common reason a major-version bump silently breaks a downstream agent. --- ## Release vs tag distinction A git tag and a published GitHub Release are not the same artifact. The changelog must be honest about this: - A tag with no Release page is a tag. Mark it as such. - A draft Release is not a published Release. Do not link to it as if it were. - A published Release exists when `gh release view <tag>` returns a status of `published`. For the `/release` skill, the in-repo state is the tag plus the curated notes file. CI is what publishes the Release. If a release run failed and never published, the tag still exists — the changelog should not pretend a Release page exists at tha