package-publishing — Claude Code skill for npm publishing
package-publishing guides npm package metadata, ESM and CJS builds, and TypeScript declarations. Useful when preparing a library’s public entry points or publishing workflow.
MIT 119 installs ★ 29 updated 2026-08-17
npx skills add oakoss/agent-skills --skill package-publishing -a claude-codeWhat package-publishing does
The skill covers exports, main, module, and types, including conditional entry points for ESM and CJS. It also explains how to limit published files, run a build through prepublishOnly, inspect package contents with npm pack --dry-run, and enable provenance.
For a new library, exports defines its public entry points; main can support older consumers. Put types first in each export condition block so tools can resolve the declarations correctly. This skill focuses on npm package publishing, not application bundler setup or private registries.
What it helps with
- define public entry points in
package.json - prepare ESM and CJS builds for a library
- configure TypeScript declarations for export conditions
- preview package contents before publishing
- add a build check and provenance to a publish workflow
Example prompts for the agent
- Set up
exportsinpackage.jsonfor my TypeScript library with ESM and CJS. - Check which files will be included when I publish this package to npm.
- Show me how to add
prepublishOnlyand provenance to the publish workflow.
How to install package-publishing
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill package-publishing -a claude-code2Manually: put the files in place
~/.claude/skills/package-publishing/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/package-publishing/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill package-publishing -a codex2Manually: put the files in place
.agents/skills/package-publishing/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill package-publishing -a cursor2Manually: put the files in place
.cursor/skills/package-publishing/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/package-publishing2Manually: put the files in place
.github/skills/package-publishing/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill package-publishing -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/package-publishingManually: put the files in place
.devin/skills/package-publishing/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill package-publishing -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about package-publishing
How do I install package-publishing in Claude Code?
Run npx skills add oakoss/agent-skills --skill package-publishing -a claude-code. The skill file will be at ~/.claude/skills/package-publishing/SKILL.md.
What does package-publishing do?
It guides npm package metadata, ESM and CJS builds, TypeScript declarations, and publishing steps. It also covers previewing package contents with npm pack --dry-run.
Where should the types condition go in an export block?
Place types first in each export condition block. This helps tools resolve the package’s type declarations.
Source text
SKILL.md · MIT
---
name: package-publishing
description: 'npm package publishing patterns for modern TypeScript libraries. Use when configuring package.json exports, setting up dual ESM/CJS builds, or publishing to npm. Use for npm-publish, package-json, exports, main, module, types, dual-package, provenance, prepublishOnly.'
license: MIT
metadata:
author: oakoss
version: '1.0'
source: 'https://docs.npmjs.com/cli/v10/configuring-npm/package-json'
user-invocable: false
---
# Package Publishing
## Overview
Covers modern npm package authoring: `package.json` configuration with the `exports` field, dual ESM/CJS builds, TypeScript type declarations, and secure publishing workflows with provenance.
**When to use:** Configuring package entry points, setting up conditional exports, building dual-format packages, publishing scoped packages, or troubleshooting module resolution.
**When NOT to use:** Application-level bundling (Vite/webpack app configs), monorepo workspace orchestration (Turborepo/Nx), private registry setup (Verdaccio/Artifactory).
## Quick Reference
| Pattern | Field / Command | Key Points |
| ------------------- | ----------------------------------------- | ------------------------------------------------ |
| Entry point | `exports` in package.json | Replaces `main`/`module`; encapsulates internals |
| CJS fallback | `main` | Legacy consumers without `exports` support |
| ESM entry | `module` | Bundler convention; not used by Node.js |
| Type declarations | `types` condition in `exports` | Must be listed first in each condition block |
| Subpath exports | `"./utils": { ... }` | Clean public API; blocks deep imports |
| Conditional exports | `import`/`require` conditions | Toggle ESM vs CJS per consumer |
| Package type | `"type": "module"` | Makes `.js` files ESM; use `.cjs` for CommonJS |
| Side effects | `"sideEffects": false` | Enables tree-shaking in bundlers |
| Peer deps | `peerDependencies` | Shared runtime deps (React, Vue, etc.) |
| Engine constraints | `"engines": { "node": ">=18" }` | Document minimum Node.js version |
| Files allowlist | `"files": ["dist"]` | Controls what gets published to npm |
| Prepublish check | `"prepublishOnly": "npm run build"` | Ensure build runs before publish |
| Dry run | `npm pack --dry-run` | Preview package contents before publishing |
| Provenance | `--provenance` flag or trusted publishers | Cryptographic build attestation |
| Scoped publish | `--access public` | Required for first publish of scoped packages |
## Common Mistakes
| Mistake | Correct Pattern |
| -------------------------------------------------------- | ---------------------------------------------------------------------- |
| Putting `types` after `default` in exports | `types` must be the first condition in every export block |
| Missing `"./package.json"` in exports | Include `"./package.json": "./package.json"` for tooling compatibility |
| Different APIs for `import` vs `require` | Same API surface; write ESM source, transpile to CJS |
| Using `main` without `exports` for new packages | Use `exports` as the primary entry point definition |
| Forgetting `"type": "module"` with `.js` ESM output | Set `"type": "module"` or use `.mjs` extension explicitly |
| Publishing `src/` or `node_modules/` | Use `"files"` allowlist to include only `dist/` |
| No `prepublishOnly` script | Add build step to prevent publishing stale artifacts |
| Using `default` export for libraries | Prefer named exports for consistent cross-tooling behavior |
| Not testing with `npm pack` before publish | Always dry-run to verify package contents and size |
| Omitting `peerDependencies` for framework plugins | Declare shared runtime dependencies as peers |
| Publishing without provenance | Enable provenance for supply-chain transparency |
| Using `.d.ts` for CJS when package is `"type": "module"` | Use `.d.cts` for CJS type declarations, `.d.ts` or `.d.mts` for ESM |
## Delegation
- **Build tooling setup**: Use `Explore` agent to examine tsup/unbuild/rollup configs
- **Type resolution debugging**: Use `Task` agent with "Are the Types Wrong?" (`attw`)
- **Publish pipeline review**: Delegate to `code-reviewer` agent
## References
- [Package.json configuration: exports, main, types, files, engines, peerDependencies](references/package-json-config.md)
- [Build scripts, prepublishOnly, npm pack, provenance, scoped packages](references/build-and-publish.md)
- [Dual ESM/CJS builds, conditional exports, type declarations](references/dual-format.md)
© oakoss · MIT · oakoss/agent-skills