Solução de problemas de skills

Esta página reúne os erros que autores e admins encontram ao trabalhar com skills — desde a importação e a publicação até a execução na máquina do usuário. Use a tabela como índice e veja os detalhes logo abaixo.

Tabela de erros

Sintoma / código	O que significa	Como resolver
missing_required_env	A skill declarou um segredo obrigatório que não está disponível.	O admin cadastra o segredo e o anexa à skill.
Skill não aparece / é recusada	Você não tem perfil com aquela skill.	Peça ao admin para atribuir a skill a um perfil seu.
Executor protegido indisponível (tool_deferred)	A skill local_protected não pôde ser preparada.	Reabra a sessão; se persistir, peça ao admin.
Execução local negada	A política da org desabilitou execução local de skills para você.	O admin ajusta a permissão no perfil/usuário.
Manifesto inválido (422)	O manifesto não passou na validação.	Corrija o manifesto; o banner do editor aponta o erro.
Conflito de versão (422)	Mesma version, conteúdo diferente.	Faça bump da version no manifesto.
ZIP rejeitado	O pacote violou um limite ou o scanner.	Ajuste o ZIP conforme os limites de importação.
Erros de Python / OUTPUTS_DIR	O script falhou em runtime.	Veja dependências e a disciplina de outputs/.
Skill some da lista	Faltou um campo obrigatório do manifesto.	Garanta name, version e description.

missing_required_env

A skill declarou um segredo obrigatório (em required_env ou env.secrets) que a organização ainda não cadastrou ou não anexou à skill. É um erro de configuração, não de código.

• Autor: confira que o nome declarado bate exatamente com o que o admin cadastrou (maiúsculas, sublinhado).
• Admin: cadastre o segredo e use Manage skills para anexá-lo. Veja Env-secrets (admin).

Detalhes do contrato em Env-secrets (autor).

Skill fora do allowlist do perfil

Se uma skill não aparece para você ou é recusada ao ser acionada, é porque o seu perfil não a inclui. As skills chegam aos usuários por perfis — sem um perfil que contenha a skill, ela não entra na lista apresentada ao modelo. Peça ao admin para atribuir a skill a um perfil seu. Veja também Governança de skills.

Executor protegido indisponível (tool_deferred)

Uma skill em modo local_protected depende de o Imaginne verificar e extrair o bundle protegido. Se isso não acontece, o acionamento fica adiado (tool_deferred). Tente:

1. Reabrir a sessão para forçar uma nova sincronização de skills.
2. Confirmar que você tem acesso à skill (perfil correto).
3. Se persistir, peça ao admin para verificar a publicação da skill protegida.

Sobre o modo em si, veja Modos de execução.

Execução local de skills negada

A organização pode desabilitar a execução local de skills por política (no perfil ou no usuário). Nesse caso, mesmo tendo acesso à skill, o agente não a executa na sua máquina. É uma decisão do admin — peça o ajuste da permissão "Execução de skill local". Veja Perfis e Usuários & papéis.

Manifesto inválido (422)

Ao publicar, o manifesto passa por validação. Falhas comuns:

• schema_version diferente de 1.
• skill_key fora do regex ^[a-z0-9][a-z0-9-]{1,98}[a-z0-9]$.
• name ausente.
• execution_mode: remote_server (rejeitado).
• required_env e env.secrets divergentes.

No editor, o banner de manifesto aponta o problema e bloqueia a publicação até que ele fique verde. Veja Anatomia de uma skill.

Conflito de versão (422)

Você tentou publicar a mesma version com conteúdo diferente. Versões publicadas são imutáveis. Faça bump da version no manifesto (ex.: 1.0.0 → 1.0.1) e publique de novo. Republicar a mesma versão com o mesmo conteúdo é um no-op (idempotente). Veja Publicar e versionar.

ZIP rejeitado

A importação falha quando o pacote viola um limite ou o scanner bloqueia um script:

• Tamanho > 10 MB ou mais de 50 arquivos.
• manifest.yaml ou prompt.md ausente (ambos obrigatórios).
• Path traversal (.. ou caminho absoluto) ou symlink.
• Binário (.exe, .dll, .so, .dylib, .com, .msi).
• Script bloqueado pelo scanner — a mensagem indica o arquivo e o motivo (comando destrutivo, exfiltração de segredo, etc.).

Ajuste o pacote conforme Importar via ZIP e reenvie.

Erros de Python / OUTPUTS_DIR

Quando o script da skill falha em runtime, os culpados mais comuns são:

• ImportError — uma dependência não está instalada. No chat web, a imagem de runtime pode não ter o pacote; localmente, instale com pip install -r requirements.txt.
• "caminho absoluto … fora de OUTPUTS_DIR" — o script tentou escrever fora de outputs/. Escreva sempre em OUTPUTS_DIR; caminhos relativos são unidos sob ele.
• "criar OUTPUTS_DIR" — problema de permissão no diretório de saída.

A disciplina de outputs/ está descrita em Anatomia de uma skill.

Skill some da lista

Se uma skill deixa de aparecer após uma edição, quase sempre falta um campo obrigatório do manifesto local: name, version ou description. Sem os três, a skill não é carregada. Restaure-os e a skill volta.

Coletar diagnóstico

Se o problema persistir e você precisar de ajuda:

• Desktop — Export Support Bundle (redigido, sem tokens) e /fb <mensagem> para enviar feedback.
• Terminal (TUI) — /diagnostics e /feedback.

Veja também a solução de problemas geral.

Veja também

📥Importar via ZIP

Os limites e o scanner que rejeitam um pacote.

Abrir →🚀Publicar e versionar

Idempotência e a regra de bump de versão.

Abrir →🔑Env-secrets (autor)

Declarar segredos e evitar missing_required_env.

Abrir →