list-npm-package-content

Visão geral da skill list-npm-package-content

O que a skill list-npm-package-content realmente faz

A skill list-npm-package-content ajuda você a inspecionar os arquivos exatos que seriam enviados no tarball de um pacote npm antes da publicação. Na prática, a função dela é simples: fazer o build do pacote, criar o tarball, listar o conteúdo do tarball e remover o arquivo temporário para que você confirme exatamente o que os usuários realmente instalarão.

Quando esta skill é mais indicada

Esta skill é mais útil para mantenedores de pacotes, engenheiros de release e autores de bibliotecas que precisam responder perguntas como:

• “Meu output de build entrou no pacote publicado?”
• “Por que o npm está enviando arquivos-fonte, fixtures de teste ou segredos?”
• “Por que um arquivo obrigatório está faltando depois da instalação?”
• “Este pacote vai funcionar em ambientes de deploy que só enxergam os artefatos publicados?”

Se você mantém monorepos ou publica a partir de subpackages, isso é especialmente relevante.

O verdadeiro trabalho que ela resolve

O valor real de list-npm-package-content não está só em imprimir uma lista de arquivos. Ela reduz o risco de release antes da publicação ao mostrar o resultado empacotado que os consumidores do npm recebem — e esse resultado muitas vezes é diferente da árvore do repositório. Isso importa ao depurar tamanho do pacote, artefatos de build ausentes, vazamento acidental de arquivos e falhas de deploy causadas por publicação incompleta.

O que diferencia esta skill de um prompt genérico

Um prompt genérico de IA pode dizer para você “verificar files, .npmignore e .gitignore”. Esta skill é mais forte porque centra a decisão no resultado real do tarball, não apenas nas regras de configuração. Na prática, o que importa é o tarball. O script auxiliar incluído também oferece um fluxo de trabalho concreto: build, pack, inspeção e limpeza.

Restrições importantes antes de instalar

A versão atual de list-npm-package-content é intencionalmente enxuta:

• Ela é focada no conteúdo de pacotes npm, não em uma validação completa de release.
• O script auxiliar assume um fluxo baseado em pnpm.
• Ela espera que você execute a partir do diretório do pacote que deseja inspecionar.
• Ela não explica por você todos os casos de borda do empacotamento do npm; ainda é preciso interpretar a saída.

Se você quer um tutorial amplo sobre packaging, ela é específica demais. Se quer uma checagem rápida antes de publicar, ela se encaixa bem.

Como usar a skill list-npm-package-content

Contexto de instalação da list-npm-package-content

Use a skill em um ambiente no qual o pacote de destino já consiga fazer build com sucesso. As evidências no repositório mostram que o fluxo de empacotamento é conduzido por um script shell:

bash scripts/list-package-files.sh

Esse script executa:

• pnpm build
• pnpm pack
• tar -tzf no tarball gerado
• limpeza do tarball

Então, antes de usar list-npm-package-content, confirme que seu ambiente tem pnpm, tar e as dependências do projeto disponíveis.

Leia estes arquivos primeiro

Para esta skill, o caminho de leitura mais rápido e útil é:

1. skills/list-npm-package-content/SKILL.md
2. skills/list-npm-package-content/scripts/list-package-files.sh
3. O package.json do pacote de destino
4. O .npmignore do pacote de destino, se existir
5. O .gitignore do pacote de destino, se não houver .npmignore

Essa ordem acompanha a forma como você sai da orientação abstrata e chega às regras exatas de empacotamento que controlam a saída.

Quais informações a skill precisa de você

Para usar list-npm-package-content bem, forneça ao agente:

• o caminho do pacote, como packages/ai
• o package manager em uso
• se o pacote precisa de build antes do pack
• o que você está tentando verificar
• quais arquivos suspeitos ou ausentes importam para você

Entradas boas são concretas. “Verifique meu pacote” é fraco. “Mostre se dist/, README.md e os arquivos de tipos gerados estão incluídos, e confirme que os fixtures de teste estão excluídos” é muito melhor.

O fluxo prático de execução

Um fluxo prático de list-npm-package-content usage é assim:

1. Entre no diretório do pacote.
2. Execute o script auxiliar se o layout do seu repositório corresponder ao da skill.
3. Revise a lista de arquivos do tarball.
4. Compare o resultado com:
   • files no package.json
   • .npmignore
   • o output de build esperado
