list-npm-package-content

list-npm-package-content スキルの概要

list-npm-package-content が実際にできること

list-npm-package-content スキルは、npm パッケージを公開する前に、npm package tarball に実際に含まれるファイルを事前に確認するためのものです。やることは実務的で明快です。パッケージをビルドし、tarball を作成し、その中身を一覧表示し、最後に一時アーカイブを削除します。つまり、ユーザーが実際にインストールする内容をそのまま検証できます。

このスキルが特に向いているケース

このスキルは、次のような疑問に答えたいパッケージメンテナー、リリースエンジニア、ライブラリ作者に特に有効です。

• 「ビルド成果物は公開パッケージにちゃんと入っているか？」
• 「なぜ npm が source files、test fixtures、secrets まで配布しているのか？」
• 「インストール後に必要なファイルが欠けているのはなぜか？」
• 「公開済み artifact しか見えないデプロイ環境でも、このパッケージは動くのか？」

monorepo を運用している場合や、subpackages から publish している場合は、特に重要度が高まります。

このスキルの本当の役割

list-npm-package-content の価値は、単にファイル一覧を出すことではありません。npm 利用者に実際に届く packaged 結果を公開前に可視化し、リリースリスクを下げることにあります。ここで見える内容は、repository tree と一致しないことがよくあります。これは、package size の調査、build artifact の欠落、意図しないファイル漏えい、不完全な公開内容による deployment failure の切り分けで特に効いてきます。

一般的なプロンプトと何が違うのか

汎用的な AI プロンプトでも「files、.npmignore、.gitignore を確認してください」とは言えます。ただし、このスキルは config rules の説明で終わらず、最終的な tarball の実物を判断の中心に置く点が強みです。実際に重要なのは設定の意図ではなく、tarball に何が入ったかです。付属の helper script も、build → pack → inspect → clean up という具体的な手順をそのまま示してくれます。

インストール前に知っておきたい主な制約

現在の list-npm-package-content スキルは、意図的に対象を絞っています。

• npm package contents の確認に特化しており、リリース全体の妥当性までは扱いません。
• helper script は pnpm ベースの workflow を前提にしています。
• 確認したい package directory で実行する想定です。
• npm packaging のあらゆる edge case を自動で説明してくれるわけではなく、出力の解釈自体は必要です。

パッケージング全般の広いチュートリアルが欲しいなら、このスキルは絞り込みが強すぎます。反対に、公開前の高速なチェックが欲しいなら、かなり相性が良いです。

list-npm-package-content スキルの使い方

list-npm-package-content の導入前提

list-npm-package-content は、対象パッケージがすでに正常に build できる環境で使うのが前提です。repository 上の根拠を見ると、package 化の workflow は次の shell script で回されています。

bash scripts/list-package-files.sh

この script が実行するのは以下です。

• pnpm build
• pnpm pack
• 生成された tarball に対する tar -tzf
• tarball の cleanup

そのため、list-npm-package-content を使う前に、環境に pnpm、tar、そして project dependencies が揃っていることを確認してください。

最初に読むべきファイル

このスキルでは、最短で役立つ読み方は次の順番です。

1. skills/list-npm-package-content/SKILL.md
2. skills/list-npm-package-content/scripts/list-package-files.sh
3. 対象パッケージの package.json
4. 対象パッケージの .npmignore（存在する場合）
5. .npmignore がない場合は対象パッケージの .gitignore

この順番にしておくと、抽象的なガイドから始めて、最終的に出力を支配する具体的な packaging rules へ自然に降りていけます。

このスキルに渡すべき入力情報

list-npm-package-content をうまく使うには、agent に次の情報を渡すのが有効です。

• packages/ai のような package path
• 使用している package manager
• pack の前に build が必要かどうか
• 何を検証したいのか
• 気になっている suspicious files や missing files

入力は具体的なほど効果的です。「Check my package」では弱すぎます。たとえば「dist/、README.md、生成された type files が含まれているか確認し、test fixtures が除外されているかも見てほしい」のように指定すると、かなり実用的になります。

実務での呼び出しフロー

list-npm-package-content usage の実践的な進め方は、次のようになります。

