Habilidades

Uma habilidade é um pacote reutilizável de instruções que ensina um especialista a executar um procedimento: fechar um orçamento, triar um chamado, redigir um laudo, conduzir uma entrevista de qualificação. Você escreve a habilidade uma vez e instala em quantos especialistas quiser.

O que diferencia uma habilidade de simplesmente escrever tudo no prompt do especialista é quando o conteúdo chega até o agente. O prompt acompanha o agente em toda conversa, o tempo inteiro. Uma habilidade fica guardada e só é aberta quando o assunto aparece — o que permite que ela seja muito maior e muito mais detalhada do que caberia num prompt.

Como o agente descobre e usa uma habilidade

O agente trabalha com uma habilidade em três camadas, abrindo cada uma só quando precisa da anterior:

1. Índice. Em toda conversa, o agente enxerga apenas o nome e a descrição de cada habilidade instalada. É por essa descrição que ele decide se a habilidade serve para o pedido do usuário.
2. Roteiro. Quando decide que serve, ele abre o SKILL.md — o documento principal, com o passo a passo do procedimento.
3. Arquivos de apoio. Se o roteiro mandar consultar um anexo, ele abre aquele anexo específico. Os demais ficam de fora — o agente não carrega a pasta inteira para dentro da conversa.

dica

Pense na habilidade como uma pasta de procedimento na mesa de um atendente novo. A etiqueta da pasta (a descrição) ele lê o tempo todo. O procedimento em si ele só lê quando o caso aparece. E os anexos — a tabela de preços, o contrato na íntegra, os exemplos — ele só puxa quando o procedimento pede.

Essa separação é o que mantém o agente rápido e barato mesmo com muitas habilidades instaladas: nada é lido "por precaução".

Anatomia do SKILL.md

Toda habilidade começa por um documento chamado SKILL.md. Ele tem um cabeçalho e um corpo:

---
name: triagem-de-chamados
description: Classifica um chamado de suporte por urgência e área
  responsável. Use quando o cliente relata um problema, erro ou
  indisponibilidade.
---

# Triagem de chamados

## Passo 1 — Entender o problema

Pergunte ao cliente o que ele estava fazendo quando o problema apareceu...

## Passo 2 — Classificar a urgência

Consulte os critérios em `referencias/matriz-de-urgencia.md` e escolha
uma das quatro faixas.

## Passo 3 — Encaminhar

...

O cabeçalho

Campo	O que é
name	O identificador da habilidade. Use letras minúsculas, números e hífens (ex.: triagem-de-chamados). É o nome pelo qual o especialista a instala.
description	O campo mais importante. É a única coisa que o agente lê antes de decidir abrir a habilidade.

A description precisa responder duas perguntas: o que a habilidade faz e quando usá-la. Uma descrição vaga faz o agente ignorar a habilidade nos casos em que ela era exatamente o que faltava.

# Vago demais — o agente não sabe quando acionar
description: Ajuda com chamados.

# Bom — diz o que faz e em que situação
description: Classifica um chamado de suporte por urgência e área
  responsável. Use quando o cliente relata um problema, erro ou
  indisponibilidade.

O corpo

O corpo é markdown livre: passo a passo, regras, exemplos, o que for necessário para o agente executar o procedimento sem improvisar.

Mantenha-o curto — até cerca de 20 KB. Quando o agente aciona a habilidade, o documento inteiro entra na conversa. Material pesado não vai aqui: vai nos arquivos de apoio.

Arquivos de apoio

São os anexos da habilidade: tudo que é volumoso, consultado só às vezes, ou que faria o roteiro perder a legibilidade. Não confunda com os anexos que o usuário manda na conversa — para esses, veja Anexos de conversa.

• tabelas de referência (preços, códigos, prazos, matrizes de decisão)
• políticas e contratos na íntegra
• exemplos longos de texto pronto
• listas de perguntas por segmento
• roteiros alternativos para casos específicos

Cada arquivo é aberto sob demanda, individualmente. Ter vinte arquivos de apoio não deixa o agente mais lento: ele abre um, dois, nenhum — conforme o roteiro pedir.

Cada arquivo pode ter até cerca de 256 KB, bem mais que o SKILL.md. Todos são arquivos de texto (markdown, CSV, YAML, JSON e afins).

Regra de ouro: cite o caminho no SKILL.md

O agente enxerga a lista dos arquivos de apoio da habilidade, então um arquivo sem citação não fica inalcançável — ele até pode ser aberto. Mas o agente não vasculha os arquivos procurando algo útil: abrir um que o roteiro não mencionou seria um palpite dele. Citar é o que troca o palpite por instrução. Um arquivo que não é citado em lugar nenhum é lido quando dá, não quando precisa — e "quando dá" costuma ser nunca.

