list-npm-package-content_skill

Overview

This skill lists the exact contents of an npm package tarball before publishing. It builds the package, creates the npm tarball, prints the files that would be published, and then cleans up the temporary artifacts. Use it to verify what end users will receive and to catch accidental or missing files before running npm publish.

How this skill works

The script runs from the package directory, builds the package, and creates a tarball using npm packing tooling. It extracts and lists the tarball entries to show the precise set of files included. The process respects package.json 'files', .npmignore, .gitignore (when .npmignore is absent), and npm's always-included or always-excluded defaults.

When to use it

• Before publishing a new version to verify included files
• When debugging unexpected files being uploaded to npm
• To confirm build output and distribution artifacts are present
• When preparing a minimal package and checking .npmignore/files settings
• During CI to assert package contents match expectations

Best practices

• Run the script from the package directory (e.g., packages/ai) so paths match the published tarball
• Ensure your build step runs first so generated artifacts are included in the listing
• Use the package.json 'files' field to explicitly allow files and keep .npmignore minimal
• Rely on .npmignore for exclusions; remember .gitignore is used only if .npmignore is absent
• Treat listed always-included files (package.json, README, LICENSE, CHANGELOG) as required in the package

Example use cases

• Confirm transpiled JS and type declarations are included before publishing a TypeScript package
• Detect accidental inclusion of source tests, large assets, or local configs that bloat the package
• Validate CI pipeline output by adding the script as a step that fails on unexpected files
• Compare package contents across versions to ensure breaking changes didn't remove important files