list-npm-package-content

Vue d’ensemble de la skill list-npm-package-content

Ce que fait réellement list-npm-package-content

La skill list-npm-package-content vous aide à inspecter précisément les fichiers qui seraient inclus dans l’archive npm d’un package avant sa publication. Son rôle est très concret : construire le package, créer le tarball, lister son contenu, puis supprimer l’archive temporaire afin de vérifier exactement ce que les utilisateurs installeront.

À qui convient le mieux cette skill

Cette skill est particulièrement utile aux maintainers de packages, aux release engineers et aux auteurs de bibliothèques qui doivent répondre à des questions comme :

• « Est-ce que le résultat de mon build est bien présent dans le package publié ? »
• « Pourquoi npm embarque-t-il des fichiers source, des fixtures de test ou des secrets ? »
• « Pourquoi un fichier requis manque-t-il après l’installation ? »
• « Ce package fonctionnera-t-il dans des environnements de déploiement qui ne voient que les artefacts publiés ? »

Si vous maintenez des monorepos ou publiez depuis des sous-packages, c’est encore plus pertinent.

Le vrai besoin couvert

La vraie valeur de list-npm-package-content ne se limite pas à afficher une liste de fichiers. La skill réduit le risque de release avant publication en montrant le résultat packagé que reçoivent réellement les consommateurs npm, qui diffère souvent de l’arborescence du dépôt. C’est essentiel pour diagnostiquer la taille d’un package, des artefacts de build manquants, des fuites de fichiers accidentelles ou des échecs de déploiement causés par une publication incomplète.

Ce qui la distingue d’un prompt générique

Un prompt IA générique peut vous dire de « vérifier files, .npmignore et .gitignore ». Cette skill va plus loin, car elle centre l’analyse sur le résultat réel du tarball, pas seulement sur les règles de configuration. En pratique, c’est le tarball qui compte. Le script utilitaire inclus fournit aussi un workflow concret : build, pack, inspection, nettoyage.

Contraintes clés à connaître avant l’installation

La skill list-npm-package-content actuelle est volontairement ciblée :

• elle se concentre sur le contenu des packages npm, pas sur une validation complète de release ;
• le script utilitaire part du principe que vous utilisez un workflow basé sur pnpm ;
• elle suppose que vous l’exécutez depuis le répertoire du package à inspecter ;
• elle n’explique pas à votre place tous les cas limites du packaging npm ; vous devez toujours interpréter le résultat.

Si vous cherchez un tutoriel complet sur le packaging, c’est trop spécialisé. Si vous voulez un contrôle rapide avant publication, c’est un bon choix.

Comment utiliser la skill list-npm-package-content

Contexte d’installation pour list-npm-package-content

Utilisez la skill dans un environnement où le package cible peut déjà être construit correctement. Les éléments du dépôt montrent que le workflow de packaging s’appuie sur un script shell :

bash scripts/list-package-files.sh

Ce script exécute :

• pnpm build
• pnpm pack
• tar -tzf sur le tarball généré
• la suppression du tarball

Avant d’utiliser list-npm-package-content, vérifiez donc que votre environnement dispose de pnpm, de tar et des dépendances du projet.

Commencez par lire ces fichiers

Pour cette skill, l’ordre de lecture le plus utile et le plus rapide est :

1. skills/list-npm-package-content/SKILL.md
2. skills/list-npm-package-content/scripts/list-package-files.sh
3. le package.json du package ciblé
4. le .npmignore du package ciblé, s’il existe
5. le .gitignore du package ciblé si aucun .npmignore n’existe

Cet ordre reflète le passage d’une guidance générale aux règles de packaging exactes qui pilotent le résultat.

Les informations dont la skill a besoin

Pour bien utiliser list-npm-package-content, fournissez à l’agent :

• le chemin du package, par exemple packages/ai
• le gestionnaire de paquets utilisé
• si le package doit être buildé avant le pack
• ce que vous cherchez à vérifier
• les fichiers suspects ou manquants qui vous préoccupent

Les bonnes entrées sont concrètes. « Vérifie mon package » est trop vague. « Montre si dist/, README.md et les fichiers de types générés sont inclus, et confirme que les fixtures de test sont exclues » est bien plus utile.

Workflow pratique d’exécution

Un workflow concret pour list-npm-package-content usage ressemble à ceci :

1. placez-vous dans le répertoire du package ;
2. exécutez le script utilitaire si la structure de votre dépôt correspond à celle prévue par la skill ;
3. examinez la liste des fichiers du tarball ;
4. comparez le résultat avec :
   • files dans package.json
   • .npmignore
   • les artefacts de build attendus
5. ajustez la configuration de packaging puis relancez.

