Audit Library Health: encontre Skills quebradas antes de compartilhar

ANÁLISE EDITORIAL

Uma biblioteca de Skills pode continuar abrindo normalmente e, mesmo assim, estar incoerente: o catálogo aponta para uma pasta que não existe, a documentação já não representa o acervo, uma instalação ficou quebrada ou uma origem mudou sem revisão. A Audit Library Health transforma essas perguntas em uma sequência verificável. Ela orienta o agente a validar a estrutura, diagnosticar instalações, procurar atualizações, comparar documentos gerados e revisar a fila de curadoria antes de compartilhar a biblioteca com outra pessoa.

O que esta Skill faz

A Skill fornece um roteiro de manutenção para bibliotecas administradas pelo CLI ai-agent-skills. O fluxo combina cinco verificações: integridade do catálogo, saúde das instalações, disponibilidade de atualizações, sincronismo da documentação e itens que ainda precisam de curadoria. A saída esperada não é um único indicador verde. É um conjunto de achados que permite distinguir erro estrutural, instalação quebrada, fonte remota incerta, documento desatualizado e metadado editorial incompleto.

O método também estabelece duas proteções importantes. Saídas automatizadas devem usar JSON, o que reduz a necessidade de interpretar texto decorativo, e a conferência da documentação deve começar com build-docs --dry-run. A geração real só entra depois, porque sem --dry-run o comando grava README.md e WORK_AREAS.md.

Para quem serve

Ela serve a equipes que mantêm um acervo de Skills para Codex, Claude Code ou outros agentes, especialmente quando esse acervo é compartilhado em um repositório. Também ajuda uma pessoa que instalou Skills de várias origens e precisa entender por que uma delas deixou de carregar, por que a lista gerada não bate com as pastas ou quais itens estão sem justificativa editorial.

A Skill é mais útil antes de publicar uma biblioteca interna, depois de atualizar o CLI, após mover o workspace ou quando a documentação diverge do catálogo. Ela não substitui uma auditoria de segurança do conteúdo de cada Skill. Um catálogo estruturalmente válido ainda pode conter instruções excessivas, dependências vulneráveis ou permissões inadequadas.

Origem e curadoria

A origem é o repositório MoizIbnYousaf/ai-agent-skills, apresentado como biblioteca curada e gerenciador universal de Skills. Em 10/09/2026, a API pública do GitHub registrava 1.138 estrelas e 133 forks; o repositório estava público, não arquivado e sob licença MIT. Esses números pertencem ao projeto inteiro, não medem adoção isolada da Audit Library Health.

A curadoria fixou o commit 1159592a122885ddd8d767243a7cf16aab065919 e leu integralmente a pasta da Skill. A pasta contém apenas SKILL.md. Pesquisas em GitHub, GitLab, Hugging Face e documentação do mantenedor não indicaram uma origem canônica diferente. O inventário autenticado do Bastidores não encontrou o mesmo nome, slug, repositório, caminho, commit, pacote ou finalidade.

Compatibilidade e limites

O arquivo segue o formato descrito pela especificação Agent Skills. As instruções podem ser lidas por agentes compatíveis com SKILL.md, mas a execução funcional depende do CLI ai-agent-skills. No commit auditado, o package.json declara versão 4.3.2 e Node.js 14.16.0 ou posterior.

A Skill declara versão 4.1.0, diferente da versão do CLI. Isso não é um erro por si só: o número do arquivo descreve o roteiro, enquanto o pacote teve lançamentos posteriores. Use o commit como referência reproduzível. O fluxo foi escrito para uma biblioteca administrada pelo próprio CLI e alguns comandos exigem um workspace inicializado. Ele não faz uma auditoria genérica de qualquer diretório de prompts.

Pré-requisitos

• Node.js e npm compatíveis com a versão do CLI que será testada.
• Uma biblioteca inicializada ou um alvo de instalação claramente identificado.
• Cópia ou branch de trabalho, sem alterações não relacionadas misturadas.
• Acesso de leitura ao catálogo, às pastas de Skills e aos destinos instalados.
• Acesso de rede somente para as etapas que verificam origens e atualizações.
• Permissão separada antes de regenerar documentos, atualizar Skills ou publicar o repositório.

Instalação com revisão

O download local desta página é propositalmente documental. Ele contém SKILL.md, LICENSE e ORIGEM.md. Não contém CLI, dependências npm, scripts, catálogo, outras Skills, configurações, credenciais ou relatórios. Compare o SHA-256, extraia em uma pasta de inspeção e leia os três arquivos antes de copiar a Skill para um diretório aceito pelo agente.

Para obter o fluxo funcional da origem, consulte o README fixado e a documentação oficial do npx. O comando sugerido pelo projeto é npx ai-agent-skills install audit-library-health -p. Ele consulta e executa um pacote npm, além de gravar a instalação no projeto. Não use esse comando em um repositório sensível antes de conferir origem, versão, lockfile e plano de mudanças.

Comece pelo mapa do que será auditado

