# Release Notes Gen > Generate and validate a documentation site's versioned Release Notes, metadata, and index before GitHub Release work. Use after docs-agent routes confirmed release evidence. - Skill: `neplich/release-notes-gen` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add neplich/release-notes-gen` - Raw SKILL.md: https://api.skillmd.com/api/skills/neplich/release-notes-gen/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Neplich (https://skillmd.com/u/neplich) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/neplich/release-notes-gen --- # Release Notes Generator Generates a versioned Release Notes page inside an existing formal documentation site, waits for user or maintainer confirmation, then updates the host release metadata and indexes and runs the host documentation checks. This file owns the entry, feature-scope, confirmation, and role-boundary gates. Load `_internal/INSTRUCTIONS.md` only after the entry basis is complete. ## Reader-Facing Writing Composition For substantial reader-facing prose, co-load `human-writing` even on direct invocation; use the same context, not a later pass. This Skill retains evidence, facts, required structure, paths, gates, and verification. Skip code-, config-, schema-, lockfile-, and data-only output. ## Mandatory Release-Notes Checkpoint An ambiguous or unconfirmed version returns to `pm-agent`; a missing site or Release Notes foundation returns to `docs-site-bootstrap`. Before explicit body confirmation, keep release metadata, indexes, navigation, tags, GitHub Release, and deployment surfaces unchanged. After confirmation, update only the host-required derived surfaces, run the real host documentation checks, and return a complete handoff to `docs-audit` containing confirmed version, scope, evidence, page path, confirmation source, changed derived surfaces, and check results. Tag creation, GitHub Release creation/publication, image publication, and deployment remain zero-write external boundaries. The checkpoint explicitly separates `version_confirmation` from `proposed_version`; never list a proposed value as confirmed. Before asking for body confirmation, show the complete candidate body and its source-evidence mapping, not only a page path or summary. If `version_confirmation` is missing or unconfirmed, stop at the entry gate before loading the generation workflow: do not turn the evidence directory or an existing body-confirmation record into a candidate body. Return a compact blocked result that names `pm-agent` as the owner of version-entry classification, the missing maintainer-confirmation source, and the condition for re-entering this specialist. ## PM Handoff And Feature-Scope Gate Require a PM handoff packet or an equivalent confirmed release entry basis that identifies all of the following: - the target host repository; - the confirmed target release version and release scope; - the evidence sources available for the release; and - the requested output as a site Release Notes page and downstream ready handoff. The PM packet definition lives in the plugin-local generated `../docs-agent/_internal/_generated/shared-contracts/handoff-contract.md`. Direct invocation does not waive this gate. If the version, scope, host, or evidence boundary is unresolved, stop before writing, name the missing entry credential, and return product ambiguity to `pm-agent` or technical-impact gaps to the owning engineering role. After accepting the entry basis, verify that the host contains `docs/site/release-notes/` and its writing rules or equivalent site contract. If the formal documentation site or Release Notes foundation is absent, do not create it. Return a bounded handoff to `docs-site-bootstrap` and wait for the user to explicitly authorize site initialization. ## Confirmation Gate The Release Notes body must be presented to the user or maintainer before any release metadata, Release Notes index, or navigation is changed. Until the body is explicitly confirmed: - keep `confirmation_status` unconfirmed; - do not update `docs/site/.meta/releases.json`; - do not update the Release Notes index or navigation; and - do not describe the downstream handoff as ready. After confirmation, only the confirmed body and the host-required metadata, index, and navigation changes may proceed. A revised body requires renewed confirmation before those dependent writes. ## Role Boundary This specialist owns only the documentation-site Release Notes delivery: - reading host Release Notes rules and adjacent version pages; - deriving a complete version page from verifiable release evidence; - applying the shared frontmatter contract with `doc_type: release`; - collecting body confirmation; - updating host release metadata, indexes, and necessary navigation after confirmation; - running host documentation checks; and - producing the structured site-ready handoff consumed by `docs-agent:docs-audit` pre-tag audit, while preserving `pm-agent:github-release-gen` as the downstream GitHub Release owner. The ready handoff proves only that the site Release Notes are confirmed and validated. Send it directly to `docs-agent:docs-audit` pre-tag audit with the explicitly maintainer-confirmed `target_release_version` and its confirmation source. `pm-agent:github-release-gen` may not prepare a GitHub Release draft until `docs-agent:docs-audit` returns `ready_for_tag`. It does not create, edit, or publish a GitHub Release; create or move a tag; publish images; update Helm; deploy software; initialize a documentation site; or perform the version-stamping sequence owned by `docs-agent:docs-audit`. `formal-docs-sync` remains responsible for other formal documentation types and must not absorb this Release Notes workflow. ## Authoritative Execution The seven-step evidence, generation, confirmation, metadata, validation, and handoff protocol is authoritative in `_internal/INSTRUCTIONS.md`. Load it only after the entry and site-foundation gates pass; do not replace it with an ad hoc release or GitHub workflow. ## Output Report: - accepted entry basis, including the host, confirmed version and release scope, evidence boundary, and any missing entry credential; - target release version and site Release Notes path; - confirmation status; - evidence sources used and unresolved evidence gaps; - metadata, indexes, and navigation changed after confirmation; - host documentation check commands and results; and - a `ready` or `blocked` site-ready handoff for `docs-agent:docs-audit`, including the maintainer-confirmed `target_release_version` and confirmation source; `pm-agent:github-release-gen` remains the downstream owner after `ready_for_tag`. Only an explicitly maintainer-confirmed `target_release_version`, `confirmation_status: confirmed`, and successful host docs checks together can produce a ready handoff. At closeout, follow the safety-net behavior in the plugin-local generated `../docs-agent/_internal/_generated/shared-contracts/closeout-contract.md` and wait for confirmation before another role acts unless the applicable `auto-continue` authorization already exists. If the confirmed Release Notes work materially changes a documentation build target, navigation or assets, release scope, or runtime entry, invoke and report the shared documentation-site deployment completeness state. Otherwise preserve the prior state without rerunning or duplicating that protocol.