skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
paldom/node-skills51 installs

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-packaging
view source ↗

Is 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

  1. Decide format from evidence, not fashion — ESM-first, not ESM-always: read package.json#engines and 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 in references/packaging-playbook.md. Dual ESM+CJS when older engines, tooling, or stated consumers demand it — with the dual-package hazard mitigation from the playbook.
  2. Write the exports map explicitly (playbook blocks for ESM-only and dual): correct types condition placement, subpath exports only for supported API, sideEffects where true.
  3. Build: tsdown as the current default (tsup acceptable with rationale) — declarations on, target matching engines.
  4. Tarball hygiene: files whitelist (never .npmignore archaeology), engines, packageManager where the repo pins one.
  5. Gate — never skip:
    bash "${CLAUDE_SKILL_DIR}/scripts/check_package.sh"
    
    (npm pack dry-run inspection + publint + arethetypeswrong — exact commands in the script; it exits non-zero on any finding.)
  6. 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.
  • engines drives everything downstream (CI matrix in node-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.

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>