list-npm-package-content

Visión general de la skill list-npm-package-content

Qué hace realmente list-npm-package-content

La skill list-npm-package-content te ayuda a inspeccionar los archivos exactos que se incluirían en el tarball de un paquete npm antes de publicarlo. Su función práctica es sencilla: compilar el paquete, crear el tarball, listar su contenido y eliminar el archivo temporal para que puedas verificar qué instalarán realmente los usuarios.

Cuándo conviene usar esta skill

Esta skill resulta especialmente útil para maintainers de paquetes, release engineers y autores de librerías que necesitan responder preguntas como:

• “¿Mi salida de build quedó incluida en el paquete publicado?”
• “¿Por qué npm está publicando archivos fuente, fixtures de tests o secretos?”
• “¿Por qué falta un archivo necesario después de instalar?”
• “¿Este paquete funcionará en entornos de despliegue que solo ven los artefactos publicados?”

Si mantienes monorepos o publicas desde subpaquetes, esto es todavía más relevante.

El problema real que resuelve

El valor real de list-npm-package-content no está solo en imprimir una lista de archivos. Reduce el riesgo de publicación antes del publish al mostrar el resultado empaquetado que reciben los consumidores de npm, que a menudo difiere del árbol de archivos del repositorio. Esto importa al depurar tamaño del paquete, artefactos de build ausentes, filtraciones accidentales de archivos y fallos de despliegue causados por una publicación incompleta.

Qué la diferencia de un prompt genérico

Un prompt genérico de IA podría decirte que “revises files, .npmignore y .gitignore”. Esta skill va más allá porque centra la decisión en el resultado real del tarball, no solo en las reglas de configuración. En la práctica, lo que importa es el tarball. Además, el script auxiliar incluido aporta un flujo de trabajo concreto: build, pack, inspección y limpieza.

Restricciones clave que debes conocer antes de instalarla

La skill list-npm-package-content actual es intencionalmente acotada:

• Se centra en el contenido de paquetes npm, no en una validación completa del release.
• El script auxiliar asume un flujo de trabajo basado en pnpm.
• Espera que la ejecutes desde el directorio del paquete que quieres inspeccionar.
• No interpreta por ti todos los casos límite del empaquetado en npm; aún debes analizar la salida.

Si buscas un tutorial amplio sobre packaging, esta skill es demasiado específica. Si buscas una comprobación rápida antes de publicar, encaja muy bien.

Cómo usar la skill list-npm-package-content

Contexto de instalación para list-npm-package-content

Usa la skill en un entorno donde el paquete objetivo ya pueda compilar correctamente. La evidencia del repositorio muestra que el flujo de empaquetado está guiado por un script shell:

bash scripts/list-package-files.sh

Ese script ejecuta:

• pnpm build
• pnpm pack
• tar -tzf sobre el tarball generado
• limpieza del tarball

Así que, antes de usar list-npm-package-content, confirma que tu entorno dispone de pnpm, tar y las dependencias del proyecto.

Lee primero estos archivos

Para esta skill, la ruta de lectura más rápida y útil es:

1. skills/list-npm-package-content/SKILL.md
2. skills/list-npm-package-content/scripts/list-package-files.sh
3. El package.json del paquete objetivo
4. El .npmignore del paquete objetivo, si existe
5. El .gitignore del paquete objetivo si no existe .npmignore

Ese orden refleja cómo pasar de la guía general a las reglas exactas de empaquetado que controlan la salida.

Qué información necesita la skill de tu parte

Para usar bien list-npm-package-content, proporciona al agente:

• la ruta del paquete, por ejemplo packages/ai
• el package manager en uso
• si el paquete debe compilarse antes de empaquetarse
• qué estás intentando verificar
• qué archivos sospechosos o ausentes te preocupan

Las buenas entradas son concretas. “Revisa mi paquete” aporta poco. “Muestra si dist/, README.md y los archivos de tipos generados están incluidos, y confirma que los fixtures de tests quedan excluidos” es mucho mejor.

Flujo práctico de invocación

Un flujo práctico para list-npm-package-content usage se ve así:

