list-npm-package-content

Overview of list-npm-package-content skill

What list-npm-package-content actually does

The list-npm-package-content skill helps you inspect the exact files that would ship in an npm package tarball before you publish. Its practical job is simple: build the package, create the tarball, list the tarball contents, and remove the temporary archive so you can verify what users would actually install.

Best fit for this skill

This skill is most useful for package maintainers, release engineers, and library authors who need to answer questions like:

• “Did my build output make it into the published package?”
• “Why is npm shipping source files, test fixtures, or secrets?”
• “Why is a required file missing after install?”
• “Will this package work in deployment environments that only see published artifacts?”

If you maintain monorepos or publish from subpackages, this is especially relevant.

The real job-to-be-done

The real value of list-npm-package-content is not just printing files. It reduces release risk before publish by showing the packaged result that npm consumers receive, which is often different from your repository tree. That matters when debugging package size, missing build artifacts, accidental file leaks, and deployment failures caused by incomplete published output.

What makes it different from a generic prompt

A generic AI prompt might tell you to “check files, .npmignore, and .gitignore.” This skill is stronger because it centers the decision on the actual tarball result, not just the config rules. In practice, the tarball is what matters. The included helper script also gives a concrete workflow: build, pack, inspect, clean up.

Key constraints to know before installing

The current list-npm-package-content skill is intentionally narrow:

• It is focused on npm package contents, not full release validation.
• The helper script assumes a pnpm-based workflow.
• It expects you to run from the package directory you want to inspect.
• It does not explain every npm packaging edge case for you; you still need to interpret the output.

If you want a broad packaging tutorial, this is too focused. If you want a fast pre-publish check, it is a good fit.

How to Use list-npm-package-content skill

Install context for list-npm-package-content

Use the skill in an environment where the target package can already build successfully. The repository evidence shows the packaged workflow is driven by a shell script:

bash scripts/list-package-files.sh

That script runs:

• pnpm build
• pnpm pack
• tar -tzf on the created tarball
• cleanup of the tarball

So before using list-npm-package-content, confirm your environment has pnpm, tar, and the project dependencies available.

Read these files first

For this skill, the fastest useful reading path is:

1. skills/list-npm-package-content/SKILL.md
2. skills/list-npm-package-content/scripts/list-package-files.sh
3. The target package's package.json
4. The target package's .npmignore if present
5. The target package's .gitignore if no .npmignore exists

That order mirrors how you move from abstract guidance to the exact packaging rules that control output.

What input the skill needs from you

To use list-npm-package-content well, provide the agent with:

• the package path, such as packages/ai
• the package manager in use
• whether the package must be built before packing
• what you are trying to verify
• any suspicious files or missing files you care about

Good inputs are concrete. “Check my package” is weak. “Show whether dist/, README.md, and generated type files are included, and confirm test fixtures are excluded” is much better.

The practical invocation workflow

A practical workflow for list-npm-package-content usage looks like this:

1. Change into the package directory.
2. Run the helper script if your repo layout matches the skill.
3. Review the tarball file list.
4. Compare the result against:
   • package.json files
   • .npmignore
   • build output expectations
5. Adjust packaging config and rerun.

This is best used as a loop, not a one-off command.

Example prompt that triggers the skill well

A stronger prompt for an agent is:

“Use list-npm-package-content on packages/my-lib. Build the package, list the tarball contents, and tell me whether dist/, type declarations, and README.md are included. Flag any source files, tests, env files, or large artifacts that should probably not ship.”

Why this works:

• It names the package path.
• It states the desired inspection targets.
• It asks for both inclusion and exclusion review.
• It makes the output decision-oriented, not just descriptive.

Stronger prompts for deployment checks

For list-npm-package-content for Deployment, tailor the prompt to runtime needs:

“Use list-npm-package-content on packages/sdk and verify the published tarball contains all files needed for production install in CI and serverless deployment. Confirm compiled output exists, entry points resolve, and no local-only files are required at runtime.”

This improves results because deployment failures often come from missing built assets rather than obvious packaging mistakes.

What the helper script is really validating

The bundled shell script validates the packaged outcome, not just declared intent. It effectively asks:

• Did the build produce the expected artifacts?
• Did pnpm pack include them?
• Does the tarball match what end users will download?

That makes the skill particularly useful when repository contents and publish contents diverge.

How npm decides what appears in the tarball

The skill surfaces the key packaging rules you should inspect:

1. files in package.json
2. .npmignore
3. .gitignore when .npmignore is absent
4. npm's always-included files like package.json, README, LICENSE, CHANGELOG
5. npm's always-excluded paths like .git, node_modules, .npmrc

