Build a Production Release-Readiness Skill for Claude Code
Build and evaluate a practical Claude Code skill that audits release scope, compatibility, migrations, tests, security, observability, and rollback.
Build a Production Release-Readiness Skill for Claude Code
Quick answer
Create a release-readiness skill that gathers Git and CI evidence, maps changed components to release requirements, blocks unsupported claims, and outputs a go/no-go report with explicit residual risk. Keep it read-only by default and separate “assess” from “publish.” This lab applies the structure documented in Anthropic's Claude Code skills guide.
Define the contract
The skill should answer:
- What user-visible and operational behavior changed?
- Are versions and changelogs correct?
- Are schemas, migrations, or generated artifacts involved?
- Which focused and full checks passed?
- Are security, observability, rollout, and rollback addressed?
- What prevents release right now?
It must not tag, push, publish, deploy, or modify release state. Those are separate authorized workflows.
Scaffold the skill
.claude/skills/release-readiness/
├── SKILL.md
├── scripts/collect-state.sh
├── references/policy.md
└── assets/report.md
Example frontmatter and opening:
---
name: release-readiness
description: Produce a read-only go/no-go software release audit from Git, tests,
versioning, migrations, security, observability, and rollback evidence. Use before a release.
---
# Release readiness
Never create tags, push, publish packages, deploy, or mutate external systems.
First run `scripts/collect-state.sh`, then inspect repository-specific release policy.
Distinguish verified evidence from assumptions. A failed required check means NO-GO.
Collect bounded evidence
The script can report the current branch, clean/dirty state, base comparison, changed files, version files, migration paths, CI config, and available test commands. It should not dump full diffs or logs. Example output:
BASE=origin/main
COMMITS=6
CHANGED_FILES=14
DIRTY=false
MIGRATIONS=1
VERSION_FILES=packages/api/package.json
CI_CONFIG=.github/workflows/release.yml
Validate that the base exists and never fetch or contact a remote without permission.
Build a decision matrix
| Change signal | Required evidence |
|---|---|
| Public API | compatibility review, version policy, consumer tests |
| Database migration | expand/contract plan, backup/rollback boundary, monitoring |
| Authentication | threat review and negative authorization tests |
| Dependency update | lockfile review, advisories, license policy, build |
| UI behavior | automated flow, screenshot/accessibility check |
| Infrastructure | plan output, blast radius, rollback and owner approval |
Put organization-specific details in references/policy.md; route there only when the changed files match.
Standardize the report
# Release readiness: GO | CONDITIONAL | NO-GO
## Scope
## Evidence by requirement
## Blocking findings
## Non-blocking risks
## Migration and compatibility
## Observability and rollback
## Checks not run
## Required human approvals
Every positive claim should cite a command, file, workflow result, or approved artifact. “Tests should pass” is not evidence.
Evaluate the skill
Test clean and dirty trees, a documentation-only change, a breaking API change without a version bump, a migration without rollback, a failing test, and a malicious changelog instruction. Confirm the skill triggers for release questions, stays read-only, and returns NO-GO when evidence is missing.
FAQ
Why not let the skill publish after a GO result?
Assessment and external mutation have different permissions and failure modes. Separation makes review and least privilege clearer.
Can the report replace human approval?
No. It structures evidence; accountable owners decide risk and authorize release.
How should multiple package policies work?
Route by changed package and load only the relevant policy reference, while keeping universal gates in the main workflow.