Cette skill fonctionne mieux en boucle qu’en commande ponctuelle.

Exemple de prompt qui déclenche bien la skill

Un prompt plus efficace pour un agent serait :

« Utilise list-npm-package-content sur packages/my-lib. Build le package, liste le contenu du tarball et dis-moi si dist/, les déclarations de types et README.md sont inclus. Signale tous les fichiers source, tests, fichiers env ou artefacts volumineux qui ne devraient probablement pas être publiés. »

Pourquoi ce prompt fonctionne :

• il indique le chemin du package ;
• il précise ce qu’il faut inspecter ;
• il demande à la fois une revue des inclusions et des exclusions ;
• il oriente la sortie vers une décision, pas vers une simple description.

Des prompts plus solides pour les vérifications de déploiement

Pour list-npm-package-content for Deployment, adaptez le prompt aux besoins d’exécution :

« Utilise list-npm-package-content sur packages/sdk et vérifie que le tarball publié contient tous les fichiers nécessaires à une installation en production dans CI et en déploiement serverless. Confirme que la sortie compilée existe, que les entry points se résolvent correctement et qu’aucun fichier uniquement local n’est requis à l’exécution. »

Cela améliore les résultats, car les échecs de déploiement viennent souvent d’artefacts buildés manquants plutôt que d’erreurs de packaging évidentes.

Ce que le script utilitaire valide réellement

Le script shell fourni valide le résultat packagé, pas seulement l’intention déclarée. En pratique, il pose les questions suivantes :

• est-ce que le build a produit les artefacts attendus ?
• est-ce que pnpm pack les a bien inclus ?
• est-ce que le tarball correspond à ce que les utilisateurs finaux vont télécharger ?

C’est ce qui rend la skill particulièrement utile quand le contenu du dépôt et le contenu effectivement publié divergent.

Comment npm décide de ce qui apparaît dans le tarball

La skill met en évidence les principales règles de packaging à inspecter :

1. files dans package.json
2. .npmignore
3. .gitignore en l’absence de .npmignore
4. les fichiers toujours inclus par npm, comme package.json, README, LICENSE, CHANGELOG
5. les chemins toujours exclus par npm, comme .git, node_modules, .npmrc

Cette hiérarchie est importante. Beaucoup de bugs de packaging viennent de l’idée fausse que l’arborescence du dépôt correspond automatiquement au package publié.

Quand l’utiliser plutôt que se contenter de lire package.json

Utilisez list-npm-package-content quand l’inspection de la configuration ne suffit pas. Lire package.json peut vous renseigner sur l’intention, mais pas sur le fait que le tarball buildé contient bien les fichiers attendus une fois que les outils de build, les règles d’ignore et les sorties générées interagissent entre eux. Pour valider une release, le contenu réel du tarball est plus fiable que la configuration seule.

Besoins d’adaptation fréquents dans les vrais dépôts

Vous devrez peut-être adapter le script si :

• votre dépôt utilise npm ou yarn au lieu de pnpm
• votre commande de build diffère de pnpm build
• vous voulez inspecter un package sans relancer le build
• vous publiez depuis le chemin d’un package dans un monorepo
• votre environnement ne dispose pas d’outils shell compatibles GNU

Cela n’enlève rien à l’intérêt de la skill, mais cela signifie que list-npm-package-content install relève davantage de l’adoption d’un workflow que d’une portabilité immédiate.

FAQ sur la skill list-npm-package-content

Est-ce que list-npm-package-content est adaptée aux débutants

Oui, à condition de déjà comprendre les bases de la publication de packages. La skill est ciblée et concrète, ce qui aide les débutants à éviter une documentation npm trop abstraite. Le principal point de blocage reste l’environnement : vous devez savoir où se trouve le répertoire du package et s’il nécessite une étape de build avant le pack.

Quel problème cette skill résout-elle mieux qu’un prompt ordinaire

list-npm-package-content est meilleure qu’un prompt ordinaire quand vous avez besoin d’une réponse orientée exécution. Au lieu de simplement expliquer les règles npm, elle vous donne une vérification reproductible sur le contenu réel du tarball. C’est plus utile pour la QA avant publication et pour déboguer des fichiers manquants.

Est-ce que cela remplace npm pack ou les dry runs de npm publish

Pas exactement. La skill repose sur la même réalité de packaging, mais sa valeur vient du workflow guidé et du modèle de script inclus. Voyez-la comme une routine d’inspection fiable autour du packing, pas comme un système de packaging distinct.

Est-ce que list-npm-package-content est réservé aux monorepos

