---
title: Skills
description: O que são Skills, como o Agent decide usar uma, e o passo a passo completo para criar, importar, editar e vincular Skills (formato SKILL.md).
---
# Skills
Uma **Skill** é um manual de procedimento que o Agent consulta quando precisa. Pensa no atendente que tem, na gaveta, uma pasta "Como negociar BPC/LOAS" e outra "Como lidar com cancelamento de voo". Ele não decora todas as pastas, mas sabe que elas existem e abre a certa quando o assunto aparece.
É exatamente assim que funciona no Atende Direito: o Agent vê a **lista** das Skills disponíveis (nome e descrição) e, quando a conversa pede, **carrega o conteúdo completo** daquela Skill para seguir as instruções dela.
## Skill, instrução ou base de conhecimento?
| | Instrução do Agent | Skill | Base de conhecimento |
|---|---|---|---|
| **O que é** | Quem o Agent é e como ele se comporta sempre | Um procedimento para uma situação específica | Documentos de consulta (FAQ, manual, tabela) |
| **Quando entra no contexto** | Em toda mensagem | Só quando o Agent decide carregá-la | Só os trechos parecidos com a pergunta |
| **Reuso** | Um Agent | Vários Agents e sub-agents | Vários Agents |
| **Exemplo** | "Você é a Ana, do escritório Pacheco. Fale de forma acolhedora." | "Roteiro de qualificação de auxílio-doença: critérios, perguntas, quando descartar" | "Tabela de honorários 2026.pdf" |
Regra prática: se a orientação vale **o tempo todo**, coloque na instrução. Se vale **só num tipo de caso**, vire Skill. Se é **informação para consultar** (não um jeito de agir), vai para a base de conhecimento.
## Como o Agent usa uma Skill
**O Agent recebe o "menu" de Skills.** Ao final da instrução do Agent, a plataforma acrescenta uma seção com cada Skill vinculada: o identificador, o **nome** e a **descrição**. Só isso. O conteúdo completo ainda não está ali.
**Durante a conversa, o Agent decide se precisa de alguma.** Ele compara o assunto da conversa com as descrições do menu. Por isso a **descrição** é o campo mais importante da Skill: é a única coisa que o Agent lê para decidir.
**Ele carrega a Skill.** O Agent chama uma ferramenta interna chamada `load_skill`, passando o identificador da Skill, e recebe de volta o corpo completo (o Markdown que você escreveu).
**Ele segue o procedimento** a partir daí, como se aquelas instruções tivessem sido escritas na instrução principal.
Esse modelo (lista curta sempre, conteúdo só sob demanda) tem um motivo: você pode vincular muitas Skills a um Agent sem pagar, em toda mensagem, o custo de todo o texto delas. Só o menu vai sempre; o corpo vai quando é usado.
**Uma Skill com descrição vaga quase nunca é usada.** Se a descrição diz só "Skill de negociação", o Agent não sabe quando ela se aplica. Escreva a descrição como um gatilho: *"Use quando o cliente perguntar sobre BPC/LOAS para idoso ou pessoa com deficiência, depois que a qualificação já confirmou o direito. Contém tabela de preços e regras de fechamento."*
## Criar uma Skill
As Skills ficam no **Catálogo de Ferramentas**, acessado de dentro do assistente do Agent.
Abra o Agent e vá ao passo **Ferramentas**. Na seção **Skills cognitivas**, clique em **Gerenciar no Catálogo**.
No catálogo, escolha a aba **Skills** e clique em **Importar / criar skill**. Se ainda não houver nenhuma, o botão aparece como **Importar sua primeira skill**.
A janela **Nova Skill (SKILL.md)** abre na aba **Criar**. Preencha:
| Campo | Obrigatório | O que colocar |
|---|---|---|
| **Nome** | Sim | Identificador em kebab-case: só letras minúsculas, números e hífens simples. Ex.: `qualificacao-auxilio-doenca`. Máximo 64 caracteres. **Não pode ser alterado depois.** |
| **Descrição curta** | Sim | Quando o Agent deve usar a Skill e o que ela contém. Máximo 1024 caracteres. É este texto que entra no menu do Agent. |
| **Corpo markdown (SKILL.md)** | Não (mas sem corpo a Skill não ensina nada) | O procedimento em si, em Markdown. Até 256 KB. |
Em **Opções avançadas** existem mais quatro campos, todos opcionais:
| Campo | O que faz |
|---|---|
| **Recursos (um arquivo por linha)** | Lista de arquivos anexos. Hoje é só referência: o Agent não lê esses arquivos. |
| **Licença** | Texto livre (ex.: `MIT`). Informativo. |
| **Compatibilidade** | Texto livre, até 500 caracteres (ex.: modelos com que a Skill foi testada). Informativo. |
| **Ferramentas permitidas** | Restringe quais ferramentas o Agent pode usar. Leia o aviso abaixo antes de preencher. |
Clique em **Criar skill**. O botão fica desabilitado enquanto o nome não estiver em kebab-case válido.
**Vincule a Skill ao Agent.** Ainda no catálogo, selecione a Skill para adicioná-la. Ela passa a aparecer como um card na seção **Skills cognitivas** do passo Ferramentas.
**Publique o Agent de novo.** Adicionar ou remover Skills de um Agent já publicado só vale depois de republicar. Veja [Publicação e versões](/guia/agents/publicacao-e-versoes).
**"Ferramentas permitidas" restringe o Agent inteiro, não só a Skill.** A plataforma junta as ferramentas permitidas de **todas** as Skills do Agent. Se pelo menos uma Skill declarar essa lista, o Agent passa a enxergar **apenas** as ferramentas listadas, mais as internas (carregar Skill, buscar na base de conhecimento, buscar memória). Todo o resto, inclusive as ferramentas do CRM e dos MCP Servers, some. Deixe esse campo vazio, a não ser que você queira exatamente esse efeito.
### Erros de validação comuns
| Mensagem | Causa |
|---|---|
| "O nome deve estar em kebab-case (apenas letras minúsculas, números e hífens simples)." | Maiúsculas, acentos, espaços, `_`, hífen no início/fim ou dois hífens seguidos. |
| "O nome não pode exceder 64 caracteres." | Nome longo demais. |
| "A descrição da skill é obrigatória." | Descrição vazia. |
| "A descrição não pode exceder 1024 caracteres." | A tela não conta os caracteres; o servidor recusa ao salvar. |
| "Já existe uma skill com o nome '...' neste workspace." | Nome repetido no seu workspace. |
## Importar uma Skill pronta
Se você já tem a Skill escrita num arquivo, use a aba **Importar** da mesma janela. Há três modos:
- **Colar texto** — cole o conteúdo completo do `SKILL.md` no campo **Conteúdo da SKILL.md**.
- **Arquivo .md** — arraste ou selecione um arquivo `.md`.
- **Pacote .zip** — um zip com o `SKILL.md` na raiz (ou dentro de uma única pasta) e, opcionalmente, as pastas `scripts/`, `references/` e `assets/`.
Clique em **Importar skill**. A Skill importada sempre fica no seu workspace.
### O formato SKILL.md
Para importar, o arquivo precisa começar com um cabeçalho YAML (o "frontmatter") entre duas linhas `---`, seguido do corpo em Markdown. É o mesmo padrão aberto de Skills usado por outras ferramentas de IA.
```markdown
---
name: qualificacao-auxilio-doenca
description: >-
Use quando o cliente relatar afastamento do trabalho por doença ou acidente
e quiser saber se tem direito a auxílio-doença. Contém os critérios de
qualificação, as perguntas na ordem certa e quando descartar o lead.
license: Proprietária
compatibility: Testada com gpt-4.1 e claude-sonnet-4-5
metadata:
area: previdenciario
autor: equipe-comercial
---
# Qualificação: auxílio-doença
## Objetivo
Confirmar se o cliente tem direito antes de apresentar proposta.
## Perguntas (uma por mensagem, nesta ordem)
1. Desde quando você está afastado?
2. Você tem laudo ou atestado médico?
3. Você contribuía para o INSS quando ficou doente?
## Descarte (só com fato confirmado)
- Nunca contribuiu para o INSS, não é segurado especial e não tem perfil
para o BPC (idoso de 65+ ou pessoa com deficiência de baixa renda).
Explique com gentileza e encerre sem prometer nada.
## Na dúvida, não descarte
- Resposta vaga, ou dado que depende de documento: pergunte de novo de outro jeito.
- Continuou sem clareza: transfira a conversa para o time do escritório analisar.
## Quando terminar
Se os três critérios forem atendidos, mova o negócio para a etapa `Closer`.
```
Chaves que a plataforma lê no cabeçalho:
| Chave | Obrigatória | Regras |
|---|---|---|
| `name` | Sim | kebab-case, até 64 caracteres. |
| `description` | Sim | Texto, até 1024 caracteres. |
| `license` | Não | Texto, até 255 caracteres. |
| `compatibility` | Não | Texto, até 500 caracteres. |
| `metadata` | Não | Mapa de chave → texto. |
| `allowed-tools` | Não | Ferramentas permitidas, separadas por espaço (ou lista YAML). Mesmo aviso de restrição da seção anterior. |
Outras chaves são ignoradas sem erro.
### Limites da importação
| Limite | Valor |
|---|---|
| Texto colado ou `SKILL.md` | 256 KB |
| Arquivo enviado (`.md` ou `.zip`) | 10 MB |
| Arquivos dentro do zip | 200 |
| Tamanho descomprimido do zip | 10 MB |
| Importações por minuto | 10 |
O zip é recusado se tiver links simbólicos, caminhos absolutos, `..` ou pastas fora de `scripts/`, `references/` e `assets/`. O arquivo precisa se chamar exatamente `SKILL.md` (em maiúsculas).
### Erros de importação comuns
| Mensagem | Causa |
|---|---|
| "O SKILL.md deve iniciar com frontmatter YAML delimitado por ---." | O arquivo não começa com `---`. |
| "Frontmatter YAML não finalizado: delimitador de fechamento --- não encontrado." | Faltou o segundo `---`. |
| "Frontmatter YAML inválido: ..." | Erro de sintaxe no YAML (indentação, dois-pontos sem aspas etc.). |
| "O campo name é obrigatório no frontmatter." | Faltou `name:`. |
| "O campo description é obrigatório no frontmatter." | Faltou `description:`. |
| "Arquivo SKILL.md não encontrado no pacote zip." | O zip não tem o `SKILL.md` na raiz nem numa pasta única. |
Arquivos em `scripts/`, `references/` e `assets/` ficam guardados junto com a Skill, mas **o Agent não os executa nem os lê** hoje. Tudo o que o Agent precisa saber tem de estar no corpo do `SKILL.md`.
## Editar, remover e excluir
- **Editar** — no card da Skill (no passo Ferramentas ou no catálogo), clique no lápis (**Editar skill**). Você pode mudar tudo, menos o nome.
- **Remover do Agent** — a lixeira do card no passo Ferramentas (**Remover skill**) só desvincula a Skill daquele Agent. A Skill continua existindo para os outros.
- **Excluir** — no catálogo, a ação de excluir apaga a Skill do workspace e a remove de **todos** os Agents que a usam. Não dá para desfazer.
**O que exige republicar e o que não exige:**
- **Vincular ou desvincular** uma Skill de um Agent publicado → só vale **depois de publicar de novo**.
- **Editar a descrição ou o corpo** de uma Skill que já está vinculada → vale **na próxima mensagem**, sem republicar. A versão publicada guarda só a referência à Skill; o conteúdo é lido na hora.
Isso significa que editar uma Skill usada por vários Agents muda o comportamento de todos eles imediatamente. Teste no [Playground](/guia/agents/playground) antes de editar uma Skill em uso.
Se uma Skill vinculada for excluída, o atendimento não para: o Agent segue sem ela e as demais Skills continuam funcionando.
## Skills globais
Além das suas, existem Skills **nativas da plataforma**, marcadas com o badge **Global** ("Skill nativa da plataforma — somente-leitura").
- Você pode **vincular e desvincular** uma Skill global como qualquer outra.
- Você **não pode editar nem excluir** uma Skill global.
- Duas Skills globais entram **automaticamente em todo Agent**, sem vínculo, e com o corpo inteiro já na instrução (não pelo menu): `humanizer` (escrita natural, balões curtos separados por `---`, no máximo 5 mensagens por resposta) e `formatacao-whatsapp` (negrito, itálico e tachado no padrão do WhatsApp).
- Se você criar uma Skill local com o **mesmo nome** de uma global, quando o Agent pedir a Skill pelo nome é a sua versão que ele recebe.
Se o Agent está quebrando a resposta em vários balões ou formatando de um jeito que você não pediu, é efeito de `humanizer` e `formatacao-whatsapp`. Para mudar esse comportamento, escreva a regra contrária explicitamente na instrução do Agent.
## Skills em sub-agents
Cada sub-agent tem as próprias Skills, configuradas na aba **Ferramentas** do sub-agent (dentro de **Configurar sub-agente**). Uma Skill vinculada ao orquestrador **não** é herdada pelos sub-agents: vincule em cada um que precisar.
## Como escrever uma boa Skill
1. **Descrição = gatilho.** Diga *quando* usar ("Use quando...") e *o que tem dentro*. Evite descrições genéricas.
2. **Uma Skill, um assunto.** "Negociação de BPC/LOAS" e "Qualificação de BPC/LOAS" funcionam melhor como duas Skills do que como uma gigante.
3. **Estrutura com títulos.** Objetivo, critérios, perguntas, o que não fazer, quando encerrar. O modelo segue melhor um texto organizado.
4. **Explique o porquê.** "Não fale valores antes de confirmar o direito, porque o cliente desiste quando ouve o preço sem entender o benefício" funciona melhor que só "não fale valores".
5. **Use tabelas** para critérios, preços e listas de descarte.
6. **Separe descarte de dúvida.** Descarte só quando o próprio cliente confirmou o fato que inviabiliza o caso. Resposta vaga, conta que depende de documento ou regra com exceção é dúvida: a Skill deve mandar perguntar de novo e, se continuar sem clareza, encaminhar para um humano (por exemplo, transferindo a conversa para um departamento). Antes de descartar, peça que o Agent confira se outra Skill se aplica ao mesmo cliente: o mesmo fato que encerra um caso muitas vezes abre outro. Um caso bom descartado custa mais caro do que um caso fraco revisado por uma pessoa.
7. **Use os nomes exatos** de etapas do funil e tags que o Agent deve aplicar (ex.: `Closer`), para não gerar variações.
8. **Tamanho:** as Skills de negócio que funcionam bem na plataforma têm cerca de 3 KB. Não há problema em ser maior, já que o corpo só é carregado quando usado.
9. **Não use comentários HTML** (``) para anotações internas: eles vão junto para o modelo e custam tokens.
**Agents com saída estruturada não usam Skills.** Quando o nó **Agente de IA** está com saída estruturada ligada, a plataforma remove do Agent as Skills, as ferramentas e a base de conhecimento. Veja [Agente de IA → Saída estruturada](/guia/flow-builder/ia/agent-no#saida-estruturada-desativa-ferramentas-do-agent).
## Saiba mais
- [Ferramentas do Agent](/guia/agents/ferramentas) — visão geral de tudo que o Agent pode usar
- [Instruções e modelo](/guia/agents/instrucoes-modelo) — o que vai na instrução principal
- [Publicação e versões](/guia/agents/publicacao-e-versoes) — o que exige republicar
- [Playground ao vivo](/guia/agents/playground) — veja na trilha de execução quando o Agent chama `load_skill`