list-npm-package-content

Überblick über den Skill list-npm-package-content

Was list-npm-package-content tatsächlich macht

Der Skill list-npm-package-content hilft dir dabei, die exakten Dateien zu prüfen, die vor dem Veröffentlichen in einem npm-Paket-Tarball landen würden. Die praktische Aufgabe ist simpel: Paket bauen, Tarball erzeugen, Inhalt des Tarballs auflisten und das temporäre Archiv wieder entfernen, damit du verifizieren kannst, was Nutzer später tatsächlich installieren.

Für wen sich dieser Skill am besten eignet

Dieser Skill ist besonders nützlich für Paket-Maintainer, Release Engineers und Library-Autoren, die Fragen beantworten müssen wie:

• „Ist mein Build-Output wirklich im veröffentlichten Paket gelandet?“
• „Warum verschifft npm Source-Dateien, Test-Fixtures oder Secrets?“
• „Warum fehlt nach der Installation eine benötigte Datei?“
• „Funktioniert dieses Paket in Deployment-Umgebungen, die nur die veröffentlichten Artefakte sehen?“

Wenn du Monorepos pflegst oder aus Subpackages veröffentlichst, ist das besonders relevant.

Der eigentliche Job-to-be-done

Der eigentliche Mehrwert von list-npm-package-content besteht nicht nur darin, Dateien auszugeben. Der Skill reduziert das Release-Risiko vor dem Publish, weil er das paketierte Ergebnis sichtbar macht, das npm-Consumer tatsächlich erhalten — und das unterscheidet sich oft vom Repository-Baum. Das ist entscheidend, wenn du Paketgröße, fehlende Build-Artefakte, versehentliche Dateilecks oder Deployment-Fehler durch unvollständige veröffentlichte Outputs debuggen musst.

Was ihn von einem generischen Prompt unterscheidet

Ein generischer AI-Prompt würde dir vielleicht sagen, du sollst files, .npmignore und .gitignore prüfen. Dieser Skill ist stärker, weil er die Entscheidung am tatsächlichen Tarball-Ergebnis ausrichtet und nicht nur an Konfigurationsregeln. In der Praxis zählt der Tarball. Das mitgelieferte Helper-Script gibt dir außerdem einen konkreten Ablauf vor: bauen, packen, prüfen, aufräumen.

Wichtige Einschränkungen vor der Installation

Der aktuelle Skill list-npm-package-content ist bewusst eng gefasst:

• Er konzentriert sich auf npm-Paketinhalte, nicht auf eine vollständige Release-Validierung.
• Das Helper-Script geht von einem pnpm-basierten Workflow aus.
• Es setzt voraus, dass du im Paketverzeichnis arbeitest, das du prüfen willst.
• Es erklärt dir nicht jeden npm-Packaging-Sonderfall; die Ausgabe musst du weiterhin selbst interpretieren.

Wenn du ein umfassendes Packaging-Tutorial suchst, ist das zu fokussiert. Wenn du einen schnellen Pre-Publish-Check brauchst, passt der Skill gut.

So verwendest du den Skill list-npm-package-content

Installationskontext für list-npm-package-content

Nutze den Skill in einer Umgebung, in der sich das Zielpaket bereits erfolgreich bauen lässt. Die Hinweise im Repository zeigen, dass der Paketierungs-Workflow über ein Shell-Script gesteuert wird:

bash scripts/list-package-files.sh

Dieses Script führt aus:

• pnpm build
• pnpm pack
• tar -tzf auf dem erzeugten Tarball
• Aufräumen des Tarballs

Bevor du list-npm-package-content verwendest, solltest du also sicherstellen, dass in deiner Umgebung pnpm, tar und die Projektabhängigkeiten verfügbar sind.

Diese Dateien solltest du zuerst lesen

Für diesen Skill ist der schnellste sinnvolle Leseweg:

1. skills/list-npm-package-content/SKILL.md
2. skills/list-npm-package-content/scripts/list-package-files.sh
3. package.json des Zielpakets
4. .npmignore des Zielpakets, falls vorhanden
5. .gitignore des Zielpakets, falls keine .npmignore existiert

Diese Reihenfolge spiegelt wider, wie du von allgemeiner Anleitung zu den konkreten Packaging-Regeln kommst, die den Output tatsächlich steuern.

Welche Eingaben der Skill von dir braucht

Um list-npm-package-content sinnvoll zu nutzen, solltest du dem Agenten Folgendes mitgeben:

• den Paketpfad, zum Beispiel packages/ai
• den verwendeten Paketmanager
• ob das Paket vor dem Packen gebaut werden muss
• was du konkret verifizieren möchtest
• welche verdächtigen oder fehlenden Dateien dich interessieren

Gute Eingaben sind konkret. „Prüf mein Paket“ ist schwach. „Zeig mir, ob dist/, README.md und generierte Typdateien enthalten sind, und bestätige, dass Test-Fixtures ausgeschlossen werden“ ist deutlich besser.

Der praktische Aufruf-Workflow

Ein praxistauglicher Workflow für list-npm-package-content usage sieht so aus:

