Anatomia de uma skill

Uma skill é uma pasta com um pequeno contrato: um manifesto que a descreve, um prompt que instrui o agente e, quando ela executa trabalho real, um diretório de scripts com suas dependências. Esta página detalha cada arquivo e os dois esquemas de manifesto que você vai encontrar.

Estrutura de pasta

minha-skill/
├── SKILL.yaml          # manifesto local (ou skill.yaml — minúsculo também vale)
├── SKILL.md            # o prompt: instruções para o agente
├── requirements.txt    # dependências Python (se houver scripts)
└── scripts/            # código executável
    ├── render.py
    └── helpers.py

Quando uma skill é distribuída como ZIP para o Skill Studio, o layout muda de nomes (o manifesto vira manifest.yaml e o prompt vira prompt.md) — veja a seção Importar via ZIP. Os dois esquemas descrevem a mesma skill; a diferença é o ponto de entrada (cliente local vs. publicação na Plataforma).

Os dois esquemas de manifesto

Esquema	Arquivo	Quando	Campos-chave
Local	SKILL.yaml / skill.yaml	Skill rodando localmente (Desktop/TUI/VS Code).	name, version, description, entrypoint, permissions, arguments[], required_env, execution_mode.
Plataforma	manifest.yaml	Empacotada em ZIP para importar/publicar no Skill Studio.	schema_version: 1, skill_key, name, version, description, entrypoint, inputs[]/outputs[], permissions, env.secrets[], execution_mode.

Mesma skill, dois nomes de arquivo

As skills inclusas trazem o skill.yaml local; o Skill Studio canoniza para manifest.yaml (schema_version 1) ao publicar. Você não precisa manter os dois à mão — escolha o esquema da via que vai usar.

Esquema local (SKILL.yaml)

Os três campos obrigatórios são name, version e description — se faltar qualquer um, a skill não aparece na lista. Os demais campos são opcionais:

Campo	Tipo	Função
name	string	Identificador da skill (obrigatório).
display_name	string	Rótulo amigável.
version	string	Versão semver, ex.: "2.0" (obrigatório).
description	string	O que a skill faz (obrigatório; ajuda o modelo a decidir acioná-la).
entrypoint	string	Script principal, ex.: scripts/render.py.
permissions	objeto	network: none|outbound|full e filesystem: none|outputs_only|full.
arguments[]	lista	Parâmetros: name, type, description, required, default, choices.
outputs[]	lista	Artefatos gerados: name, content_type, primary.
required_env[]	lista	Nomes de segredos que o Imaginne injeta antes de rodar. Veja Env-secrets.
execution_mode	string	local_plain (padrão) ou local_protected. Veja Modos de execução.
dependencies / commands	listas	Metadados de documentação para o loader.

Esquema da Plataforma (manifest.yaml)

Este é o esquema canônico para ZIP e publicação. Obrigatórios: schema_version: 1, skill_key, name. O skill_key segue o regex ^[a-z0-9][a-z0-9-]{1,98}[a-z0-9]$ (minúsculas, dígitos e hifens).

Campo	Tipo	Função
schema_version	int	Deve ser 1.
skill_key	string	Chave única da skill na org (regex acima).
name	string	Nome interno (obrigatório).
display_name	string	Rótulo exibido no console.
version	string	Versão semver (vira a versão publicada).
description	string	Descrição da skill.
entrypoint	string	Script ou prompt.md para skills só-prompt.
inputs[] / outputs[]	listas	type, description, required, enum.
permissions	objeto	network: none|outbound|full, filesystem: none|outputs_only|full.
docs.summary	string	Arquivo de resumo (geralmente SKILL.md).
env.secrets[]	lista	{ name, secret_ref, required }. Veja Env-secrets.
execution_mode	string	local_plain (padrão) ou local_protected.

remote_server é rejeitado

O valor execution_mode: remote_server (e o legado mode: remote_server) é recusado na importação e na publicação. O runtime de skill é sempre local; canais remotos só fazem relay. Veja Sessão remota.

Exemplo real completo

A skill inclusa docx cria, lê e edita documentos Word. Este é um recorte do SKILL.yaml real (local):

schema_version: 1
skill_key: docx
name: docx_skill
display_name: "DOCX (Microsoft Word)"
version: "2.0"
entrypoint: scripts/docx_create.py
permissions:
  network: none
  filesystem: outputs_only
outputs:
  - name: output.docx
    content_type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
    primary: true
commands:
  - name: docx_create
    script: scripts/docx_create.py
    usage: "python scripts/docx_create.py input.md output.docx [--scheme NAME]"
  - name: docx_edit
    script: scripts/docx_edit.py
    usage: "python scripts/docx_edit.py input.docx output.docx <op> [args...]"
dependencies:
  - python-docx
  - lxml
  - Pillow

Repare nas escolhas: permissions.network: none (gera o documento sem tocar a rede), filesystem: outputs_only (só escreve em outputs/) e commands com o ponto de entrada exato que o agente chama.

O prompt (SKILL.md)

O SKILL.md é o que o agente lê para saber como usar a skill: quando acioná-la, qual script chamar, o formato dos argumentos e os erros comuns. É o componente mais importante para a qualidade do resultado. Boas práticas observadas nas skills inclusas:

• Diga o que NÃO fabricar. "Não invente dados; se faltar input, peça em texto e pare."
• Fixe a disciplina de saída. Todo arquivo final vai em outputs/ (a variável OUTPUTS_DIR).
• Documente o ponto de entrada exato. Mostre a linha de comando, não a teoria.
• Liste os erros úteis (ex.: ImportError, "caminho fora de OUTPUTS_DIR") para o agente se recuperar.

Scripts e dependências

• scripts/ guarda o código executável (Python é o caso comum). Os scripts recebem os argumentos do manifesto e escrevem em outputs/.
• requirements.txt lista as dependências Python, uma por linha:

python-docx
lxml
Pillow

Disciplina de outputs/

Os scripts devem escrever apenas em OUTPUTS_DIR (padrão outputs/). Caminhos relativos são unidos sob OUTPUTS_DIR; um caminho absoluto só é aceito se já estiver dentro dele. Arquivos auxiliares (debug.py, check_env.py) não devem ser criados — eles vazam como artefatos no chat.

Veja também

📦Skills inclusas

Manifestos reais de docx, excel, pdf e ppt_skill.

Abrir →✨Criar no Skill Studio

Editar metadados, prompt, arquivos e segredos no console.

Abrir →🛡️Modos de execução

O que muda no disco entre local_plain e local_protected.

Abrir →