Release Agent Skill

Coordinate one Agent Skill from verified source through package publication, namespaced GitHub release, optional catalog sync, and independent consumer verification.

Release Agent Skill gives an AI coding agent an explicit state machine for end-to-end Agent Skill shipment. It coordinates metadata, repository readiness, portable installer tests, archive inspection, npm publication, tags, release notes, GitHub releases, catalogs, and final readback while specialist skills own the details of their stage.

The orchestrator never turns “prepare” into permission to publish. Every external channel remains separately authorized and a completed mutation is not called verified until provider or consumer evidence matches it.

npx --yes --package=release-agent-skill@latest release-agent-skill --target codex

npm package · source · issues

Use it when

• One Agent Skill needs an end-to-end Git, GitHub, npm, release, and optional catalog shipment.
• A partial release must resume without repeating immutable or already verified stages.
• Host compatibility, package contents, release identity, and authorization must be tracked together.
• A final answer must distinguish ready, authorized, completed, verified, and blocked stages.

Use a specialist directly for a single job: fix-project-metadata-mismatches, make-project-github-ready, publish-verified-github-release, update-skillfolio-catalog, or verify-github-npm-release.

Install and invoke

Node.js 18 or newer is required for local validation. Publication may also require Git, authenticated GitHub access, npm authentication, and destination-specific tools.

npx --yes --package=release-agent-skill@latest release-agent-skill \
  --target codex --scope project

The shared installer supports Codex, Claude Code, Gemini CLI, Google Antigravity, Antigravity CLI, ZCode, Cursor, GitHub Copilot, and OpenCode. Use --target all or an exact --path as needed.

Prepare only:

Use $release-agent-skill to prepare package version 0.2.0, validate every installer target, inspect the archive, and draft release notes. Do not commit, push, publish, tag, or release.

End-to-end shipment:

/release-agent-skill Ship package-name 0.2.0 to npm and GitHub, update the local Skillfolio catalog, and verify every authorized stage.

Release state model

| State | Meaning | | --- | --- | | pending | Required but not yet assessed | | ready | Local evidence satisfies the stage gate | | authorized | The exact external mutation is approved | | completed | The action returned success but still needs independent readback | | verified | Registry, GitHub, CI, installer, or catalog evidence matches the release identity | | blocked | A prerequisite, permission, identity conflict, or failed check prevents progress |

Every requested stage receives one state. A later successful step never hides an earlier unverified or failed step.

Gate sequence

1. Skill contract: directory/frontmatter identity, trigger description, workflow, resources, scripts, and output are structurally valid.
2. Host compatibility: portable SKILL.md behavior is separated from host-specific presentation and every advertised install target is tested.
3. Repository state: branch, remote, version, URLs, install commands, license, tests, and user changes agree.
4. Package state: name/version are unused, the exact archive is safe, and a clean packed-artifact install works.
5. Release state: immutable namespaced tag targets the reviewed commit and notes contain only verified claims.
6. Consumer verification: npm exact version and dist-tag, clean invocation, GitHub release, CI, and authorized catalog surfaces match.

Namespaced skill tags use:

<package-name>-v<package-version>

Run the structural preflight

node /absolute/skill/root/scripts/preflight.mjs /absolute/project/root --json

The preflight is an early structural gate. It does not query npm or GitHub, inspect the final archive, run project tests, check CI, or prove release readiness.

Specialist routing

| Stage | Specialist | Evidence expected | | --- | --- | --- | | Identity, version, URLs, install commands | fix-project-metadata-mismatches | Authorities and derived files agree | | GitHub/community readiness | make-project-github-ready | Local readiness plus authorized remote readback | | Release notes and GitHub release | publish-verified-github-release | Evidence-backed notes and verified release state | | Local Skillfolio synchronization | update-skillfolio-catalog | Authorities, projection, routes, and app checks agree | | Final release audit | verify-github-npm-release | Critical release checks return evidence-backed passes |

The orchestrator directly owns stage order, authorization, package archive inspection, npm publication gating, partial-failure recovery, and final handoff.

Publication behavior

• Existing npm versions are immutable; a collision blocks publication and requires a new version decision.
• npm web authentication or OTP stays in the official flow and is never pasted into project files or logs.
• A successful npm publish is immediately checked through public registry metadata and a clean consumer path.
• Tags point to the reviewed release commit and are never silently moved.
• Catalog deployment remains separate from a local catalog update.
• If npm succeeds but a later stage fails, the immutable published artifact is reported before any retry.

Bundled resources and installer

release-agent-skill/
├── SKILL.md
├── agents/openai.yaml
├── references/release-gates.md
└── scripts/preflight.mjs

Use --scope user|project, --dry-run, --force, --migrate, a provider list, or --path. Installation performs no release action.

Develop and verify

git clone https://github.com/montasim/skills.git
cd skills
npm ci
npm test --workspace skills/release-agent-skill
npm run pack:check --workspace skills/release-agent-skill

Limits and safety

• The orchestrator cannot replace missing registry ownership, GitHub permissions, or destination authentication.
• It never weakens tests, deletes user changes, rewrites history, or bypasses registry safeguards to make a release pass.
• Network propagation and external caches are reported as limitations rather than silently treated as success.

Support, contribution, and license

Use GitHub Issues for reproducible defects. Follow the repository support, contribution, and security guidance.

Built and maintained by Montasim. Optional SupportKori funding supports release compatibility work. Licensed under the MIT License.