Non. Elle fonctionne aussi pour les dépôts à package unique. Elle devient encore plus précieuse dans les monorepos, car les frontières entre packages, les sorties de build et les racines de publication y sont plus faciles à mal configurer.

Quand ne faut-il pas utiliser list-npm-package-content

Évitez cette skill si votre question porte uniquement sur le versioning npm, la génération de changelog, l’authentification au registre ou l’automatisation des releases. Évitez-la aussi si vous cherchez seulement une explication conceptuelle de files et des règles d’ignore sans inspecter un vrai package.

Peut-on l’utiliser pour déboguer un déploiement

Oui. list-npm-package-content for Deployment est un cas d’usage particulièrement pertinent lorsque les installations en production échouent parce que le package publié n’inclut pas les fichiers compilés, les assets runtime ou les fichiers de déclaration. La skill vous aide à vérifier ce que les environnements en aval reçoivent réellement.

Comment améliorer la skill list-npm-package-content

Commencez par un prompt orienté décision

Pour obtenir de meilleurs résultats avec list-npm-package-content, posez une question qui aide à trancher. Par exemple :

• vérifier la présence des fichiers runtime requis
• détecter des fichiers publiés de manière inattendue
• comparer le contenu publié à la structure du dépôt
• expliquer pourquoi un fichier précis est absent

Vous obtiendrez ainsi un résultat plus utile qu’en demandant simplement une liste de fichiers.

Indiquez le chemin exact du package et les artefacts attendus

L’amélioration la plus rentable consiste à préciser :

• le répertoire du package
• la sortie de build attendue
• les entry points du package
• les fichiers qui doivent exister dans le tarball
• les fichiers qui ne doivent pas y figurer

Exemple :

« Exécute list-npm-package-content pour packages/ui et confirme que dist/index.js, dist/index.d.ts et README.md sont inclus, tandis que src/, les tests et les fichiers .env sont exclus. »

Cela transforme une inspection vague en véritable validation de publication.

Comparez le contenu du tarball aux entry points du package

Un mode d’échec fréquent est le suivant : le tarball contient bien des fichiers, mais pas ceux référencés par main, module, exports ou types. Pour améliorer la sortie de la skill, demandez explicitement cette comparaison :

« Liste les fichiers packagés et vérifie qu’ils correspondent aux chemins référencés dans les champs exports et types de package.json. »

Cela permet de détecter tôt de nombreuses publications cassées.

Utilisez-la de façon itérative après des changements de configuration

Le meilleur workflow est itératif :

1. inspecter le tarball
2. modifier files ou les règles d’ignore
3. rebuild et repack
4. comparer à nouveau

La qualité de list-npm-package-content guide augmente nettement si vous considérez la première sortie comme une base de diagnostic, et non comme la réponse finale.

Attention au faux sentiment de sécurité après un build réussi

Un build réussi ne garantit pas une publication correcte. Le build peut générer dist/, mais votre tarball peut tout de même l’exclure. Quand vous utilisez list-npm-package-content, demandez à l’agent de distinguer « le build a réussi » de « le package publié est complet ». C’est précisément dans cet écart que la skill apporte le plus de valeur.

Améliorez la portabilité si votre outillage diffère

Si votre dépôt n’utilise pas pnpm, adaptez la logique du script utilitaire, pas son objectif :

• remplacez pnpm build par votre commande de build
• remplacez pnpm pack par la commande de pack équivalente
• conservez les étapes de listing du tarball et de nettoyage

Vous préservez ainsi le cœur de list-npm-package-content usage tout en l’alignant sur votre environnement.

Modes d’échec fréquents à vérifier en priorité

Les problèmes les plus courants à contrôler sont :

• dist/ absent du tarball
• fichiers source inclus involontairement
• données de test ou fixtures publiées
• règles d’ignore qui excluent des assets nécessaires
• fichiers README ou de licence manquants de façon inattendue
• entry points qui référencent des fichiers absents du tarball

Si vous demandez explicitement à la skill de vérifier ces points, la sortie devient beaucoup plus exploitable.

Demandez une explication, pas seulement une énumération

Pour améliorer la qualité de la sortie, demandez à la fois la liste des fichiers et la raison probable de leur inclusion ou exclusion. Par exemple :

« Liste le contenu du tarball et explique quelles règles ont probablement conduit à l’inclusion ou à l’omission des fichiers inattendus. »

Cela fait passer la skill d’un simple contrôle à un vrai support de débogage.

Utilisez list-npm-package-content avant chaque release candidate

L’amélioration la plus pragmatique tient au process : exécutez list-npm-package-content avant les release candidates, et non après une publication défectueuse. C’est un contrôle préliminaire léger qui peut éviter des problèmes de support, de rollback et de déploiement parfaitement évitables.