Skill em ZIP: confira conteúdo, origem e hash antes de instalar

Um arquivo ZIP pode trazer uma Skill útil para um agente de IA, mas o nome do pacote não diz o que será instalado. Antes de extrair, vale conferir de onde veio, quais caminhos existem dentro dele e se o arquivo recebido corresponde à versão anunciada pelo mantenedor. Este guia mostra uma inspeção inicial no Windows que não executa o conteúdo. O resultado esperado é uma lista de arquivos e uma decisão documentada de continuar a revisão ou interrompê-la, não um selo de segurança.

Antes de começar

Você precisa do ZIP salvo localmente, da página oficial do projeto e do PowerShell. Não abra anexos inesperados, não rode instaladores e não cole em um agente as instruções do pacote antes de avaliá-las. Se o mantenedor publicou uma versão, um commit e um SHA-256 em canal próprio, registre esses dados. Se não publicou um hash independente, calcule o hash local mesmo assim para identificar sua cópia, mas não o trate como prova de origem.

Faça a inspeção em um computador ou ambiente adequado ao risco do material, sem credenciais de produção acessíveis a scripts desconhecidos. Os comandos abaixo leem o arquivo compactado; não pedem privilégios de administrador, não criam pasta de extração e não executam o que estiver dentro do ZIP. Troque o caminho de exemplo pelo caminho real do pacote que você decidiu examinar.

1. Confirme a origem e calcule o hash

Abra a página do repositório ou da documentação diretamente, em vez de confiar apenas no nome enviado por outra pessoa. Confira o mantenedor, a URL canônica e a versão ou commit a que o download se refere. Em seguida, no PowerShell, calcule o SHA-256 do ZIP:

$arquivo = 'C:\caminho\pacote-skill.zip'
Get-FileHash -LiteralPath $arquivo -Algorithm SHA256

O cmdlet Get-FileHash, documentado pela Microsoft, identifica o conteúdo do arquivo. Compare a saída com o SHA-256 divulgado em um canal independente e confiável do mantenedor, quando houver. Dois hashes diferentes exigem parar e investigar. Dois hashes iguais indicam que os bytes coincidem com a referência consultada, mas não garantem que o código ou as instruções sejam benignos. Um hash copiado da mesma mensagem que entregou um pacote suspeito não serve como confirmação independente.

2. Liste o interior sem extrair

O tipo ZipFile.OpenRead, da biblioteca .NET, abre o índice do arquivo para leitura. No PowerShell, use:

Add-Type -AssemblyName System.IO.Compression.FileSystem
$pacote = [System.IO.Compression.ZipFile]::OpenRead($arquivo)
try {
    $pacote.Entries | Select-Object FullName, Length, CompressedLength
} finally {
    $pacote.Dispose()
}

FullName é o caminho de cada item dentro do ZIP. Length é o tamanho descompactado informado no arquivo, e CompressedLength é o tamanho compactado. A saída permite ver se um pacote apresentado como uma Skill de texto contém apenas documentos esperados ou também scripts, executáveis, bibliotecas, pastas ocultas e arquivos enormes. A presença de um SKILL.md não torna os demais arquivos confiáveis. Se o ZIP estiver corrompido ou não puder ser interpretado, o comando pode falhar; não tente contornar o erro executando arquivos de dentro dele.

3. Procure caminhos inesperados

Repita a leitura e destaque nomes com barra inicial, unidade de disco, retorno a diretório pai ou separador invertido. O filtro abaixo é uma triagem de nomes, não um verificador completo de arquivos maliciosos:

$pacote = [System.IO.Compression.ZipFile]::OpenRead($arquivo)
try {
    $pacote.Entries | Where-Object {
        $_.FullName -match '(^/|^[A-Za-z]:|(^|/)\.\.(/|$)|\\)'
    } | Select-Object FullName
} finally {
    $pacote.Dispose()
}

Um item como ../config.txt tenta apontar para fora de uma pasta de extração. Esse tipo de nome exige cuidado de quem implementa a extração: o destino precisa ser normalizado e conferido antes de gravar cada arquivo. Como este guia não extrai nada, qualquer caminho suspeito é motivo para parar e pedir uma versão corrigida ao mantenedor. Uma lista vazia nesse filtro não prova que o ZIP está seguro; ela apenas não encontrou esses padrões específicos.

4. Compare a lista com a finalidade da Skill

Leia a descrição oficial e anote o que deveria estar no pacote. Para uma Skill distribuída só como instruções, arquivos como SKILL.md, licença e registro de origem podem ser suficientes. Outros projetos podem precisar de recursos adicionais legítimos. O importante é não aceitar componentes inesperados sem explicação. Confira também se há arquivos de configuração com tokens, chaves, senhas ou dados pessoais. Não publique nem envie esse conteúdo a outro serviço para pedir uma análise automática.

Se o pacote contiver scripts, trate-os como código a revisar separadamente. Liste dependências e comandos de instalação, verifique o repositório de origem e entenda quais arquivos, pastas, contas e serviços poderiam ser acessados. Para esse passo, o guia do Bastidores sobre dependências e scripts de instalação oferece uma checagem complementar. A inspeção do ZIP não substitui essa revisão.

Erros comuns e limites

Se Get-FileHash disser que não encontrou o arquivo, confira o caminho entre aspas e use -LiteralPath como no exemplo. Se OpenRead indicar formato inválido, confirme que o download terminou e que o arquivo é realmente um ZIP, sem tentar renomear outro formato para fazê-lo funcionar. Se a lista revelar milhares de itens ou tamanhos descompactados desproporcionais, interrompa a análise simples e procure ajuda técnica antes de extrair. Este guia não define um limiar universal para todos os pacotes.

Não confunda ausência de alerta com aprovação. O filtro de caminhos não inspeciona o comportamento de scripts, permissões solicitadas, links dentro do SKILL.md, assinaturas, licença ou dependências externas. Mesmo um pacote sem executáveis pode instruir um agente a executar comandos ou revelar dados. Uma decisão responsável depende da origem verificável, do conteúdo completo, da finalidade e das permissões que você pretende conceder depois.

Resultado esperado

Ao final, você deve ter o caminho do ZIP, seu SHA-256, a URL e a versão da fonte consultada, uma lista de entradas e uma anotação dos itens que exigem revisão. Se não houver fonte confiável, se o hash independente divergir ou se surgirem caminhos e componentes sem explicação, não instale. Se a triagem parecer coerente, avance apenas para uma revisão controlada do conteúdo e das permissões, sem executar automaticamente o pacote. A capa desta matéria é uma ilustração editorial, não uma captura de inspeção real.