efforts
The `/pm-release` utility skill encodes the end-to-end product release workflow for pm-skills, automating multi-phase steps including pre-flight audits, documentation generation, CI validation, artifact authoring, version bumps, and GitHub Release creation. Use this skill to streamline release cycles that previously required 2 to 4 hours of manual work rediscovered from scratch each version.
git clone --depth 1 https://github.com/product-on-purpose/pm-skills /tmp/efforts && cp -r /tmp/efforts/docs/internal/efforts/F-38-release- ~/.claude/skills/effortsF-38-release-skill.md
# [F-38] `/pm-release` Utility Skill Status: Backlog Milestone: v2.12.0 (candidate) Issue: TBD Agent: Claude Opus 4.7 ## Scope Create `skills/utility-release/` with command `/pm-release` that encodes the end-to-end release workflow currently executed manually each version. One invocation runs: pre-flight audits, em-dash sweep, stale-count reconciliation, mkdocs regeneration, CI validation, CHANGELOG + release notes + skills-manifest authoring, commit, tag, push, GitHub Release verification. Surfaced by the 2026-04-23 `/insights` report which flagged the release workflow as repeated three times (v2.11.0, v2.11.1, jp-ai-review v1.1.0) with nearly identical steps, each time rediscovered from scratch. ## Problem Every pm-skills release cycle in the v2.10+ era has followed the same multi-phase pattern: 1. Pre-flight audits (em-dash sweep, stale skill-count reconciliation, broken-link checks) 2. Generator reruns (`scripts/generate-skill-pages.py`, `generate-workflow-pages.py`, `generate-showcase.py`) to sync docs/ with sources 3. CI validation suite (`lint-skills-frontmatter`, `validate-agents-md`, `validate-meeting-skills-family`, `check-count-consistency`) 4. Dry-run against live skills CLI to confirm 38 skills discoverable 5. Release artifact authoring: plan doc, skills-manifest.yaml, CHANGELOG entry, release notes, release-index row 6. Version bumps: README badge, `.claude-plugin/plugin.json`, `marketplace.json` 7. Commit, tag, push, GitHub Release polish Today this is roughly 2 to 4 hours of work that an agent re-derives from context each version. Evidence: - v2.11.0 release cycle took multiple sessions with Codex adversarial review loops - v2.11.1 (2026-04-22) repeated the same steps top-to-bottom, including a review pass that discovered pre-push gaps (missing What's New entry, "5 vs 8 references" wording) - Cross-session friction: the agent starts each release by re-learning the release plan template, re-reading CHANGELOG conventions, re-checking which files need version bumps A `/pm-release` skill would turn this into: the agent already knows the template, the checklist, the order, the exemplar commit messages, the CI sequence. ## How It Works ### Invocation modes Three subcommand variants covering the typical slice of work: - `/pm-release prep <version>` runs the audit + generator + CI phases, authoring the release plan + skills-manifest but not committing anything. Agent presents a review checkpoint before the user approves proceeding to ship. - `/pm-release ship <version>` assumes prep is done and approved. Runs CHANGELOG + release notes authoring, version bumps, final CI, staged commit, tag, push. Pauses before push for user confirmation. - `/pm-release verify <version>` runs post-push validation: `gh release view`, live CLI dry-run from clean env, GitHub Release body check (strips frontmatter if present), docs-site link check. ### Inputs Minimal required: - Target version (e.g., `v2.11.2`) - Release type (patch, minor, major) to guide copy in CHANGELOG + release notes - Release theme (one-liner for CHANGELOG section header) Optionally: - Override path to release-plan template - Skip phases (e.g., `--skip-mkdocs-regen` when no skill content changed) ### Default behavior Sensible defaults drawn from the v2.11.1 release as the gold-standard exemplar: - Em-dash sweep runs whenever any `.md` file has changed since last tag - Stale-count reconciliation runs unconditionally (cheap; high value) - Generator reruns run when `skills/` or `_workflows/` or `library/skill-output-samples/` have changed since last tag - CI suite runs all validators; any failure blocks ship phase - Commit boundaries: one commit per logical unit (em-dash sweep, release artifacts, mkdocs polish) unless user passes `--single-commit` - Tag is never moved once pushed; polish commits land on main after the tag ### Guardrails - Never uses `git push --force` without explicit confirmation - Blocks push if CI fails - Blocks push if `--follow-tags` would move an already-pushed tag - Detects and warns on em-dashes in any staged file before commit - Detects and warns on unquoted descriptions with inline `": "` (the YAML-parser gotcha caught during v2.11.1 skills.sh work) ## Classification - Type: utility skill (automates repo-level workflow, not domain/phase work) - Directory: `skills/utility-release/` - Command: `/pm-release` (with subcommands `prep`, `ship`, `verify`) - SKILL.md pattern: mirror of other utility skills (`utility-pm-skill-builder`, `utility-pm-skill-validate`, `utility-pm-skill-iterate`, `utility-update-pm-skills`) ## Exemplars - `docs/internal/release-plans/v2.11.1/plan_v2.11.1.md` is the gold-standard template. the skill should produce plans of this shape - `docs/internal/release-plans/v2.11.1/skills-manifest.yaml` is the canonical manifest schema - `docs/releases/Release_v2.11.1.md` shows the user-facing release notes structure - `CHANGELOG.md` entries for v2.11.0 and v2.11.1 show the Keep-A-Changelog style in use here - `skills/utility-pm-skill-builder/SKILL.md` is the closest structural exemplar for a multi-phase utility skill with subcommand-style invocation ## Deliverables - `skills/utility-release/SKILL.md` - `skills/utility-release/references/TEMPLATE.md` (release-plan template, pre-filled sections) - `skills/utility-release/references/EXAMPLE.md` (worked example reproducing the v2.11.1 release) - `skills/utility-release/references/CHECKLIST.md` (phase-by-phase checklist that the skill walks through) - `commands/pm-release.md` (Claude Code slash command entry) - `AGENTS.md` (new entry for the skill) - `mkdocs.yml` (new nav entry) - `docs/skills/utility/utility-release.md` (auto-generated on first `generate-skill-pages.py` run after landing) - `docs/internal/release-plans/v2.12.0/skills-manifest.yaml` (lists `utility-release` 1.0.0 as added) - `docs/internal/release-plans/v2.12.0/plan_v2.12.0.md` (update to include F-38) ## Validation ### Dry-run test plan 1. **Prep phase
Run an ad-hoc ordered chain of pm-skills with shared context (ephemeral; routes to the pm-workflow-orchestrator)
Defines a testable hypothesis with clear success metrics and a validation approach. Use when forming assumptions to test or aligning a team on what success looks like, before any experiment is designed. To design the A/B test or experiment that will validate the hypothesis, use measure-experiment-design.
Creates a Jobs to be Done canvas capturing the functional, emotional, and social dimensions of a customer job. Use when deeply understanding customer motivations, designing for jobs, or reframing product positioning.
Creates an opportunity solution tree connecting a desired outcome to customer opportunities and candidate solutions, preventing solution-first jumps in continuous discovery. Use when structuring scattered feature ideas or communicating how the roadmap traces to outcomes. For ranking an existing flat list of candidates, use define-prioritization-framework instead; this skill discovers the list, it does not score one.
Run applicable prioritization frameworks (RICE, ICE, MoSCoW, Weighted Scoring, Kano) against a list of features or initiatives. Produces a comparison table showing where rankings agree and diverge across frameworks, and an executive summary with recommendation. Framework applicability is filtered by data availability; Kano requires customer research. Refuses to fabricate scores; produces an estimation scaffold when input data is missing.
Creates a clear problem framing document with user impact, business context, and success criteria. Use when starting a new initiative, realigning a drifted project, or communicating up to leadership.
Generates structured Given/When/Then acceptance criteria for a user story or feature slice, covering the happy path, key failure scenarios, and non-functional expectations in testable form. Use when turning requirements into verifiable scenarios for engineering handoff and QA sign-off. For a dedicated catalog of boundary conditions, error states, and recovery paths across a feature, use deliver-edge-cases; to write the stories themselves, use deliver-user-stories.
Documents edge cases, error states, boundary conditions, race conditions, and recovery paths for a feature - the systematic catalog of what can go wrong and the failure modes to design for. Use during specification to map the failure surface and ensure comprehensive coverage, or during QA planning to identify boundary and limit scenarios to test. Distinct from deliver-acceptance-criteria, which writes story-level Given/When/Then checks; this skill produces the whole-feature edge-case catalog.