npm

Publish and manage packages on the npm registry (npmjs.com), publish, dist-tags, deprecate, owners, download stats, private installs. Use when the user asks to publish, release or manage an npm packag

SKILL.md

GitHub

npm (connected)

The npm CLI is already authenticated for $NPM_REGISTRY_URL (it stands in for https://registry.npmjs.org): pass --registry "$NPM_REGISTRY_URL" on the commands that need the login, as below (the token also sits in $NPM_TOKEN for curl).

  • Who am I: npm whoami --registry "$NPM_REGISTRY_URL"
  • Inspect: npm view <PKG> · versions: npm view <PKG> versions · tags: npm view <PKG> dist-tags
  • Publish (from the package dir): npm publish --registry "$NPM_REGISTRY_URL", a scoped package's first publish needs --access public
  • Dist-tags: npm dist-tag add <PKG>@<VERSION> <TAG> --registry "$NPM_REGISTRY_URL" / npm dist-tag ls <PKG>
  • Deprecate: npm deprecate <PKG>@"<RANGE>" "<MESSAGE>" --registry "$NPM_REGISTRY_URL"
  • Owners / access: npm owner ls <PKG> · npm access list packages --registry "$NPM_REGISTRY_URL"
  • Downloads (no auth): curl -s https://api.npmjs.org/downloads/point/last-week/<PKG> | jq

2FA / one-time codes

When a write is refused with an OTP/one-time-password error, mint a code and retry in one step: npm publish --registry "$NPM_REGISTRY_URL" --otp "$(otp ${id})". Codes die within seconds: mint at the moment of use, never ahead, and never ask the user for a code before trying otp ${id}.

If otp ${id} says no TOTP secret is stored: the account is on WebAuthn. When the npmjs.com browser is connected (its skill exists beside this one), take the web path: navigate to the https://www.npmjs.com/auth/... URL the CLI prints (or the publish's approval link) in that browser; its passkey answers the 2FA step by itself. Only with neither the TOTP secret nor that browser connected do you stop and ask the user.

Failure modes worth naming

  • A 401/403 from a token that worked before is almost always an EXPIRED token (npm caps write tokens at 90 days): ask for a fresh one with capabilities request ${id} --reconnect --why "npm refuses the token (401)", which puts a masked field for it in the owner's chat and continues the conversation once it is in, rather than retrying.
  • A Bypass-2FA token may STAGE a publish for the owner to approve on npmjs.com instead of completing it: approve it in the connected npmjs.com browser, or report the staged state if that browser isn't connected.