Importar uma skill via ZIP

Quando você já tem uma skill pronta — com manifesto, prompt e scripts — pode trazê-la inteira para a sua organização via Import from ZIP no Skill Studio. Esta página descreve o layout exato que o ZIP precisa ter, os limites que o validador impõe e como importar pela interface.

Layout exigido

O ZIP precisa conter, na raiz, dois arquivos obrigatórios:

minha-skill.zip
├── manifest.yaml      # obrigatório — esquema da Plataforma (schema_version 1)
├── prompt.md          # obrigatório — as instruções para o agente
├── requirements.txt   # opcional — dependências Python
└── scripts/           # opcional — código executável
    ├── render.py
    └── helpers.py

• manifest.yaml (ou manifest.yml) — o manifesto no esquema da Plataforma. Deve ter schema_version: 1, um skill_key válido e um name.
• prompt.md — o conteúdo do prompt (o que o agente lê). É obrigatório, mesmo que curto.
• Qualquer outro arquivo (scripts, requirements.txt, assets) é preservado.

Os dois arquivos são obrigatórios

Um ZIP sem manifest.yaml ou sem prompt.md é rejeitado. Os nomes são fixos — não use SKILL.yaml/SKILL.md no pacote de importação.

Limites e validação

Antes de aceitar o pacote, o validador aplica regras rígidas. Conhecê-las evita rejeições:

Regra	Limite / comportamento
Tamanho do ZIP	≤ 10 MB. Acima disso é rejeitado.
Número de arquivos	≤ 50 arquivos.
Path traversal	Caminhos com .. ou absolutos são rejeitados.
Symlinks	Não permitidos.
Binários	Extensões .exe, .dll, .so, .dylib, .com, .msi são rejeitadas.
schema_version	Deve ser exatamente 1.
skill_key	Deve casar ^[a-z0-9][a-z0-9-]{1,98}[a-z0-9]$.
name	Obrigatório.
execution_mode	local_plain (padrão) ou local_protected. remote_server é rejeitado.
Scanner de scripts	Arquivos de script (.py, .sh, .js, .ts, .rb…) passam por uma análise de conteúdo.

O scanner de segurança

Os arquivos de script no pacote passam por uma varredura de conteúdo que procura padrões perigosos — comandos destrutivos, tentativas de exfiltração de segredos, chamadas diretas a provedores de modelo, etc. O resultado pode ser:

• Bloqueado — a importação falha e a mensagem aponta o arquivo e o motivo. Corrija o script e tente de novo.
• Aviso — a importação prossegue, mas o Studio exibe sinais para você revisar.

O scanner inspeciona o código-fonte, não binários

Binários já são barrados pela regra de extensão. O scanner roda sobre o código-fonte dos scripts permitidos. Mantenha os scripts simples e com a disciplina de outputs/.

Consistência de env-secrets

Se o manifesto declara segredos nas duas formas — required_env e env.secrets[] — elas precisam concordar. Uma divergência é rejeitada na importação. Veja Env-secrets (autor) para o contrato.

Exemplo de manifest.yaml

Um manifesto mínimo e válido para importar, com um segredo declarado:

schema_version: 1
skill_key: lead-proposal
name: lead_proposal
display_name: "Gerador de Propostas"
version: "1.0.0"
description: Gera uma proposta comercial .docx a partir de um CSV de leads.
entrypoint: scripts/build_proposal.py
permissions:
  network: outbound
  filesystem: outputs_only
docs:
  summary: prompt.md
inputs:
  - name: leads_csv
    type: string
    description: Caminho do CSV de leads.
    required: true
outputs:
  - name: proposta.docx
    type: file
    description: A proposta gerada.
env:
  secrets:
    - name: CRM_API_TOKEN
      secret_ref: crm-api-token
      required: true
execution_mode: local_plain

Passo a passo na interface

1. No console web, abra Skills e clique em Import from ZIP.
2. Selecione o arquivo .zip montado conforme o layout acima.
3. Escolha o grupo de skills de destino (obrigatório).
4. Envie. O validador roda os limites e o scanner.
   • Se algo falhar, a mensagem indica o quê (tamanho, arquivo ausente, manifesto inválido, script bloqueado). Corrija e reenvie.
5. Em caso de sucesso, a skill entra como rascunho no editor. Revise o Prompt Editor e os Files.
6. Quando estiver pronta, publique — veja Publicar e versionar.

Reimportar é seguro

Importar a mesma skill com a mesma versão e o mesmo conteúdo é idempotente (no-op). Mudou o conteúdo? Faça bump da version no manifest.yaml, senão a publicação retorna um conflito. Veja Publicar e versionar.

Veja também

🧩Anatomia de uma skill

O esquema completo do manifest.yaml.

Abrir →🚀Publicar e versionar

Do rascunho importado ao catálogo.

Abrir →🩺Solução de problemas

O que fazer quando o ZIP é rejeitado.

Abrir →