Sempre que criar um arquivo de apoio, escreva no corpo do SKILL.md quando consultá-lo:

Para escolher a faixa de urgência, consulte
`referencias/matriz-de-urgencia.md`.

Se o cliente for do setor público, use o modelo de resposta em
`modelos/resposta-orgao-publico.md` no lugar do padrão.

Repare que a citação diz em que situação abrir o arquivo, não só que ele existe. É a mesma lógica da description.

Nomes de arquivo

Os caminhos aceitam pastas, o que ajuda a organizar habilidades grandes:

referencias/matriz-de-urgencia.md
referencias/codigos-de-produto.csv
modelos/resposta-padrao.md
modelos/resposta-orgao-publico.md

As regras são simples:

• caminho relativo — não comece com /
• apenas letras, números, ., _ e - (sem espaços e sem acentos)
• até 8 níveis de pastas
• SKILL.md é reservado para o documento principal

Arquivos compartilhados entre habilidades

Às vezes o mesmo material serve a várias habilidades: um glossário da empresa, uma tabela de preços, o tom de voz da marca. Se você copiar esse material dentro de cada habilidade, as cópias divergem na primeira edição que esquecer alguma.

Para isso existe a área compartilhada, uma pasta da sua organização que fica fora de qualquer habilidade. O roteiro cita o arquivo pelo caminho /shared/...:

Antes de responder, confira os termos em `/shared/padroes/glossario.md`.

Se o cliente perguntar preço, use `/shared/comercial/tabela-2026.csv` —
nunca responda de memória.

A mesma citação funciona em quantas habilidades você quiser, e editar o arquivo uma vez atualiza todas.

Quem enxerga o quê

Um especialista não enxerga a área compartilhada inteira por padrão — ele declara quais pastas pode ler:

installed_shared:
  - padroes
  - comercial

Declarar padroes dá acesso a tudo abaixo dela (padroes/glossario.md, padroes/tom/formal.md, e assim por diante). É pasta, não arquivo a arquivo — um pacote pode ter centenas de arquivos.

aviso

Lista vazia significa que o especialista não enxerga nada. Não é o contrário. Se uma habilidade cita /shared/padroes/glossario.md e o especialista não declarou padroes, a leitura falha — de propósito.

Duas coisas que costumam surpreender:

• declarar padrao não dá acesso a padroes/ — o nome da pasta tem que bater inteiro;
• os arquivos compartilhados não ocupam espaço no índice, porque não têm nome nem descrição para o agente escolher. Você pode ter muitos sem prejudicar a lista de habilidades do especialista.

Compartilhado ou arquivo de apoio?

Use arquivo de apoio	Use a área compartilhada
só aquela habilidade consulta	duas ou mais habilidades consultam
o conteúdo é parte do procedimento	o conteúdo é da empresa, não do procedimento
morre junto com a habilidade	sobrevive à habilidade que o citou

Na dúvida, comece com arquivo de apoio. Mover para a área compartilhada depois é fácil; descobrir três cópias divergentes, não.

Instalando em um especialista

Liste a habilidade pelo name no campo installed_skills do especialista:

installed_skills:
  - triagem-de-chamados
  - resumo-de-documentos

Só as habilidades listadas ficam visíveis para aquele especialista. Se elas consultarem a área compartilhada, declare também as pastas:

installed_skills:
  - triagem-de-chamados
  - resumo-de-documentos
installed_shared:
  - padroes

Veja a configuração do especialista para os campos no contexto do arquivo completo.

observação

Há um limite prático para o índice — a soma de nomes e descrições de todas as habilidades instaladas em um mesmo especialista. Se você instalar muitas habilidades de descrição longa, as últimas da lista deixam de ser oferecidas ao agente. Descrições objetivas resolvem: uma ou duas frases bastam.

Instalando um pacote de habilidades

Criar habilidade por habilidade na tela funciona para uma ou duas. Para um conjunto — um método de trabalho inteiro, com dezenas de roteiros e seus anexos — você monta o pacote fora e sobe um arquivo .zip.

O formato

Cada pasta na raiz do zip vira uma habilidade, e o SKILL.md dentro dela é o roteiro:

meu-pacote.zip
├── triagem-de-chamados/
│   ├── SKILL.md
│   ├── referencias/matriz-de-urgencia.md
│   └── modelos/resposta-padrao.md
├── resumo-de-documentos/
│   └── SKILL.md
└── _shared/
    ├── padroes/glossario.md
    └── comercial/tabela-2026.csv

A pasta _shared/ é reservada: o que estiver nela vai para a área compartilhada, não vira habilidade. Os caminhos ficam relativos a ela — o glossario.md acima é citado como /shared/padroes/glossario.md.

