node-packaging
Configures npm package artifacts - package.json exports maps, ESM-first vs dual format decisions, tsdown/tsup bundling, publint and arethetypeswrong gates, files whitelist, engines. Use when the user asks to package a library for npm, fix consumer import or type-resolution errors, or check publish-readiness. Not for version bumps, changelogs, releases, or registry auth.
How do I install this agent skill?
npx skills add https://github.com/paldom/node-skills --skill node-packagingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides comprehensive tools and guidance for correctly packaging Node.js libraries. It includes a security-conscious validation script that runs industry-standard linters and performs defensive checks to prevent sensitive files (such as .env or .github) from being accidentally included in published artifacts. No malicious patterns were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
node-packaging
Makes a package that installs and resolves correctly for every consumer you claim to support — module format, exports map, types, and tarball contents. The failures this skill fixes: models declare "ESM-only is fine now" without checking the consumer Node range, write exports maps whose types don't resolve, and publish tarballs full of source and CI junk.
When NOT to use
- Version bumps, changelogs, publishing, OIDC →
node-release. - Declaration emission / tsconfig →
node-typescript(this skill owns how consumers resolve what was emitted). - Dependency hygiene →
node-supply-chain.
Workflow
- Decide format from evidence, not fashion — ESM-first, not ESM-always:
read
package.json#enginesand the consumer reality.require(esm)exists only on specific Node lines and has real constraints (no top-level await in the required graph) — the support matrix and decision framework live inreferences/packaging-playbook.md. Dual ESM+CJS when older engines, tooling, or stated consumers demand it — with the dual-package hazard mitigation from the playbook. - Write the exports map explicitly (playbook blocks for ESM-only and dual):
correct
typescondition placement, subpath exports only for supported API,sideEffectswhere true. - Build: tsdown as the current default (tsup acceptable with rationale) —
declarations on, target matching
engines. - Tarball hygiene:
fileswhitelist (never.npmignorearchaeology),engines,packageManagerwhere the repo pins one. - Gate — never skip:
(npm pack dry-run inspection +bash "${CLAUDE_SKILL_DIR}/scripts/check_package.sh"publint+arethetypeswrong— exact commands in the script; it exits non-zero on any finding.) - Consumer-error diagnosis (
ERR_REQUIRE_ESM, "types not found"): playbook has the decision tree — identify the consumer's Node/module context first; options are documented support-range, genuine dual build, or exports fix. Never blind-add CJS.
Output spec
Explicit exports map; format decision written down with the engines evidence;
build emitting exactly what exports declares; files whitelist; both gates
(publint, attw) clean; npm pack --dry-run tarball reviewed. Changing format or
exports of a published package is semver-major — say so.
Gotchas
- The dual-package hazard (two module instances) is real — singleton/state packages need the playbook's mitigation or ESM-only with a documented range.
- attw failures read cryptically; the playbook maps its codes to concrete exports-map fixes.
enginesdrives everything downstream (CI matrix innode-ci, format here) — set it deliberately, never inherit it silently.- Version-gate the
require(esm)support matrix — re-verify Node ranges against nodejs.org docs at use time.
Files
references/packaging-playbook.md— require(esm) matrix, format decision framework, exports blocks, bundler status, hazard mitigations, error decision tree.scripts/check_package.sh— pack dry-run + publint + attw gate; non-zero exit on findings; degrades with a clear message when Node/npx is unavailable.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/paldom/node-skills/node-packaging">View node-packaging on skillZs</a>