1. package directory に移動する。
2. repository layout がスキルの前提と合うなら helper script を実行する。
3. tarball の file list を確認する。
4. 結果を次と照合する。
   • package.json の files
   • .npmignore
   • 想定している build output
5. packaging config を調整して再実行する。

これは一度きりのコマンドというより、反復して使うチェックループとして使うのが向いています。

スキルをうまく起動できるプロンプト例

agent へのプロンプトは、次のようにすると強くなります。

「packages/my-lib に対して list-npm-package-content を使ってください。パッケージを build し、tarball の contents を一覧化して、dist/、type declarations、README.md が含まれているか教えてください。さらに、source files、tests、env files、大きすぎる artifacts で配布すべきでないものがあれば flag してください。」

この書き方が有効な理由は次のとおりです。

• package path を明示している
• 確認したい対象が具体的
• 含まれるべきものと除外されるべきものの両方を見ている
• 単なる説明ではなく、判断につながる出力を求めている

デプロイ確認向けに強化したプロンプト

list-npm-package-content for Deployment として使う場合は、実行時要件に寄せてプロンプトを調整すると効果的です。

「packages/sdk に対して list-npm-package-content を使い、公開 tarball に CI と serverless deployment の production install に必要なファイルがすべて含まれているか検証してください。compiled output が存在すること、entry points が解決できること、runtime で local-only files に依存していないことを確認してください。」

こうすると、単純な packaging ミスよりも、built assets の欠落が原因で起きる deployment failure を拾いやすくなります。

helper script が本当に検証していること

同梱の shell script が見ているのは、宣言上の意図ではなく、最終的な packaged outcome です。実質的には次の問いを検証しています。

• build は期待どおりの artifacts を生成したか？
• pnpm pack はそれらを含めたか？
• tarball は end users が実際にダウンロードする内容と一致しているか？

repository contents と publish contents がずれているケースでは、この性質が特に役立ちます。

npm が tarball の内容を決める仕組み

このスキルを使うと、確認すべき packaging rules の優先順位がはっきり見えます。

1. package.json の files
2. .npmignore
3. .npmignore がない場合の .gitignore
4. package.json、README、LICENSE、CHANGELOG のような npm の always-included files
5. .git、node_modules、.npmrc のような npm の always-excluded paths

この優先順位は重要です。repository tree と公開パッケージが自動的に一致すると思い込んで起きる packaging bug は少なくありません。

package.json を読むだけでは足りないとき

設定ファイルを読むだけでは判断しきれないときは、list-npm-package-content を使うべきです。package.json を見れば意図は読めますが、build tooling、ignore rules、generated outputs が絡んだあとに、実際の tarball に期待したファイルが入っているかまでは分かりません。リリース確認では、config 単体よりも tarball の実物のほうが信頼できます。

実際の repository で起こりやすい調整ポイント

次のような場合は、script を多少調整する必要が出てきます。

• pnpm ではなく npm や yarn を使っている
• build command が pnpm build ではない
• build し直さずに package を確認したい
• monorepo の package path から publish している
• 環境に GNU 互換の shell tooling がない

これはスキル自体の価値を下げる話ではありませんが、list-npm-package-content install はそのまま差し込めるツールというより、workflow を取り入れるための仕組みだと考えたほうが適切です。

list-npm-package-content スキル FAQ

list-npm-package-content は初心者でも使いやすいですか

はい、基本的な package publishing の流れを理解しているなら使いやすいです。list-npm-package-content は対象が狭く、やることも具体的なので、抽象的な npm documentation に振り回されにくいのが利点です。最大のハードルは環境把握で、package directory がどこか、pack 前に build が必要かを自分で判断できる必要があります。

普通のプロンプトより、どんな問題をうまく解決できますか

実行ベースの答えが必要な場面では、list-npm-package-content のほうが普通のプロンプトより有効です。npm の rules を説明するだけでなく、実際の tarball contents に対して再現可能なチェックを行えるからです。公開前 QA や missing files のデバッグでは、こちらのほうが役に立ちます。

npm pack や npm publish の dry run を置き換えるものですか

完全な置き換えではありません。同じ packaging reality を前提にしていますが、このスキルの価値は guided workflow と script pattern にあります。別の packaging system というより、pack 周辺に信頼できる inspection routine を足すものだと考えるのが近いです。