1. Entra en el directorio del paquete.
2. Ejecuta el script auxiliar si la estructura de tu repo coincide con la skill.
3. Revisa la lista de archivos del tarball.
4. Compara el resultado con:
   • files de package.json
   • .npmignore
   • las expectativas sobre la salida de build
5. Ajusta la configuración de empaquetado y vuelve a ejecutar.

Lo ideal es usarlo como un bucle, no como un comando puntual.

Ejemplo de prompt que activa bien la skill

Un prompt más sólido para un agente sería:

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

Por qué funciona:

• Indica la ruta del paquete.
• Define los objetivos concretos de la inspección.
• Pide revisar tanto inclusiones como exclusiones.
• Hace que la salida esté orientada a decisiones, no solo a describir.

Prompts más sólidos para comprobaciones de despliegue

Para list-npm-package-content for Deployment, adapta el prompt a las necesidades de ejecución:

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

Esto mejora los resultados porque muchos fallos de despliegue provienen de artefactos compilados ausentes, no de errores obvios de packaging.

Qué valida realmente el script auxiliar

El script shell incluido valida el resultado empaquetado, no solo la intención declarada. En la práctica, plantea estas preguntas:

• ¿El build generó los artefactos esperados?
• ¿pnpm pack los incluyó?
• ¿El tarball coincide con lo que descargarán los usuarios finales?

Por eso la skill es especialmente útil cuando el contenido del repositorio y el contenido publicado no coinciden.

Cómo decide npm qué aparece en el tarball

La skill pone sobre la mesa las reglas clave de empaquetado que deberías inspeccionar:

1. files en package.json
2. .npmignore
3. .gitignore cuando no existe .npmignore
4. archivos que npm siempre incluye, como package.json, README, LICENSE, CHANGELOG
5. rutas que npm siempre excluye, como .git, node_modules, .npmrc

Esta jerarquía importa. Muchos errores de packaging surgen al asumir que el árbol del repo coincide automáticamente con el paquete publicado.

Cuándo usar esto en lugar de limitarte a leer package.json

Usa list-npm-package-content cuando inspeccionar la configuración no sea suficiente. Leer package.json puede mostrarte la intención, pero no te dice si el tarball generado contiene realmente los archivos esperados después de que interactúen las herramientas de build, las reglas de exclusión y las salidas generadas. Para verificar un release, la salida del tarball es más fiable que la configuración por sí sola.

Necesidades habituales de adaptación en repos reales

Puede que necesites adaptar el script si:

• tu repo usa npm o yarn en lugar de pnpm
• tu comando de build no es pnpm build
• quieres inspeccionar un paquete sin reconstruirlo
• publicas desde la ruta de un paquete dentro de un monorepo
• tu entorno no dispone de herramientas shell compatibles con GNU

Esto no reduce el valor de la skill, pero sí implica que list-npm-package-content install tiene más que ver con adoptar el flujo de trabajo que con una portabilidad inmediata.

Preguntas frecuentes sobre la skill list-npm-package-content

¿list-npm-package-content es apta para principiantes?

Sí, siempre que ya entiendas lo básico de la publicación de paquetes. La skill es concreta y acotada, lo que ayuda a evitar perderse en documentación abstracta de npm. El principal obstáculo suele ser la configuración del entorno: necesitas saber dónde está el directorio del paquete y si requiere un paso de build antes de empaquetar.

¿Qué problema resuelve mejor que un prompt normal?

list-npm-package-content supera a un prompt común cuando necesitas una respuesta orientada a la ejecución. En vez de limitarse a explicar reglas de npm, te da una comprobación reproducible contra el contenido real del tarball. Eso resulta más útil para QA previo a la publicación y para depurar archivos ausentes.

¿Sustituye a npm pack o a los dry runs de npm publish?

No exactamente. La skill se apoya en la misma realidad de empaquetado, pero su valor está en el flujo guiado y en el patrón del script incluido. Piensa en ella como una rutina fiable de inspección alrededor del proceso de pack, no como un sistema de empaquetado distinto.

¿list-npm-package-content es solo para monorepos?

