Atende Direito · Docs

Tema

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 AgentSkillBase de conhecimento
O que éQuem o Agent é e como ele se comporta sempreUm procedimento para uma situação específicaDocumentos de consulta (FAQ, manual, tabela)
Quando entra no contextoEm toda mensagemSó quando o Agent decide carregá-laSó os trechos parecidos com a pergunta
ReusoUm AgentVários Agents e sub-agentsVá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"
Dica

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 ​

  1. 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.

  2. 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.

  3. 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).

  4. 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.

Criar uma Skill ​

As Skills ficam no Catálogo de Ferramentas, acessado de dentro do assistente do Agent.

  1. Abra o Agent e vá ao passo Ferramentas. Na seção Skills cognitivas, clique em Gerenciar no Catálogo.

    Passo Ferramentas do assistente, com a seção 'Skills cognitivas' e o botão 'Gerenciar no Catálogo'.

    Passo Ferramentas do assistente, com a seção 'Skills cognitivas' e o botão 'Gerenciar no Catálogo'.

  2. 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.

    Aba Skills do Catálogo de Ferramentas, com as skills disponíveis, o selo Global e o botão Importar / criar skill.

    Aba Skills do Catálogo de Ferramentas, com as skills disponíveis, o selo Global e o botão Importar / criar skill.

  3. Janela Nova Skill (SKILL.md), com as abas Criar e Importar.

    Janela Nova Skill (SKILL.md), com as abas Criar e Importar.

    A janela Nova Skill (SKILL.md) abre na aba Criar. Preencha:

    CampoObrigatórioO que colocar
    NomeSimIdentificador 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 curtaSimQuando 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:

    CampoO que faz
    Recursos (um arquivo por linha)Lista de arquivos anexos. Hoje é só referência: o Agent não lê esses arquivos.
    LicençaTexto livre (ex.: MIT). Informativo.
    CompatibilidadeTexto livre, até 500 caracteres (ex.: modelos com que a Skill foi testada). Informativo.
    Ferramentas permitidasRestringe quais ferramentas o Agent pode usar. Leia o aviso abaixo antes de preencher.

  4. Clique em Criar skill. O botão fica desabilitado enquanto o nome não estiver em kebab-case válido.

  5. 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.

  6. 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.

Erros de validação comuns ​

MensagemCausa
"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:

ChaveObrigatóriaRegras
nameSimkebab-case, até 64 caracteres.
descriptionSimTexto, até 1024 caracteres.
licenseNãoTexto, até 255 caracteres.
compatibilityNãoTexto, até 500 caracteres.
metadataNãoMapa de chave → texto.
allowed-toolsNãoFerramentas 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 ​

LimiteValor
Texto colado ou SKILL.md256 KB
Arquivo enviado (.md ou .zip)10 MB
Arquivos dentro do zip200
Tamanho descomprimido do zip10 MB
Importações por minuto10

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 ​

MensagemCausa
"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.
Dica

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.

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.
Dica

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.

Saiba mais ​