This hierarchy matters. Many packaging bugs come from assuming the repo tree automatically matches the published package.

When to use this instead of only reading package.json

Use list-npm-package-content when config inspection is not enough. Reading package.json can tell you intent, but not whether the built tarball actually contains the expected files after build tooling, ignore rules, and generated outputs all interact. For release verification, the tarball output is more trustworthy than the config alone.

Common adaptation needs in real repos

You may need to adapt the script if:

• your repo uses npm or yarn instead of pnpm
• your build command differs from pnpm build
• you want to inspect a package without rebuilding
• you publish from a monorepo package path
• your environment does not have GNU-compatible shell tooling

That does not reduce the value of the skill, but it does mean list-npm-package-content install is more about workflow adoption than drop-in portability.

list-npm-package-content skill FAQ

Is list-npm-package-content beginner-friendly

Yes, if you already understand basic package publishing. The skill is narrow and concrete, which helps beginners avoid abstract npm documentation. The main blocker is environment setup: you need to know where the package directory is and whether it requires a build step before packing.

What problem does this solve better than an ordinary prompt

list-npm-package-content is better than an ordinary prompt when you need an execution-oriented answer. Instead of only explaining npm rules, it gives you a reproducible check against the actual tarball contents. That is more useful for pre-publish QA and debugging missing files.

Does this replace npm pack or npm publish dry runs

Not exactly. The skill is built around the same packaging reality, but its value is the guided workflow and the included script pattern. Think of it as a reliable inspection routine around packing, not a separate packaging system.

Is list-npm-package-content only for monorepos

No. It works for single-package repos too. It becomes even more valuable in monorepos because package boundaries, build outputs, and publish roots are easier to get wrong there.

When should I not use list-npm-package-content

Skip this skill if your question is purely about npm versioning, changelog generation, registry auth, or release automation. Also skip it if you only need a conceptual explanation of files and ignore rules without inspecting a real package.

Can I use this for deployment debugging

Yes. list-npm-package-content for Deployment is a strong use case when production installs fail because the published package is missing compiled files, runtime assets, or declaration files. It helps you verify what downstream environments actually receive.

How to Improve list-npm-package-content skill

Start with a decision-focused prompt

To get better results from list-npm-package-content, ask a question that supports a decision. For example:

• verify required runtime files
• detect unexpected shipped files
• compare shipped contents to repo structure
• explain why a specific file is missing

This yields a better outcome than simply asking for a file list.

Name the exact package path and expected artifacts

The single highest-value improvement is to specify:

• package directory
• expected build output
• package entry points
• files that must exist in the tarball
• files that must not exist

Example:

“Run list-npm-package-content for packages/ui and confirm dist/index.js, dist/index.d.ts, and README.md are included, while src/, tests, and .env files are excluded.”

This turns vague inspection into publish validation.

Compare tarball output against package entry points

A common failure mode is that the tarball includes files, but not the ones referenced by main, module, exports, or types. Improve the skill output by explicitly asking for that comparison:

“List packaged files and verify they satisfy the paths referenced in package.json exports and types fields.”

That catches many broken publishes early.

Use it iteratively after config changes

The best workflow is iterative:

1. inspect tarball
2. change files or ignore rules
3. rebuild and repack
4. compare again

list-npm-package-content guide quality improves when you treat the first output as a diagnostic baseline, not the final answer.

Watch for false confidence from successful builds

A successful build does not mean a correct publish. The build may generate dist/, but your tarball can still exclude it. When using list-npm-package-content, ask the agent to separate “build succeeded” from “published package is complete.” That distinction is where the skill adds real value.

Improve portability if your tooling differs

If your repo does not use pnpm, adapt the helper script logic rather than the purpose:

• replace pnpm build with your build command
• replace pnpm pack with the equivalent pack command
• keep the tarball listing and cleanup steps

This preserves the core of list-npm-package-content usage while matching your environment.

Common failure modes to check first

The most common issues worth checking are:

• dist/ missing from the tarball
• source files included unintentionally
• test data or fixtures shipped
• ignore files excluding required assets
• README or license files missing unexpectedly
• entry points referencing files not present in the tarball

If you ask the skill to check these explicitly, the output becomes much more actionable.

Ask for explanation, not just enumeration

To improve output quality, request both the file list and the likely reason behind inclusion or exclusion. For example:

“List the tarball contents and explain which rules likely caused unexpected files to be included or omitted.”

That pushes the skill from inspection into debugging support.

Use list-npm-package-content before every release candidate

The most practical improvement is process-based: run list-npm-package-content before release candidates, not after a broken publish. It is a lightweight preflight check that can prevent avoidable support, rollback, and deployment issues.