list-npm-package-content

list-npm-package-content skill 概覽

list-npm-package-content 實際在做什麼

list-npm-package-content skill 可協助你在發佈前檢查 npm package tarball 最終會包含哪些檔案。它的實際工作很直接：先 build 套件、建立 tarball、列出 tarball 內容，最後刪除暫存封存檔，讓你能確認使用者實際安裝到的會是什麼。

這個 skill 最適合哪些情境

這個 skill 特別適合 package 維護者、release engineer，以及需要回答以下問題的函式庫作者：

• 「我的 build 輸出有真的進到發佈套件裡嗎？」
• 「為什麼 npm 把 source files、test fixtures 或 secrets 一起打包出去了？」
• 「為什麼安裝後缺少必要檔案？」
• 「這個 package 在只能看到已發佈 artifacts 的部署環境中，真的能正常運作嗎？」

如果你維護 monorepo，或是從 subpackage 發佈，這個 skill 會特別有幫助。

list-npm-package-content 真正要解決的工作

list-npm-package-content 的價值不只是把檔案列出來。它真正能做的是在發佈前降低 release 風險：直接把 npm 使用者實際收到的打包結果攤開來看，而那往往和你的 repository tree 不完全一樣。這對於排查 package 體積過大、build artifacts 缺失、意外洩漏檔案，以及因已發佈內容不完整而導致的部署失敗，都很關鍵。

它和一般泛用 prompt 有什麼不同

一般的 AI prompt 可能只會告訴你去檢查 files、.npmignore 與 .gitignore。list-npm-package-content 更強的地方在於：它把判斷依據放在實際 tarball 結果，而不是只看設定規則。實務上，真正重要的是 tarball 裡面有什麼。內附的 helper script 也提供了具體可重複的流程：build、pack、inspect、clean up。

安裝前要先知道的關鍵限制

目前的 list-npm-package-content skill 刻意維持在明確且聚焦的範圍：

• 它專注在 npm package 內容檢查，不是完整的 release 驗證流程。
• helper script 預設以 pnpm 為基礎工作流程。
• 它預期你會在想檢查的 package 目錄中執行。
• 它不會替你解釋每一種 npm packaging 邊界情況；你仍然需要自己判讀輸出結果。

如果你要的是一份完整的 packaging 教學，這個 skill 會太聚焦；但如果你要的是快速的發佈前檢查，它就很適合。

如何使用 list-npm-package-content skill

list-npm-package-content 的安裝與使用前提

請在目標 package 已能成功 build 的環境中使用這個 skill。從 repository 內容可以看出，這個打包檢查流程是由 shell script 驅動：

bash scripts/list-package-files.sh

這個 script 會執行：

• pnpm build
• pnpm pack
• 對產生的 tarball 執行 tar -tzf
• 清除 tarball

因此，在使用 list-npm-package-content 前，請先確認你的環境已具備 pnpm、tar，以及專案所需依賴。

先讀這些檔案最快

對這個 skill 來說，最快進入狀況的閱讀順序是：

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

這個順序對應的是：從抽象指引一路走到實際控制輸出的 packaging 規則。

list-npm-package-content 需要你提供哪些輸入

想把 list-npm-package-content 用好，請提供 agent 以下資訊：

• package 路徑，例如 packages/ai
• 目前使用的 package manager
• package 在 pack 之前是否必須先 build
• 你想驗證的是什麼
• 你特別在意哪些可疑檔案或缺失檔案

輸入越具體越好。「幫我檢查 package」太模糊；「確認 dist/、README.md 和產生的 type files 是否有被包含，並確認 test fixtures 有被排除」會好得多。

list-npm-package-content 的實際操作流程

一個實用的 list-npm-package-content usage 流程大致如下：

1. 切換到 package 目錄。
2. 如果你的 repo 結構符合這個 skill，執行 helper script。
3. 檢查 tarball 檔案清單。
4. 把結果和以下項目對照：
   • package.json 的 files
   • .npmignore
   • build 輸出預期
5. 調整 packaging 設定後再重新執行。

這個 skill 最適合用迭代方式操作，而不是只跑一次就結束。

能有效觸發 list-npm-package-content 的 prompt 範例

更好的 agent prompt 可以像這樣：

「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 路徑
• 清楚說明想檢查的目標
• 同時要求檢查有被包含與應該被排除的項目
• 讓輸出聚焦在決策，而不只是描述現象

用於部署檢查時，prompt 要更精準

如果是 list-npm-package-content for Deployment，prompt 應該依執行環境需求調整：

「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 錯誤，而是缺少 build 後資產所造成。

helper script 實際驗證的是什麼

內附的 shell script 驗證的是最終打包結果，而不只是宣告上的設定。它實際在回答的是：

• build 是否產生了預期 artifacts？
• pnpm pack 是否真的把它們打進去？
• tarball 內容是否和終端使用者實際下載到的一致？

當 repository 內容與實際發佈內容出現落差時，這正是 list-npm-package-content 特別有價值的地方。

npm 是怎麼決定 tarball 會包含哪些內容的

這個 skill 會把你該檢查的關鍵 packaging 規則凸顯出來：

1. package.json 中的 files
2. .npmignore
3. 當沒有 .npmignore 時，改看 .gitignore
4. npm 一律會包含的檔案，例如 package.json、README、LICENSE、CHANGELOG
5. npm 一律會排除的路徑，例如 .git、node_modules、.npmrc

這個優先順序很重要。很多 packaging 問題，都是因為誤以為 repo tree 會自動等同於實際發佈內容。