Antes de executar o roteiro, registre a raiz da biblioteca, o arquivo skills.json, as pastas de Skills mantidas localmente, as coleções e os destinos de instalação que entram no escopo. Separe o acervo fonte das cópias instaladas. Uma pasta ausente no catálogo é um problema diferente de uma instalação que aponta para um caminho movido.

Capture também o estado do Git e preserve mudanças do usuário. O diagnóstico deve começar em leitura. Se a biblioteca vive em um workspace compartilhado, faça a auditoria em branch ou cópia controlada. Não aceite uma regeneração automática de documentação antes de saber quais arquivos seriam tocados.

Primeiro passo: valide a estrutura

O comando npx ai-agent-skills validate --format json verifica a estrutura interpretada pelo CLI. Na revisão editorial, validate foi aplicado diretamente à pasta da Audit Library Health e passou: nome, descrição, frontmatter, tamanho e caminho foram reconhecidos, sem erros ou avisos.

Um resultado válido confirma que a Skill pode ser analisada pelo CLI, não que suas instruções sejam seguras ou corretas para todos os ambientes. Leia o conteúdo depois do parser. Procure comandos mutáveis, dependências implícitas, acesso a rede, caminhos amplos e instruções que ultrapassem a autoridade do usuário.

Segundo passo: rode o diagnóstico de instalações

doctor --format json compara biblioteca, configuração e destinos de agentes. Ele pode revelar pastas ausentes, metadados quebrados ou falta de acesso. No teste editorial contra o destino Codex local, duas verificações passaram e uma falhou porque havia uma entrada instalada quebrada. Esse achado foi mantido como falha, não convertido em aprovação.

Interprete cada linha no contexto do alvo. Um diretório gravável não garante que a instalação esteja íntegra. Uma configuração ausente pode significar que padrões serão usados, não necessariamente erro. Se o diagnóstico aponta caminho privado, nome de usuário ou inventário de ferramentas, não copie a saída completa para um relatório público.

Terceiro passo: verifique atualizações com rede controlada

check --format json consulta as origens registradas para saber se uma Skill pode estar desatualizada. O próprio SKILL.md auditado avisa que essa etapa usa rede e pode demorar ou falhar quando um repositório está indisponível.

Uma fonte inacessível deve aparecer como estado desconhecido, não como atualização confirmada. Uma atualização disponível também não autoriza sync. Primeiro compare commits, licença, arquivos adicionados e mudanças de permissão. Atualizar uma Skill pode substituir arquivos instalados; isso é uma ação posterior e precisa de revisão separada.

Quarto passo: confira a documentação sem gravar

Use build-docs --dry-run --format json para perguntar se README.md e WORK_AREAS.md correspondem ao catálogo. O código do CLI, no commit fixado, calcula currentlyInSync no modo seco. Sem --dry-run, a função grava os dois documentos.

No teste editorial, o comando seco foi bloqueado porque o clone não era um workspace inicializado. Esse é o resultado correto para o contexto. Não inicializamos uma biblioteca artificial só para produzir um sinal verde. Em um workspace real, examine o plano e o diff antes de permitir a regeneração.

Quinto passo: trate a fila de curadoria como heurística

curate review --format json organiza itens com metadados ausentes, datas antigas ou outros sinais de revisão. A fila pode listar Skills sem rótulos, sem coleção, nunca curadas ou com confiança insuficiente. Ela ajuda a ordenar trabalho, mas não decide sozinha o que deve ser removido.

Na execução editorial, a fila incluiu a própria Audit Library Health porque o catálogo de origem a marcava sem alguns campos de curadoria. Isso demonstra o limite: um item pode ser funcional e ainda precisar de metadados. Revise a finalidade, o mantenedor, a licença, o histórico e o uso real antes de agir.

Primeiro uso seguro

Um pedido inicial pode ser: “Use Audit Library Health nesta cópia da biblioteca. Comece somente com validate, doctor, check, build-docs --dry-run e curate review, sempre em JSON. Não atualize Skills, não regenere arquivos e não faça push. Entregue achados por severidade, com comando, alvo e evidência compacta”.

Depois, revise o relatório humano. Separe falhas determinísticas de indisponibilidade de rede. Para cada correção proposta, peça um plano de arquivo, comando e reversão. Uma biblioteca saudável é aquela cujo estado pode ser explicado e reproduzido, não apenas aquela em que o processo terminou com código zero.

Resultado esperado

O resultado útil é um relatório com versão do CLI, commit do acervo, escopo, contagens, comandos executados, códigos de saída e achados. Cada achado deve indicar categoria, impacto, evidência, ação recomendada e necessidade de autorização. Inclua uma seção de incertezas para origens que não responderam e caminhos que ficaram fora do escopo.

Quando documentos estiverem fora de sincronia, apresente o diff previsto. Quando uma instalação estiver quebrada, registre o destino e a referência ausente sem expor dados privados. Quando houver atualização, mostre a origem e os commits comparados. Não transforme “há uma versão diferente” em “a atualização é segura”.

Permissões e riscos