No. También funciona en repos de un solo paquete. Aun así, gana valor en monorepos porque allí es más fácil equivocarse con los límites entre paquetes, las salidas de build y las raíces de publicación.

¿Cuándo no debería usar list-npm-package-content?

Omite esta skill si tu pregunta trata exclusivamente sobre versionado de npm, generación de changelog, autenticación con el registry o automatización de releases. También puedes omitirla si solo necesitas una explicación conceptual de files y de las reglas de exclusión, sin inspeccionar un paquete real.

¿Puedo usarla para depurar despliegues?

Sí. list-npm-package-content for Deployment es un caso de uso fuerte cuando las instalaciones en producción fallan porque al paquete publicado le faltan archivos compilados, assets de runtime o archivos de declaraciones. Te ayuda a verificar qué reciben realmente los entornos aguas abajo.

Cómo mejorar la skill list-npm-package-content

Empieza con un prompt orientado a decisiones

Para obtener mejores resultados con list-npm-package-content, formula una pregunta que ayude a tomar una decisión. Por ejemplo:

• verificar archivos necesarios en runtime
• detectar archivos publicados que no deberían estar
• comparar el contenido publicado con la estructura del repo
• explicar por qué falta un archivo concreto

Esto produce mejores resultados que pedir simplemente una lista de archivos.

Indica la ruta exacta del paquete y los artefactos esperados

La mejora de mayor impacto es especificar:

• directorio del paquete
• salida de build esperada
• entry points del paquete
• archivos que deben existir en el tarball
• archivos que no deben existir

Ejemplo:

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

Así conviertes una inspección vaga en una validación de publicación.

Compara la salida del tarball con los entry points del paquete

Un modo de fallo muy común es que el tarball incluya archivos, pero no los que referencian main, module, exports o types. Mejora la salida de la skill pidiendo explícitamente esa comparación:

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

Esto detecta muchas publicaciones rotas de forma temprana.

Úsala de forma iterativa después de cambios de configuración

El mejor flujo de trabajo es iterativo:

1. inspeccionar el tarball
2. cambiar files o las reglas de exclusión
3. reconstruir y volver a empaquetar
4. comparar de nuevo

La calidad de list-npm-package-content guide mejora cuando tratas la primera salida como una línea base de diagnóstico, no como la respuesta final.

Evita la falsa confianza de un build exitoso

Que el build termine bien no significa que la publicación sea correcta. El build puede generar dist/, pero tu tarball aun así puede excluirlo. Al usar list-npm-package-content, pide al agente que separe “el build fue exitoso” de “el paquete publicado está completo”. Esa diferencia es justo donde la skill aporta valor real.

Mejora la portabilidad si tu tooling es distinto

Si tu repo no usa pnpm, adapta la lógica del script auxiliar sin cambiar su objetivo:

• sustituye pnpm build por tu comando de build
• sustituye pnpm pack por el comando equivalente para empaquetar
• conserva los pasos de listado del tarball y limpieza

Así mantienes el núcleo de list-npm-package-content usage mientras lo ajustas a tu entorno.

Modos de fallo comunes que conviene revisar primero

Los problemas más habituales que merece la pena comprobar son:

• falta dist/ en el tarball
• se incluyen archivos fuente sin querer
• se publican datos de tests o fixtures
• los archivos de exclusión eliminan assets necesarios
• faltan README o archivos de licencia de forma inesperada
• los entry points apuntan a archivos que no están en el tarball

Si le pides a la skill que revise estos puntos de forma explícita, la salida será mucho más accionable.

Pide explicación, no solo enumeración

Para mejorar la calidad de la salida, solicita tanto la lista de archivos como la razón probable de su inclusión o exclusión. Por ejemplo:

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

Esto hace que la skill pase de la simple inspección al apoyo real en depuración.

Usa list-npm-package-content antes de cada release candidate

La mejora más práctica es de proceso: ejecuta list-npm-package-content antes de cada release candidate, no después de una publicación fallida. Es una comprobación previa ligera que puede evitar incidencias de soporte, rollbacks y problemas de despliegue perfectamente evitables.