什麼時候該用 list-npm-package-content，而不是只看 package.json

當你光看設定還不足以做判斷時，就該用 list-npm-package-content。讀 package.json 可以知道意圖，但無法保證在 build 工具、ignore 規則與產生檔案彼此交互作用後，最終 tarball 真的包含你預期的內容。若是做 release 驗證，tarball 輸出比單看設定更可信。

真實 repo 中常見的調整需求

以下情況下，你可能需要調整 script：

• repo 使用的是 npm 或 yarn，不是 pnpm
• build 指令不是 pnpm build
• 你想在不重新 build 的情況下檢查 package
• 你是從 monorepo 的 package 路徑發佈
• 你的環境不具備相容 GNU 的 shell tooling

這不會降低 list-npm-package-content 的價值，但也表示 list-npm-package-content install 更偏向導入一套工作流程，而不是拿來就能完全無痛使用。

list-npm-package-content skill 常見問題

list-npm-package-content 對初學者友善嗎

算是友善，只要你已經理解基本的 package 發佈概念。這個 skill 範圍明確、內容具體，對初學者來說比抽象的 npm 文件更容易上手。主要門檻在環境準備：你需要知道 package 目錄在哪裡，以及 pack 之前是否需要先 build。

它比一般 prompt 更擅長解決什麼問題

當你需要的是可執行、可重現的答案時，list-npm-package-content 會比一般 prompt 更好。它不只解釋 npm 規則，而是直接對實際 tarball 內容做檢查。這對發佈前 QA，以及排查缺檔問題都更有幫助。

它能取代 npm pack 或 npm publish dry run 嗎

不完全是。這個 skill 本來就建立在同一套 packaging 現實之上，但它的價值在於有引導性的工作流程與內附的 script 模式。比較貼切的理解是：它是一套圍繞 packing 的可靠檢查流程，而不是另一套獨立的 packaging 系統。

list-npm-package-content 只能用在 monorepo 嗎

不是。單一 package repo 也能用。不過在 monorepo 中它通常更有價值，因為那類環境更容易在 package 邊界、build 輸出與發佈根目錄上出錯。

什麼情況下不該用 list-npm-package-content

如果你的問題純粹是 npm versioning、changelog 產生、registry 認證，或 release automation，就不適合用這個 skill。若你只想了解 files 和 ignore 規則的概念，而不打算檢查真實 package，這個 skill 也不是最佳選擇。

可以用 list-npm-package-content 做部署除錯嗎

可以。list-npm-package-content for Deployment 是很強的使用情境，特別是在 production install 失敗，而原因是已發佈 package 缺少 compiled files、runtime assets 或 declaration files 時。它能幫你確認下游環境實際拿到的是什麼。

如何改進 list-npm-package-content skill 的使用效果

先從以決策為導向的 prompt 開始

想讓 list-npm-package-content 的結果更好，請先提出能支撐決策的問題。例如：

• 驗證必要的 runtime files
• 找出不該被打包出去的檔案
• 比較已發佈內容與 repo 結構
• 解釋某個特定檔案為何遺失

這會比單純要求列出檔案清單更有效。

明確指出 package 路徑與預期 artifacts

最有價值的改進，就是把以下資訊講清楚：

• package 目錄
• 預期的 build 輸出
• 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 entry points 對照

一種很常見的失敗模式是：tarball 裡有檔案，但不是 main、module、exports 或 types 所引用的那些檔案。想提升輸出品質，可以明確要求做這個比對：

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

這能提早抓出很多發佈後才會爆出的問題。

在修改設定後反覆使用 list-npm-package-content

最佳做法是走迭代流程：

1. 檢查 tarball
2. 修改 files 或 ignore 規則
3. 重新 build 並 repack
4. 再比較一次

當你把第一次輸出當成診斷基線，而不是最終答案時，list-npm-package-content guide 的實用性會更高。

不要因為 build 成功就產生錯誤信心

build 成功，不代表發佈內容正確。你的 build 也許真的產生了 dist/，但 tarball 還是可能把它排除掉。使用 list-npm-package-content 時，請要求 agent 明確區分「build succeeded」和「published package is complete」。這個差異正是這個 skill 最有價值的地方。

如果工具鏈不同，就調整可攜性而不是改變目的

如果你的 repo 不使用 pnpm，請調整 helper script 的邏輯，而不是改變這個 skill 的目的：

• 把 pnpm build 換成你的 build 指令
• 把 pnpm pack 換成等效的 pack 指令
• 保留列出 tarball 與清理封存檔的步驟

這樣就能在符合你環境的前提下，保留 list-npm-package-content usage 的核心價值。

先檢查這些最常見的失敗模式

最值得優先檢查的問題通常是：

• tarball 裡缺少 dist/
• 不小心把 source files 一起打包出去
• test data 或 fixtures 被發佈
• ignore 檔把必要資產排除了
• README 或 license 檔意外缺失
• entry points 指向 tarball 中不存在的檔案

如果你在 prompt 中明確要求檢查這些項目，輸出就會更具操作性。

不只要列舉，也要要求解釋原因

想提高輸出品質，請同時要求列出檔案清單，並解釋哪些規則可能導致包含或排除。例如：

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

這會讓 list-npm-package-content 從單純檢查，升級成可用於除錯的支援工具。

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

最實際的改進，其實是把它納入流程：在每個 release candidate 前執行 list-npm-package-content，而不是等發佈壞掉之後才補救。這是一個成本很低的 preflight check，能避免很多其實可以預先發現的支援、回滾與部署問題。