Se você zipar a pasta que contém tudo (zip -r pacote.zip meu-pacote/), o envelope extra é descartado sozinho.

O plano vem antes

Ao subir o zip, a plataforma mostra o que vai acontecer antes de fazer: quantas habilidades são novas, quantas serão sobrescritas, quais arquivos entram, o que foi recusado e por quê. Nada é gravado até você confirmar.

Vale ler a lista de recusados: uma pasta sem SKILL.md, um nome inválido ou um arquivo grande demais é recusado individualmente, e o resto do pacote entra normalmente. Um pacote parcialmente aceito é comum e não é erro — mas se o que faltou era importante, é ali que você descobre.

Levando embora

O caminho inverso também existe: você exporta um pacote e recebe o mesmo formato de volta, pronto para versionar em outro lugar ou levar para outra organização. Exportar uma habilidade traz só ela; exportar o pacote traz também a área compartilhada.

Pedindo à Aura

A Aura é a assistente da própria plataforma — o agente com quem você conversa para configurar o que os seus agentes fazem. Ela cria e edita habilidades a seu pedido, sem você abrir a tela:

Crie uma habilidade de triagem de chamados. O agente deve classificar a urgência, e para os critérios de urgência deixe um arquivo de apoio à parte, porque a tabela muda toda hora.

Ela conhece as regras deste manual — as três camadas, o teto de cada parte, e principalmente a regra de citar o caminho no roteiro. Se você pedir um arquivo de apoio e o roteiro não citá-lo, ela avisa.

Também dá para pedir revisão de habilidade existente:

Olha a habilidade triagem-de-chamados e me diz se a descrição está boa o bastante para o agente saber quando acionar.

Ela alcança a área compartilhada do mesmo jeito, e sabe que criar o arquivo não basta — o especialista precisa enxergar a pasta:

Cria um glossário compartilhado com estes termos e deixa o especialista de atendimento enxergando.

Isso é uma armadilha real, e vale saber que ela conhece: como a leitura é fail-closed, um arquivo compartilhado criado sem o especialista declarar a pasta nasce inerte — existe, mas ninguém lê.

observação

O que ainda é só pela tela: instalar um pacote .zip. A Aura cria e edita habilidades, arquivos de apoio e arquivos compartilhados, e configura o que cada especialista enxerga — mas subir um pacote inteiro ainda é pela interface.

Como escrever uma boa habilidade

Uma habilidade, um procedimento. Se o SKILL.md está tentando cobrir triagem e orçamento e cobrança, são três habilidades. Separadas, o agente escolhe melhor qual usar.

Escreva para quem não conhece o contexto. A habilidade não herda o que foi dito na conversa nem o que está no prompt do especialista. Ela precisa se sustentar sozinha.

Prefira passos numerados a texto corrido. O agente segue sequência muito melhor do que interpreta parágrafos.

Deixe explícito o que NÃO fazer. Limites ("nunca prometa prazo sem consultar a tabela", "não ofereça desconto acima de 10%") evitam a maior parte dos desvios.

Empurre volume para os anexos. Se você está colando uma tabela grande dentro do SKILL.md, ela provavelmente é um arquivo de apoio.

Erros comuns

Sintoma	Causa provável	Correção
O agente nunca usa a habilidade	A description não diz quando usar	Reescreva a descrição citando a situação-gatilho
O agente usa a habilidade fora de hora	A description está ampla demais	Restrinja e diga explicitamente o que está fora do escopo
O agente ignora um arquivo de apoio	O caminho não é citado no SKILL.md	Cite o caminho e a situação em que consultá-lo
O agente segue o roteiro pela metade	Passos longos e em texto corrido	Numere os passos e quebre em ações curtas
As últimas habilidades da lista não aparecem	Índice cheio de descrições longas	Encurte as descrições ou reduza a lista
Não consigo salvar o SKILL.md	Passou do tamanho recomendado	Mova o material pesado para arquivos de apoio
O agente não lê um arquivo compartilhado	O especialista não declarou a pasta em installed_shared	Acrescente a pasta — lista vazia não enxerga nada
Declarei a pasta e ainda não lê	O nome não bate inteiro (padrao não abre padroes/)	Confira o nome da pasta, sem abreviar
Parte do pacote não entrou	Recusa por entrada — pasta sem SKILL.md, nome inválido, arquivo grande	Leia a lista de recusados do plano; o resto entrou
O que estava em _shared/ virou habilidade	O zip foi montado com _shared/ fora da raiz	_shared/ só é reservada na raiz do pacote
Uma habilidade que estava em _shared/ sumiu	SKILL.md dentro da área compartilhada é sempre recusado	Tire a habilidade de dentro de _shared/ — lá vão só os arquivos que várias habilidades leem