5. Ajuste a configuração de empacotamento e rode novamente.

O melhor uso aqui é em ciclo iterativo, não como comando isolado.

Exemplo de prompt que aciona bem a skill

Um prompt mais forte para um agente seria:

“Use list-npm-package-content em packages/my-lib. Faça o build do pacote, liste o conteúdo do tarball e me diga se dist/, as declarações de tipos e README.md estão incluídos. Sinalize qualquer arquivo-fonte, testes, arquivos de ambiente ou artefatos grandes que provavelmente não deveriam ser enviados.”

Por que isso funciona:

• Nomeia o caminho do pacote.
• Define os alvos da inspeção.
• Pede revisão tanto do que deve entrar quanto do que deve ficar de fora.
• Faz a saída ser orientada à decisão, e não apenas descritiva.

Prompts mais fortes para checagens de deploy

Para list-npm-package-content for Deployment, adapte o prompt às necessidades de runtime:

“Use list-npm-package-content em packages/sdk e verifique se o tarball publicado contém todos os arquivos necessários para instalação em produção em CI e deploy serverless. Confirme que o output compilado existe, que os entry points resolvem corretamente e que nenhum arquivo apenas local é exigido em runtime.”

Isso melhora o resultado porque muitas falhas de deploy vêm de assets gerados ausentes, e não de erros óbvios de packaging.

O que o script auxiliar realmente valida

O script shell incluído valida o resultado empacotado, não apenas a intenção declarada. Na prática, ele pergunta:

• O build gerou os artefatos esperados?
• O pnpm pack os incluiu?
• O tarball corresponde ao que os usuários finais vão baixar?

Isso torna a skill particularmente útil quando o conteúdo do repositório e o conteúdo publicado divergem.

Como o npm decide o que aparece no tarball

A skill expõe as principais regras de packaging que você deve inspecionar:

1. files no package.json
2. .npmignore
3. .gitignore quando não existe .npmignore
4. arquivos sempre incluídos pelo npm, como package.json, README, LICENSE, CHANGELOG
5. caminhos sempre excluídos pelo npm, como .git, node_modules, .npmrc

Essa hierarquia importa. Muitos bugs de empacotamento surgem da suposição de que a árvore do repositório corresponde automaticamente ao pacote publicado.

Quando usar isto em vez de apenas ler o package.json

Use list-npm-package-content quando inspecionar a configuração não for suficiente. Ler o package.json mostra a intenção, mas não garante que o tarball gerado contenha de fato os arquivos esperados depois da interação entre tooling de build, regras de ignore e outputs gerados. Para verificação de release, a saída do tarball é mais confiável do que a configuração isolada.

Adaptações comuns em repositórios reais

Pode ser necessário adaptar o script se:

• seu repositório usa npm ou yarn em vez de pnpm
• seu comando de build é diferente de pnpm build
• você quer inspecionar um pacote sem reconstruí-lo
• você publica a partir do caminho de um pacote dentro de um monorepo
• seu ambiente não tem ferramentas shell compatíveis com GNU

Isso não reduz o valor da skill, mas mostra que list-npm-package-content install tem mais a ver com adoção de fluxo de trabalho do que com portabilidade imediata.

FAQ da skill list-npm-package-content

A list-npm-package-content é amigável para iniciantes?

Sim, desde que você já entenda o básico de publicação de pacotes. A skill é estreita e concreta, o que ajuda iniciantes a não se perderem na documentação abstrata do npm. O principal obstáculo costuma ser o setup do ambiente: você precisa saber onde está o diretório do pacote e se ele exige uma etapa de build antes do pack.

Que problema ela resolve melhor do que um prompt comum?

list-npm-package-content é melhor do que um prompt comum quando você precisa de uma resposta orientada à execução. Em vez de só explicar as regras do npm, ela fornece uma checagem reproduzível contra o conteúdo real do tarball. Isso é mais útil para QA pré-publicação e para depurar arquivos ausentes.

Isso substitui npm pack ou simulações de npm publish?

Não exatamente. A skill é construída em torno da mesma realidade de empacotamento, mas o valor dela está no fluxo guiado e no padrão de script incluído. Pense nela como uma rotina confiável de inspeção ao redor do processo de pack, não como um sistema de packaging separado.

A list-npm-package-content é só para monorepos?

Não. Ela também funciona em repositórios com um único pacote. Em monorepos, ela se torna ainda mais valiosa porque é mais fácil errar os limites entre pacotes, os outputs de build e as raízes de publicação.