Os três arquivos do ZIP local são texto e não realizam ações sozinhos. A execução funcional lê catálogos, configurações e diretórios de instalação. Isso pode revelar nomes de Skills, caminhos locais, estrutura da equipe e origens privadas. O comando check acessa rede. A instalação via npx baixa e executa código. A regeneração real de documentos grava arquivos.

Use menor privilégio, limite a raiz e redija saídas antes de compartilhá-las. Não inclua tokens de repositório em comandos ou relatórios. Mantenha sync, build-docs sem modo seco, remoções, commits e push fora do primeiro passe. A documentação de configuração do npm ajuda a identificar registry, cache e variáveis envolvidas.

Alerta atual sobre a cadeia npm

O pacote do CLI foi testado em clone isolado com o lockfile do commit fixado. npm ci instalou 47 pacotes, e npm audit reportou duas vulnerabilidades de severidade alta em dependências transitivas trazidas por ink 4.4.1: lodash 4.17.23 e ws 8.19.0. Não aplicamos npm audit fix, pois isso alteraria a árvore auditada.

Os avisos correspondem aos registros GHSA-r5fr-rjxr-66jc, GHSA-f23m-r3pf-42rh, GHSA-58qx-3vcg-4xpx e GHSA-96hv-2xvq-fx4p. Isso não demonstra exploração no CLI, mas impede tratar a cadeia como limpa. Reavalie o lockfile e as correções atuais antes de usar a CLI em ambiente sensível.

Erros comuns e como corrigir

O comando não encontra o workspace

Confirme a raiz e a presença da configuração da biblioteca. Não inicialize um workspace sobre um repositório existente sem revisar os arquivos que serão criados.

O doctor falha em um destino que parece gravável

Verifique entradas instaladas quebradas, links, pastas movidas e metadados. Permissão de escrita é apenas uma das verificações.

O check fica lento ou retorna desconhecido

Registre a origem afetada e o horário. Não marque a Skill como atualizada ou obsoleta sem resposta verificável. Repita depois, com a mesma versão do CLI.

O dry-run diz que os documentos mudariam

Capture o plano, gere em branch controlada e revise o diff. Não grave diretamente no ramo compartilhado.

A fila de curadoria parece enorme

Agrupe por causa, como rótulo ausente, data antiga ou pasta faltante. Corrija primeiro falhas estruturais e trate metadados editoriais em lotes pequenos.

O que a revisão editorial confirmou

Confirmamos o conteúdo integral do SKILL.md, a versão declarada 4.1.0, o CLI 4.3.2 no mesmo commit, a licença MIT e os comandos implementados no código. validate passou na pasta da Skill. doctor preservou uma falha real. build-docs --dry-run recusou um contexto não inicializado. curate review produziu uma fila heurística.

Também confirmamos os avisos atuais da árvore npm. A revisão não certifica o pacote, não corrige dependências, não auditou cada uma das 47 dependências e não executou check contra origens privadas. A ilustração é conceitual e não representa um painel real.

Quando não usar

Não use esta Skill como substituta de análise de segurança, revisão jurídica de licenças ou teste do comportamento de cada Skill. Não use o fluxo para atualizar automaticamente um acervo de produção. Também não o aplique a uma pasta arbitrária esperando que o CLI compreenda convenções diferentes.

Se o objetivo é avaliar uma única Skill antes de instalá-la, faça uma revisão específica de conteúdo, dependências e permissões. Se a biblioteca não usa o modelo do ai-agent-skills, adapte apenas as ideias de inventário e evidência, sem fingir compatibilidade de comandos.

Versão, licença e pacote auditado

Origem: MoizIbnYousaf/ai-agent-skills, caminho skills/audit-library-health/SKILL.md, commit 1159592a122885ddd8d767243a7cf16aab065919. A Skill declara versão 4.1.0; o CLI no mesmo commit declara 4.3.2. A licença MIT permite redistribuição com o aviso preservado.

O pacote local contém três arquivos textuais, tem 3.266 bytes e SHA-256 2c63e62ec75ede3e4ca1f287d750033d35a369dad748bf6f7cdd5213b2ceb268. O botão de download entrega esse espelho documental. O botão do repositório abre a origem oficial em nova aba. Eles são ações distintas.

Checklist antes de avançar

• Fixei o commit da Skill e a versão do CLI.
• Li SKILL.md, licença, README, package.json e lockfile.
• Defini a raiz, o catálogo, as pastas e os destinos em escopo.
• Preservei mudanças existentes e comecei somente em leitura.
• Usei JSON nas saídas automatizadas.
• Separei indisponibilidade de rede de atualização confirmada.
• Executei build-docs primeiro com dry-run.
• Revisei os avisos npm atuais antes de executar o CLI.
• Exigi aprovação separada para instalar, sincronizar, regenerar, remover, commitar ou publicar.

Fontes oficiais consultadas

• SKILL.md fixado no GitHub.
• README de instalação e uso.
• Changelog do projeto.
• Release 4.3.2.
• Licença MIT.
• Metadados oficiais do pacote npm 4.3.2.
• Especificação Agent Skills.