pi-web/.agents/skills/npm-release-via-github-actions/SKILL.md

name, description

name

description

npm-release-via-github-actions

Use this skill whenever the user asks for a new npm version, npm release, package release, new release, version bump, publishing to npm, cutting a GitHub release, tagging a release, or anything similar. It publishes through GitHub Actions and GitHub Releases, not from the local machine, and uses Changesets to generate CHANGELOG.md/release notes. Trigger even for casual phrasing like "ship a release", "bump npm", "publish the package", or "make a new version".

Publish npm packages via GitHub Actions

The user explicitly does not want local npm publishing. For release requests, route publishing through the repository's GitHub Actions workflow, usually triggered by a published GitHub Release.

This project also uses Changesets for changelog generation. Release prep should consume .changeset/*.md fragments into CHANGELOG.md before the GitHub Release is created.

Core rules

Do not publish from the local machine.

Avoid these commands unless the user explicitly overrides this skill for an unusual emergency:

• npm publish
• npm run publish:npm
• pnpm publish, yarn publish, or equivalent package-manager publish commands
• any local publish workaround after a GitHub Actions problem

It is OK to run local safety checks and release-prep commands that do not publish, such as:

• npm run verify
• npm run build
• npm run pack:dry
• npm run changelog:status
• npm run release:version
• npm version <version> --no-git-tag-version when an exact custom version needs to be enforced

First inspect the repository release setup

Before acting, read:

1. package.json for package name, current version, scripts, and package manager.
2. package-lock.json, pnpm-lock.yaml, or yarn.lock if present, so version bumps keep lockfiles consistent.
3. .changeset/config.json and pending .changeset/*.md files, if present.
4. .github/workflows/publish.yml or similarly named release workflow.

Confirm the workflow publishes on GitHub, preferably from one of these triggers:

on:
  release:
    types: [published]
  workflow_dispatch:

For the pi-web repository, the expected workflow is .github/workflows/publish.yml; it publishes with npm publish --access public --provenance from GitHub Actions. Use the GitHub Release path by default.

If there is no GitHub Actions publish workflow, stop and explain that one must be added or fixed. Do not fall back to local npm publish.

Standard release workflow

1. Check repo state

   • Run git status --short --branch.
   • Ensure you are on the intended branch, usually main.
   • If there are unrelated or user-owned uncommitted changes, pause and ask before including, stashing, or working around them.
   • Pull/rebase only when it is safe and the user has not left local work that could be disrupted.

2. Review pending changesets

   • Run:

     npm run changelog:status
     

   • Inspect .changeset/*.md files.
   • If there are no changesets but there are user-visible changes to release, pause and ask whether to add a changeset. Do not create a low-quality release note just to proceed.
   • If changesets exist, make sure their text is user-facing and their bump types are plausible.

3. Choose or confirm the new version

   • If the user gave an exact version, use it.
   • If they asked for patch, minor, major, or similar, compute/confirm the next compatible version.
   • If the repository uses a custom scheme, preserve it. For example, pi-web uses versions like 1.202605.3; a routine next release in the same month should increment the final component unless the user says otherwise.
   • Changesets uses semver bump types. For routine pi-web releases, patch changesets normally produce the desired final-component increment.
   • If uncertain, ask for confirmation before changing files.

4. Generate changelog and version files

   • Prefer the Changesets version step:

     npm run release:version
     

   • This consumes pending .changeset/*.md fragments, updates CHANGELOG.md, updates package.json, and updates the npm lockfile when applicable.
   • Review the generated CHANGELOG.md section. It should be suitable for GitHub Release notes.
   • If the user requested an exact version and Changesets produced a different version, adjust carefully:

     npm version <new-version> --no-git-tag-version
     

     Then update the generated CHANGELOG.md heading to match the exact version. This manual changelog edit is acceptable during release prep; normal development should use changeset fragments instead.
   • Do not use plain npm version <new-version> because it creates a local git tag as a side effect; releases should be controlled via GitHub.

5. Run checks before creating the release

   • Run the repository's normal verification commands, for example:

     npm run verify
     npm run build
     npm run pack:dry
     

   • If checks fail, fix the issue or report it. Do not create the GitHub Release until the release commit is sound.

6. Commit and push the release prep

   • Commit only intended release changes. Typical files include:
     • package.json
     • package-lock.json
     • CHANGELOG.md
     • consumed/deleted .changeset/*.md fragments
   • Use:

     git add package.json package-lock.json CHANGELOG.md .changeset
     git commit -m "chore(release): v<new-version>"
     git push origin main
     

   • If there are other intentional changes required for the release, include them deliberately and mention them.

7. Create a GitHub Release to trigger publishing

   • Prefer release notes from the generated changelog instead of generic generated notes.
   • Extract the new version's section from CHANGELOG.md into a temporary notes file if useful.
   • Use the pushed commit on main as the target:

     gh release create v<new-version> \
       --target main \
       --title "v<new-version>" \
       --notes-file /tmp/pi-web-release-notes-v<new-version>.md
     

   • If a clean notes file is not practical, --generate-notes is acceptable, but prefer the Changesets-generated text because it is curated.
   • Creating a non-draft published release triggers on: release: types: [published].
   • If the user specifically wants to review notes first, create a draft release, then publish it through GitHub when approved. Remember: draft creation will not trigger publishing until it is published.

8. Monitor GitHub Actions

   • Find the publish run:

     gh run list --workflow publish.yml --limit 5
     

   • Watch it:

     gh run watch <run-id>
     

   • If it fails, inspect logs:

     gh run view <run-id> --log-failed
     

   • Fix by committing and creating a new release/tag if needed, or rerun the failed GitHub Actions job when the failure is transient. Do not publish locally as a workaround.

9. Verify npm registry publication

   • After the workflow succeeds, verify:

     npm view <package-name> version
     npm view <package-name>@<new-version> dist.tarball
     

   • If npm has not updated yet, wait briefly and check again.

Reruns and special cases

• If a GitHub Actions publish run failed due to a transient infrastructure issue, prefer gh run rerun <run-id> --failed or rerun the workflow in GitHub.
• If using workflow_dispatch, pass the intended ref/tag explicitly where possible:

  gh workflow run publish.yml --ref v<version>
  

  Use this mainly for reruns or repositories designed around manual dispatch. For normal releases, prefer a published GitHub Release.
• If the npm version already exists, npm will reject publishing. Bump to a new version and create a new release; do not try to overwrite an existing npm version.
• If a GitHub Release/tag was created incorrectly, fix it on GitHub with care and tell the user exactly what changed.
• Never use local npm publish as a workaround for a GitHub Actions or npm provenance issue.

Final response format

After completing or attempting a release, summarize concisely:

• Version requested/released
• Changelog source: generated CHANGELOG.md section or other notes used
• Commit hash and pushed branch
• GitHub Release URL
• GitHub Actions run URL and status
• npm verification result, if published
• Any follow-up needed from the user