Quando eu não devo usar a list-npm-package-content?

Ignore esta skill se sua dúvida for puramente sobre versionamento de npm, geração de changelog, autenticação no registry ou automação de release. Também não vale usar se você só precisa de uma explicação conceitual sobre files e regras de ignore, sem inspecionar um pacote real.

Posso usar isso para depurar problemas de deploy?

Sim. list-npm-package-content for Deployment é um caso de uso forte quando instalações em produção falham porque o pacote publicado está sem arquivos compilados, assets de runtime ou arquivos de declaração. Ela ajuda a verificar o que os ambientes downstream realmente recebem.

Como melhorar a skill list-npm-package-content

Comece com um prompt orientado à decisão

Para obter resultados melhores com list-npm-package-content, faça uma pergunta que ajude a tomar uma decisão. Por exemplo:

• verificar arquivos obrigatórios de runtime
• detectar arquivos enviados por engano
• comparar o conteúdo enviado com a estrutura do repositório
• explicar por que um arquivo específico está ausente

Isso gera um resultado melhor do que simplesmente pedir uma lista de arquivos.

Informe o caminho exato do pacote e os artefatos esperados

A melhoria de maior impacto é especificar:

• diretório do pacote
• output de build esperado
• entry points do pacote
• arquivos que precisam existir no tarball
• arquivos que não podem existir

Exemplo:

“Execute list-npm-package-content para packages/ui e confirme que dist/index.js, dist/index.d.ts e README.md estão incluídos, enquanto src/, testes e arquivos .env estão excluídos.”

Isso transforma uma inspeção vaga em validação de publicação.

Compare a saída do tarball com os entry points do pacote

Um modo de falha comum é o tarball incluir arquivos, mas não aqueles referenciados por main, module, exports ou types. Para melhorar a saída da skill, peça explicitamente essa comparação:

“Liste os arquivos empacotados e verifique se eles atendem aos caminhos referenciados nos campos exports e types do package.json.”

Isso detecta cedo muitas publicações quebradas.

Use de forma iterativa após mudanças na configuração

O melhor fluxo é iterativo:

1. inspecionar o tarball
2. alterar files ou regras de ignore
3. reconstruir e empacotar novamente
4. comparar outra vez

A qualidade de list-npm-package-content guide melhora quando você trata a primeira saída como uma linha de base de diagnóstico, e não como resposta final.

Cuidado com a falsa confiança de builds bem-sucedidos

Um build bem-sucedido não significa uma publicação correta. O build pode gerar dist/, mas o tarball ainda assim pode excluí-lo. Ao usar list-npm-package-content, peça ao agente para separar “o build funcionou” de “o pacote publicado está completo”. É justamente nessa distinção que a skill agrega valor real.

Melhore a portabilidade se seu tooling for diferente

Se seu repositório não usa pnpm, adapte a lógica do script auxiliar, não o objetivo:

• substitua pnpm build pelo seu comando de build
• substitua pnpm pack pelo comando equivalente de pack
• mantenha as etapas de listagem do tarball e limpeza

Isso preserva o núcleo de list-npm-package-content usage ao mesmo tempo em que se ajusta ao seu ambiente.

Modos de falha mais comuns para verificar primeiro

Os problemas mais comuns que valem a checagem inicial são:

• dist/ ausente no tarball
• arquivos-fonte incluídos sem querer
• dados de teste ou fixtures enviados
• arquivos de ignore excluindo assets necessários
• arquivos README ou licença faltando de forma inesperada
• entry points apontando para arquivos que não existem no tarball

Se você pedir à skill para verificar esses pontos explicitamente, a saída fica muito mais acionável.

Peça explicação, não só enumeração

Para melhorar a qualidade da saída, solicite tanto a lista de arquivos quanto a provável razão para cada inclusão ou exclusão. Por exemplo:

“Liste o conteúdo do tarball e explique quais regras provavelmente fizeram com que arquivos inesperados fossem incluídos ou omitidos.”

Isso faz a skill sair da simples inspeção e entrar em suporte real de debugging.

Use list-npm-package-content antes de toda release candidate

A melhoria mais prática é de processo: execute list-npm-package-content antes de cada release candidate, não depois de uma publicação quebrada. É uma checagem leve de pré-voo que pode evitar suporte desnecessário, rollback e problemas de deploy.