NPM Publish

npm-publish

Ship a package to the npm registry with full pre-flight checks, version management, and post-publish verification.

When to Trigger

Activate this skill when the user:

• Asks to publish an npm package or ship to npm
• Wants to release a new version or cut a release
• Says "bump version and publish" or "push to registry"
• Needs to prepare a package for distribution

Pre-Flight Checks

Run every check before attempting to publish. Fail fast on any blocker.

1. Validate package.json

Verify the following fields exist and are non-empty:

If any required field is missing, report it and stop.

2. Verify .npmrc Scope

Check that .npmrc (project root or ~/.npmrc) contains:

@0xjitsu:registry=https://registry.npmjs.org/

If missing, offer to create it. Verify npm auth:

npm whoami

If not authenticated, instruct the user to run npm login.

3. Build

If package.json contains a build script:

npm run build

Fail the pipeline if the build exits non-zero. Verify the output directory (dist/, build/, etc.) exists and is non-empty.

4. Test

If package.json contains a test script (and it is not the default echo "Error: no test specified"):

npm test

Hard rule: Never publish if tests fail. No exceptions.

5. Dry-Run Pack

npm pack --dry-run 2>&1

Review the file list. Flag and halt if any of these appear:

• .env, .env.* (secrets)
• node_modules/ (bloat)
• .git/ (repository internals)
• *.pem, *.key (certificates/keys)
• credentials.json, serviceAccountKey.json (auth files)
• Any file larger than 1 MB (warn, don't halt)

Report the total packed size. Warn if over 5 MB.

Version Bump Workflow

Ask the User

Present the current version and ask:

Current version: X.Y.Z What type of release?

• patch (X.Y.Z+1) -- bug fixes, no new features
• minor (X.Y+1.0) -- new features, backward compatible
• major (X+1.0.0) -- breaking changes

Bump

npm version <patch|minor|major> --no-git-tag-version

Using --no-git-tag-version because we create the tag manually after publish succeeds.

Update CHANGELOG

Invoke the changelog-gen skill if available. If not available, prompt the user to write a changelog entry manually. The entry must exist before publishing.

Commit the Version Bump

git add package.json package-lock.json CHANGELOG.md
git commit -m "release: v<new-version>"

Publish

Execute

Ask for explicit confirmation before running:

npm publish --access public

• --access public is required for scoped packages to be publicly visible.
• Never use --force. If publish fails, diagnose and fix the root cause.
• If the version already exists on the registry, bump again -- do not force overwrite.

Create Git Tag

git tag v<version>

Push

git push origin <current-branch>
git push origin v<version>

Create GitHub Release

Write the changelog entry for this version to a temp file, then:

gh release create v<version> \
  --title "v<version>" \
  --notes-file /tmp/CHANGELOG_ENTRY.md

Clean up the temp file after.

Post-Publish Verification

Confirm on Registry

npm view @0xjitsu/<package>@latest version

Verify the returned version matches what was just published.

Test Install

TMPDIR=$(mktemp -d)
cd "$TMPDIR"
npm init -y --silent
npm install @0xjitsu/<package>@<version>

If the package has a bin entry:

npx @0xjitsu/<package> --help

Verify it runs without error. Clean up the temp directory.

Report

Print a summary:

Published: @0xjitsu/<package>@<version>
Registry:  https://www.npmjs.com/package/@0xjitsu/<package>
Git tag:   v<version>
Release:   https://github.com/0xjitsu/<repo>/releases/tag/v<version>

Safety Rules

Rollback

If something goes wrong after publish:

1. npm unpublish @0xjitsu/<package>@<version> (only within 72 hours)
2. git tag -d v<version> and git push origin :refs/tags/v<version>
3. Delete the GitHub release: gh release delete v<version> --yes
4. Revert the version bump commit if needed