AI Builder - NPM Publish

This skill provides a repeatable process for publishing packages to the npm registry with proper metadata, versioning, and safeguards.

When to Use This Skill

• •You need to publish a new or updated npm package
• •You want a standard preflight checklist for npm releases
• •You need guidance on npm CLI steps and package metadata

Your Roles in This Skill

• •DevOps Engineer: Ensure release process, tags, and automation readiness
• •Backend Developer (Engineer): Validate package structure and metadata correctness
• •Technical Writer: Verify README and release notes expectations

Role Communication

As an expert in your assigned roles, you must announce your actions before performing them using the following format:

As a {Role, and Role-XYZ if have more roles}, I will {action description}

This communication pattern ensures transparency and allows for human-in-the-loop oversight at key decision points.

Instructions

Follow these steps in order:

Step 1: Confirm prerequisites and access

• •Verify required tools are installed and versions are visible.
• •Ensure npm account access works from the CLI.
• •If missing prerequisites, stop and resolve before continuing.

Step 2: Validate package metadata and repository links

• •Confirm package.json includes required fields and correct naming.
• •Ensure repository, homepage, and issues metadata point to the correct GitHub URLs.
• •Ensure README exists and meets the minimum content expectation.

Step 3: Control published files

• •Use the files field or .npmignore to exclude non-release content.
• •Double-check the package tarball content before publishing.

Step 4: Apply semantic versioning

• •Choose patch/minor/major based on the change impact.
• •Use npm version to update metadata and create the git tag.
• •Ensure the branch matches the expected release branch.

Step 5: Publish to npm

• •Run a dry run with npm pack.
• •Publish with correct access flags (especially for scoped packages).
• •Verify the published package is visible on npm.

Step 6: Post-publish management

• •Add owners or deprecate as needed.
• •Handle unpublish within the allowed window if necessary.

Expected Output

• •A published npm package with correct metadata, version, and README content
• •A clear audit trail via git tags and release notes
• •Confidence the package content matches the intended release

Key Principles

• •Prefer scoped packages when possible
• •Never publish secrets
• •Always validate metadata and README before release
• •Use dry runs to verify package contents

Common Issues

• •403 errors from version conflicts or missing access flags
• •402 errors for scoped packages published without --access public

References

• •For detailed commands, checks, and error handling, see references/npm-publish.md