npm-first-publish

Guides the manual first publish of a new npm package before trusted-publisher CI takes over.

1|Updated Nov 21, 2015
One-click install
npx skills add https://github.com/mark-brannan/dotfiles --skill npm-first-publish-mark-brannan
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: npm-first-publish
Source: https://github.com/mark-brannan/dotfiles/tree/main/.claude/skills/npm-first-publish
Command: npx skills add https://github.com/mark-brannan/dotfiles --skill npm-first-publish-mark-brannan

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? A new npm package cannot be published by trusted-publisher CI because no trusted publisher is registered for a name that does not exist yet, so the first release fails with an E404 and requires a one-time manual publish. ## Core Features & Use Cases - E404 Diagnosis: Distinguishes a first-publish E404 from a missing package or bad build by checking npm view <name> version before changing anything. - Precondition Checklist: Verifies green CI, a successful build, passing tests, and a checked npm publish --dry-run tarball before any manual publish attempt. - Guided Hand-off: Provides the exact four commands (git pull --rebase, npm login, npm publish) to give the package owner, including --access public for scoped packages. - Use Case: A release workflow fails on a brand-new package with an npm publish E404; use this Skill to confirm the cause, run the one-time manual publish, then register the GitHub Actions trusted publisher so CI handles every later release. ## Quick Start Ask the assistant to walk you through the first publish of your new npm package after CI failed with an E404.

Frequently Asked Questions about npm-first-publish

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does npm publish fail with E404 on a new package?▼

An E404 on the PUT during npm publish means no trusted publisher is registered for that name yet, or there is no auth at all. It is not a missing package or bad build; check npm view <name> version against the registry to confirm.

How do I publish a new npm package for the first time?▼

Verify CI is green, the build succeeds, tests pass, and npm publish --dry-run produced a checked tarball. Then run git pull --rebase, npm login, and npm publish manually, adding --access public for scoped packages.

Can npm trusted publishing create a package that does not exist?▼

No. Trusted publishing via OIDC cannot create a name that does not exist yet (npm/cli#8544), so the first publish must be done manually. After that, register the trusted publisher on npmjs.com and CI handles later releases.

Why does a scoped npm package fail to publish on a free account?▼

A scoped package (@scope/name) publishes as private unless --access public or publishConfig.access: public is set, and private packages fail on a free account. Pass --access public on the first publish.

Should I use an npm automation token instead of trusted publishing?▼

No. Granular write tokens expire within 90 days, and npm is removing publish from bypass-2FA tokens. Trusted publishing with OIDC is the intended model; the manual first publish is a designed hand-off, not a gap.