list-npm-package-content

list-npm-package-content 技能概览

list-npm-package-content 实际能做什么

list-npm-package-content 技能的作用，是在你发布 npm 包之前，提前检查最终会被打进 npm package tarball 的准确文件列表。它的实际工作很直接：构建包、生成 tarball、列出 tarball 内容，然后删除临时归档文件，让你确认用户最终安装到的到底是什么。

哪些场景最适合用这个技能

这个技能最适合 package maintainer、release engineer，以及需要回答以下问题的 library author：

• “我的构建产物到底有没有进到已发布的包里？”
• “为什么 npm 把源码、test fixtures，甚至 secrets 一起发出去了？”
• “为什么安装之后缺了某个必需文件？”
• “这个包在只能拿到已发布产物的部署环境里能不能正常工作？”

如果你维护 monorepo，或者是从 subpackage 进行发布，这个技能尤其有用。

list-npm-package-content 真正解决的核心问题

list-npm-package-content 的价值，不只是把文件名打印出来。它真正降低的是发布前的风险：通过直接展示 npm 消费者实际拿到的打包结果，帮你发现它和仓库目录树之间的差异。这个差异在排查 package 体积异常、构建产物缺失、文件误泄露，以及因发布内容不完整导致的部署失败时，尤其关键。

它和普通提示词有什么不同

普通的 AI 提示词，可能只会告诉你“检查一下 files、.npmignore 和 .gitignore”。而这个技能更强的地方在于：它把判断依据放在真实的 tarball 结果上，而不是只停留在配置规则层面。实际工作里，真正重要的是 tarball 里有什么。附带的 helper script 也提供了明确可执行的流程：build、pack、inspect、clean up。

安装前需要知道的关键限制

当前的 list-npm-package-content 技能是刻意做得很聚焦的：

• 它关注的是 npm package 内容检查，不是完整的发布验证流程。
• 附带脚本默认假设你使用的是 pnpm 工作流。
• 它默认你是在想要检查的 package 目录下执行。
• 它不会替你解释所有 npm 打包边界情况；输出结果仍然需要你自己判断。

如果你想找的是一份大而全的 packaging 教程，这个技能会显得过于聚焦；但如果你想要一个发布前的快速检查手段，它就非常合适。

如何使用 list-npm-package-content 技能

list-npm-package-content 的安装与使用前提

使用这个技能时，最好确保目标 package 已经能在当前环境中成功构建。仓库里的实现证据表明，这个打包检查流程是由一个 shell script 驱动的：

bash scripts/list-package-files.sh

这个脚本会依次执行：

• pnpm build
• pnpm pack
• 对生成的 tarball 执行 tar -tzf
• 清理 tarball 文件

所以在使用 list-npm-package-content 之前，先确认你的环境里已经具备 pnpm、tar，以及项目所需依赖。

先看这些文件，效率最高

针对这个技能，最快能进入有效判断状态的阅读顺序是：

1. skills/list-npm-package-content/SKILL.md
2. skills/list-npm-package-content/scripts/list-package-files.sh
3. 目标 package 的 package.json
4. 目标 package 的 .npmignore（如果存在）
5. 如果没有 .npmignore，则看目标 package 的 .gitignore

这个顺序对应的就是你从抽象说明，逐步走到真正控制打包输出的具体规则。

使用这个技能时，你需要提供什么输入

要把 list-npm-package-content 用好，最好向 agent 提供这些信息：

• package 路径，例如 packages/ai
• 当前使用的 package manager
• 这个包在 pack 前是否必须先 build
• 你到底想验证什么
• 你特别关注哪些可疑文件或缺失文件

好的输入一定是具体的。“帮我检查一下我的包”太弱了；“确认 dist/、README.md 和生成的类型文件是否被包含，同时确认 test fixtures 被排除”会好得多。

实际可执行的调用流程

一个实用的 list-npm-package-content usage 工作流通常是这样：

1. 切换到目标 package 目录。
2. 如果你的 repo 结构与该技能匹配，运行附带的 helper script。
3. 检查 tarball 文件列表。
4. 将结果与以下内容对照：
   • package.json 里的 files
   • .npmignore
   • 预期的 build 输出
5. 调整打包配置后重新执行。

这个技能最适合当成一个循环流程来用，而不是一次性命令。

能很好触发该技能的提示词示例

一个更强的 agent 提示词可以这样写：

“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.”

之所以有效，是因为它做到了：

• 明确指定 package 路径
• 说明要重点检查的目标
• 同时要求检查“应包含”和“应排除”的内容
• 让输出面向决策，而不是只做描述

面向部署检查时，更强的提示词写法

如果是做 list-npm-package-content for Deployment，提示词要围绕运行时需求来写：

“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.”

这样效果更好，因为很多部署失败并不是明显的 packaging 错误，而是构建产物缺失导致的。

这个 helper script 真正在验证什么

附带的 shell script 验证的是最终打包结果，而不只是声明层面的意图。它本质上在回答这些问题：

• 构建是否产生了预期产物？
• pnpm pack 是否真的把这些产物打进去了？
• tarball 是否与最终用户下载到的内容一致？

也正因为如此，当 repo 内容和实际发布内容出现偏差时，这个技能特别有价值。

npm 是怎么决定哪些文件会进入 tarball 的

这个技能会把你拉回到 npm 打包最关键的几层规则上，建议重点检查：

1. package.json 中的 files
2. .npmignore
3. 如果没有 .npmignore，则看 .gitignore
4. npm 总是会包含的文件，例如 package.json、README、LICENSE、CHANGELOG
5. npm 总是会排除的路径，例如 .git、node_modules、.npmrc

这个优先级关系非常重要。很多 packaging 问题，本质上都是因为误以为仓库目录树会自动等于发布出去的包内容。