list-npm-package-content は monorepo 専用ですか

いいえ。single-package repo でも使えます。ただし、monorepo では package boundaries、build outputs、publish roots を間違えやすいため、list-npm-package-content の価値はさらに高まります。

list-npm-package-content を使わないほうがよいのはどんなときですか

質問が npm versioning、changelog generation、registry auth、release automation に限られているなら、このスキルは向きません。また、実在する package を検査せず、files や ignore rules の概念説明だけが欲しい場合も対象外です。

デプロイのデバッグにも使えますか

はい。list-npm-package-content for Deployment は、公開パッケージに compiled files、runtime assets、declaration files が足りずに production install が失敗するケースで特に有効です。下流の環境が実際に受け取る内容を検証できます。

list-npm-package-content スキルを改善する方法

判断につながるプロンプトから始める

list-npm-package-content でより良い結果を得たいなら、判断に結びつく問い方にしてください。たとえば次のような依頼です。

• 必須の runtime files を検証する
• 想定外に配布されるファイルを検出する
• 配布内容と repo structure を比較する
• 特定のファイルが欠ける理由を説明する

単に file list を求めるより、こうした依頼のほうが結果の価値が上がります。

package path と期待する artifacts を正確に指定する

最も効果が大きい改善ポイントは、次を明示することです。

• package directory
• 期待する build output
• package entry points
• tarball に必ず存在してほしい files
• tarball に含まれてほしくない files

例:

「packages/ui に対して list-npm-package-content を実行し、dist/index.js、dist/index.d.ts、README.md が含まれていること、および src/、tests、.env files が除外されていることを確認してください。」

こうすると、曖昧な確認作業が publish validation に変わります。

tarball の内容を package entry points と照合する

よくある失敗は、「tarball にファイル自体は入っているが、main、module、exports、types が参照するものが入っていない」というパターンです。次の比較を明示的に求めると、list-npm-package-content の出力はさらに有用になります。

「packaged files を一覧化し、それらが package.json の exports と types fields が参照する paths を満たしているか検証してください。」

これで、壊れた publish をかなり早い段階で見つけられます。

config 変更後は反復的に使う

最も良い workflow は反復型です。

1. tarball を確認する
2. files や ignore rules を修正する
3. rebuild と repack を行う
4. もう一度比較する

list-npm-package-content guide の質は、最初の出力を最終回答ではなく diagnostic baseline として扱うほど上がります。

build 成功だけで安心しない

build が成功したからといって、publish が正しいとは限りません。dist/ が生成されても、tarball からは除外されていることがあります。list-npm-package-content を使うときは、「build succeeded」と「published package is complete」を分けて確認するよう agent に依頼してください。この切り分けこそ、このスキルの実価値です。

ツールが違うなら移植性を目的に調整する

repository が pnpm を使っていない場合でも、helper script の目的そのものは変えず、ロジックだけ合わせるのが基本です。

• pnpm build を自分の build command に置き換える
• pnpm pack を対応する pack command に置き換える
• tarball の listing と cleanup の手順は維持する

これで、環境に合わせながら list-npm-package-content usage の核を保てます。

まず確認したい代表的な失敗パターン

最初に見るべき典型的な問題は次のとおりです。

• dist/ が tarball に入っていない
• source files が意図せず含まれている
• test data や fixtures が配布されている
• ignore files によって必要な assets が除外されている
• README や license files が想定外に欠けている
• entry points が tarball に存在しないファイルを参照している

これらを明示して確認させると、出力は一気に実務向けになります。

列挙だけでなく理由の説明も求める

出力品質を上げるには、file list だけでなく、含まれた理由・除外された理由の推定も求めてください。たとえば次のように依頼します。

「tarball の contents を一覧化し、想定外のファイルが含まれた、または省かれた原因になった rules を説明してください。」

こうすることで、list-npm-package-content は単なる inspection から debugging support へ一段深く使えるようになります。

すべてのリリース候補前に list-npm-package-content を使う

最も実務的な改善は、運用プロセスに組み込むことです。壊れた publish のあとではなく、release candidate の前に毎回 list-npm-package-content を実行してください。軽量な preflight check として、避けられたはずの support、rollback、deployment issues を未然に防げます。