1. Wechsle in das Paketverzeichnis.
2. Führe das Helper-Script aus, wenn dein Repo-Layout zum Skill passt.
3. Prüfe die Dateiliste des Tarballs.
4. Vergleiche das Ergebnis mit:
   • files in package.json
   • .npmignore
   • den erwarteten Build-Artefakten
5. Passe die Packaging-Konfiguration an und führe den Ablauf erneut aus.

Das funktioniert am besten als Schleife, nicht als einmaliger Befehl.

Beispiel-Prompt, der den Skill gut auslöst

Ein stärkerer Prompt für einen Agenten ist:

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

Warum das funktioniert:

• Er nennt den Paketpfad.
• Er benennt die gewünschten Prüfziele.
• Er fordert sowohl die Prüfung von Einschlüssen als auch Ausschlüssen an.
• Er macht die Ausgabe entscheidungsorientiert statt rein beschreibend.

Bessere Prompts für Deployment-Prüfungen

Für list-npm-package-content for Deployment solltest du den Prompt an die Laufzeitanforderungen anpassen:

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

Das verbessert die Ergebnisse, weil Deployment-Fehler oft durch fehlende Build-Artefakte entstehen und nicht durch offensichtliche Packaging-Fehler.

Was das Helper-Script eigentlich validiert

Das mitgelieferte Shell-Script validiert das paketierte Ergebnis, nicht nur die deklarierte Absicht. Im Kern stellt es folgende Fragen:

• Hat der Build die erwarteten Artefakte erzeugt?
• Hat pnpm pack sie aufgenommen?
• Entspricht der Tarball dem, was Endnutzer herunterladen werden?

Dadurch ist der Skill besonders nützlich, wenn sich Repository-Inhalt und Publish-Inhalt unterscheiden.

Wie npm entscheidet, was im Tarball erscheint

Der Skill macht die wichtigsten Packaging-Regeln sichtbar, die du prüfen solltest:

1. files in package.json
2. .npmignore
3. .gitignore, wenn keine .npmignore vorhanden ist
4. von npm immer eingeschlossene Dateien wie package.json, README, LICENSE, CHANGELOG
5. von npm immer ausgeschlossene Pfade wie .git, node_modules, .npmrc

Diese Hierarchie ist wichtig. Viele Packaging-Fehler entstehen, weil man annimmt, dass der Repository-Baum automatisch dem veröffentlichten Paket entspricht.

Wann du das statt nur package.json zu lesen verwenden solltest

Verwende list-npm-package-content, wenn das reine Prüfen der Konfiguration nicht ausreicht. Das Lesen von package.json zeigt dir zwar die Absicht, aber nicht, ob der gebaute Tarball nach Zusammenspiel von Build-Tooling, Ignore-Regeln und generierten Outputs tatsächlich die erwarteten Dateien enthält. Für die Release-Verifikation ist der Tarball-Output verlässlicher als die Konfiguration allein.

Typische Anpassungen in realen Repositories

Du musst das Script möglicherweise anpassen, wenn:

• dein Repo npm oder yarn statt pnpm verwendet
• dein Build-Befehl von pnpm build abweicht
• du ein Paket ohne erneuten Build prüfen möchtest
• du aus einem Monorepo-Paketpfad veröffentlichst
• deine Umgebung keine GNU-kompatiblen Shell-Tools hat

Das mindert den Wert des Skills nicht, bedeutet aber, dass list-npm-package-content install eher Workflow-Übernahme als echte Drop-in-Portabilität ist.

FAQ zum Skill list-npm-package-content

Ist list-npm-package-content anfängerfreundlich

Ja, sofern du grundlegendes Paket-Publishing bereits verstehst. Der Skill ist eng umrissen und konkret, was Einsteigern hilft, abstrakte npm-Dokumentation zu umgehen. Die größte Hürde ist das Setup der Umgebung: Du musst wissen, wo das Paketverzeichnis liegt und ob vor dem Packen ein Build-Schritt nötig ist.

Welches Problem löst das besser als ein normaler Prompt

list-npm-package-content ist besser als ein gewöhnlicher Prompt, wenn du eine ausführungsorientierte Antwort brauchst. Statt nur npm-Regeln zu erklären, liefert der Skill einen reproduzierbaren Check gegen den tatsächlichen Tarball-Inhalt. Das ist für Pre-Publish-QA und das Debuggen fehlender Dateien deutlich nützlicher.

Ersetzt das npm pack oder Dry Runs von npm publish

Nicht ganz. Der Skill basiert auf derselben Packaging-Realität, aber sein Mehrwert liegt im geführten Workflow und im mitgelieferten Script-Muster. Denk eher an eine verlässliche Inspektionsroutine rund ums Packen als an ein eigenes Packaging-System.

Ist list-npm-package-content nur für Monorepos gedacht

Nein. Er funktioniert auch für Repositories mit nur einem Paket. In Monorepos wird er noch wertvoller, weil dort Paketgrenzen, Build-Outputs und Publish-Roots leichter falsch konfiguriert werden.