什么情况下，它比只看 package.json 更值得用

当单纯看配置已经不够时，就该用 list-npm-package-content。读取 package.json 只能告诉你“设计意图”，却不能保证在 build 工具、ignore 规则和生成文件相互作用之后，最终 tarball 里真的还有你期望的文件。做发布验证时，tarball 的实际输出比单看配置更可信。

在真实仓库里常见的适配需求

如果出现以下情况，你可能需要对脚本做适配：

• repo 用的是 npm 或 yarn，不是 pnpm
• 你的构建命令不是 pnpm build
• 你想检查某个 package，但不希望重新构建
• 你是在 monorepo 的某个 package 路径下发布
• 你的环境没有 GNU 兼容的 shell 工具

这并不会降低这个技能本身的价值，但也说明 list-npm-package-content install 更像是对工作流的接入，而不是即插即用的跨环境脚本。

list-npm-package-content 技能 FAQ

list-npm-package-content 对新手友好吗

友好，前提是你已经理解基本的 package 发布流程。这个技能本身足够聚焦，也足够具体，反而能帮助新手避开过于抽象的 npm 文档。真正的门槛主要在环境准备：你需要知道 package 目录在哪，以及它在 pack 之前是否需要先 build。

它比普通提示词更擅长解决什么问题

当你需要的是可执行、可复现的检查结果时，list-npm-package-content 会比普通提示词更强。它不只是解释 npm 规则，而是让你对真实 tarball 内容进行检查。对于发布前 QA 和缺失文件排查，这种方式更有用。

它能替代 npm pack 或 npm publish 的 dry run 吗

不完全是。这个技能依然建立在同一套 npm 打包现实之上，但它的价值在于：提供了带步骤的工作流，以及一个可复用的脚本模式。更准确地说，它是围绕 pack 构建的一套可靠检查流程，而不是另起一套独立的 packaging 系统。

list-npm-package-content 只适合 monorepo 吗

不是。单 package 仓库同样适用。只是在 monorepo 里，它通常更有价值，因为 package 边界、构建产物和 publish 根目录更容易出错。

什么情况下不该用 list-npm-package-content

如果你的问题只和 npm version 管理、changelog 生成、registry 鉴权，或者 release automation 有关，那就不适合用这个技能。如果你只想理解 files 和 ignore 规则的概念，而并不打算检查一个真实 package，它也不是最合适的选择。

我能把它用于部署排障吗

可以。list-npm-package-content for Deployment 是一个很强的使用场景，尤其适合排查生产安装失败：例如已发布 package 缺少编译后的文件、运行时资源或 declaration files。它能帮你确认下游环境实际拿到的到底是什么。

如何提升 list-npm-package-content 技能的使用效果

从“面向决策”的提示词开始

想让 list-npm-package-content 给出更有价值的结果，先把问题问成一个支持决策的问题。例如：

• 验证运行时必需文件是否齐全
• 识别是否意外发布了不该带上的文件
• 对比已发布内容与 repo 结构的差异
• 解释某个特定文件为什么缺失

这会比单纯要求“列出文件列表”更有产出。

明确写出 package 路径和预期产物

提升效果最明显的一点，就是把这些信息写清楚：

• package 目录
• 预期的构建输出
• package entry points
• tarball 中必须存在的文件
• tarball 中绝对不该出现的文件

例如：

“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.”

这样就把模糊的“看看包内容”变成了真正的发布验证。

把 tarball 输出和 package 入口定义对照起来看

一个常见失败模式是：tarball 里确实有文件，但并不是 main、module、exports 或 types 指向的那些文件。要提升这个技能的输出质量，可以明确要求做这一步比对：

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

这能提前发现很多“能发出去但实际不可用”的发布问题。

在每次改完配置后迭代使用

最佳工作流是迭代式的：

1. 检查 tarball
2. 修改 files 或 ignore 规则
3. 重新 build 和 repack
4. 再次对比结果

当你把第一次输出当成诊断基线，而不是最终结论时，list-npm-package-content guide 的实际效果会明显更好。

不要被“构建成功”带来的假象误导

build 成功，不代表 publish 正确。构建过程可能确实生成了 dist/，但 tarball 依然可能把它排除掉。使用 list-npm-package-content 时，最好明确要求 agent 区分“build succeeded”和“published package is complete”。这正是这个技能真正能产生价值的地方。

如果工具链不同，优先改脚本逻辑，不要改目标

如果你的 repo 不使用 pnpm，应该适配的是 helper script 的逻辑，而不是改变这个技能的目标：

• 用你的构建命令替换 pnpm build
• 用等价的 pack 命令替换 pnpm pack
• 保留 tarball 列表和清理步骤

这样既保住了 list-npm-package-content usage 的核心思路，也能贴合你的实际环境。

优先检查这些常见失败模式

最值得优先排查的问题通常包括：

• dist/ 没有进入 tarball
• 源码文件被意外包含
• test data 或 fixtures 被一起发布
• ignore 文件把必需资源排除了
• README 或 license 文件意外缺失
• entry points 指向了 tarball 中并不存在的文件

如果你在提示词里明确要求检查这些点，输出会更容易直接落地。

不只让它列举文件，还要让它解释原因

想进一步提升输出质量，可以同时要求它给出文件列表和“为什么会被包含/排除”的可能原因。例如：

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

这样一来，这个技能就不只是做检查，而是开始真正帮助你排障。

在每个 release candidate 之前都跑一次 list-npm-package-content

最实用的改进，其实是流程上的：不要等发布坏了再查，而是在每个 release candidate 之前都运行一次 list-npm-package-content。这是一个很轻量的 preflight check，但往往能提前避免很多本可避免的支持成本、回滚和部署问题。