Wann sollte ich list-npm-package-content nicht verwenden

Lass diesen Skill aus, wenn es dir rein um npm-Versionierung, Changelog-Erstellung, Registry-Authentifizierung oder Release-Automatisierung geht. Ebenfalls ungeeignet ist er, wenn du nur eine konzeptionelle Erklärung von files und Ignore-Regeln brauchst, ohne ein reales Paket zu prüfen.

Kann ich das für Deployment-Debugging verwenden

Ja. list-npm-package-content for Deployment ist ein starker Anwendungsfall, wenn Produktionsinstallationen scheitern, weil dem veröffentlichten Paket kompilierte Dateien, Runtime-Assets oder Deklarationsdateien fehlen. Der Skill hilft dir zu verifizieren, was nachgelagerte Umgebungen tatsächlich erhalten.

So verbesserst du den Skill list-npm-package-content

Starte mit einem entscheidungsorientierten Prompt

Um bessere Ergebnisse aus list-npm-package-content zu bekommen, stelle eine Frage, die eine Entscheidung unterstützt. Zum Beispiel:

• erforderliche Runtime-Dateien verifizieren
• unerwartet mitgelieferte Dateien erkennen
• ausgelieferte Inhalte mit der Repo-Struktur vergleichen
• erklären, warum eine bestimmte Datei fehlt

Das führt zu besseren Ergebnissen, als einfach nur nach einer Dateiliste zu fragen.

Nenne den exakten Paketpfad und die erwarteten Artefakte

Die wertvollste einzelne Verbesserung ist, konkret anzugeben:

• Paketverzeichnis
• erwarteten Build-Output
• Paket-Entry-Points
• Dateien, die im Tarball vorhanden sein müssen
• Dateien, die nicht vorhanden sein dürfen

Beispiel:

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

Damit wird aus vager Inspektion eine echte Publish-Validierung.

Vergleiche den Tarball-Output mit den Paket-Entry-Points

Ein häufiger Fehlerfall ist, dass der Tarball zwar Dateien enthält, aber nicht die, auf die main, module, exports oder types verweisen. Verbessere die Ausgabe des Skills, indem du diesen Vergleich explizit anforderst:

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

So werden viele fehlerhafte Veröffentlichungen früh erkannt.

Setze den Skill nach Konfigurationsänderungen iterativ ein

Der beste Workflow ist iterativ:

1. Tarball prüfen
2. files oder Ignore-Regeln ändern
3. neu bauen und neu packen
4. erneut vergleichen

Die Qualität eines list-npm-package-content guide steigt deutlich, wenn du die erste Ausgabe als diagnostische Baseline behandelst und nicht als endgültige Antwort.

Hüte dich vor falscher Sicherheit durch erfolgreiche Builds

Ein erfolgreicher Build bedeutet nicht automatisch ein korrektes Publish. Der Build kann dist/ erzeugen, aber dein Tarball kann es trotzdem ausschließen. Wenn du list-npm-package-content verwendest, bitte den Agenten ausdrücklich darum, zwischen „Build erfolgreich“ und „veröffentlichtes Paket vollständig“ zu unterscheiden. Genau in dieser Differenz liegt der eigentliche Mehrwert des Skills.

Verbessere die Portabilität, wenn dein Tooling abweicht

Wenn dein Repo nicht pnpm verwendet, passe die Logik des Helper-Scripts an, nicht dessen Zweck:

• ersetze pnpm build durch deinen Build-Befehl
• ersetze pnpm pack durch den entsprechenden Pack-Befehl
• behalte das Auflisten des Tarballs und die Cleanup-Schritte bei

So bleibt der Kern von list-npm-package-content usage erhalten und passt trotzdem zu deiner Umgebung.

Häufige Fehlerbilder, die du zuerst prüfen solltest

Die häufigsten Probleme, die sich zuerst zu prüfen lohnen, sind:

• dist/ fehlt im Tarball
• Source-Dateien wurden unbeabsichtigt aufgenommen
• Testdaten oder Fixtures werden mit ausgeliefert
• Ignore-Dateien schließen benötigte Assets aus
• README- oder Lizenzdateien fehlen unerwartet
• Entry-Points verweisen auf Dateien, die im Tarball nicht vorhanden sind

Wenn du den Skill ausdrücklich bittest, diese Punkte zu prüfen, wird die Ausgabe deutlich handlungsorientierter.

Bitte um Erklärung, nicht nur um Aufzählung

Um die Qualität der Ausgabe zu verbessern, fordere sowohl die Dateiliste als auch die wahrscheinliche Ursache für Einschluss oder Ausschluss an. Zum Beispiel:

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

So entwickelt sich der Skill von einer reinen Inspektion hin zu echter Debugging-Unterstützung.

Verwende list-npm-package-content vor jedem Release Candidate

Die praktischste Verbesserung ist prozessbezogen: Führe list-npm-package-content vor jedem Release Candidate aus, nicht erst nach einem fehlerhaften Publish. Das ist ein leichtgewichtiger Preflight-Check, der vermeidbare Support-, Rollback- und Deployment-Probleme verhindern kann.