Skill para agentes

Uma Agent Skill instalável que ensina o seu assistente a integrar a Amivu sem errar as armadilhas.

Uma Agent Skill é um procedimento que o assistente carrega sozinho quando o assunto aparece. A da Amivu ensina a integrar a API — e, principalmente, ensina o que a especificação não diz.

O que ela carrega

A especificação descreve a forma de tudo e nada sobre a ordem das coisas. Um agente só com ela descobre que POST /v1/messages existe, monta a chamada e erra nas mesmas armadilhas que todo mundo erra da primeira vez. A skill fecha essa lacuna:

O modelo em cinco linhas, e por que existe uma rota de envio só.
As quarenta rotas com o alcance de cada uma, em tabela.
As regras de toda chamada: tenant pela credencial, idempotência, cursor, formato de erro.
A conferência de assinatura de webhook, com a janela verificada antes do HMAC.
Dez armadilhas — que não existe /whatsapp/send, que status pode ser null, que message.sent chega quando o canal aceita e não quando o POST responde.

Ela instrui a começar pelo sandbox

A skill manda o agente perguntar qual ambiente usar antes de qualquer escrita. Mas instrução é sugestão: a garantia de verdade é criar uma chave amivu_test_… para ele — ver Ambientes.

Instalar

Baixe para dentro do seu projeto

A skill é um arquivo só. Ela mora no projeto que você está integrando — assim ela acompanha o repositório e vale para todo mundo do time, e não só para a sua máquina.

Terminal

mkdir -p .claude/skills/amivu-api
curl -o .claude/skills/amivu-api/SKILL.md \
  https://developers.amivu.com.br/skills/amivu-api/SKILL.md

Confirme que o assistente a enxerga

No Claude Code, /skills lista o que está carregado. A partir daí ela entra sozinha quando o assunto aparecer — você não precisa mencioná-la.

$ claude
> /skills

  amivu-api   Como integrar a API pública da Amivu…

Dê a ele uma chave de sandbox

Crie a chave no painel, em Configurações → Desenvolvedores, com o ambiente Sandbox e só os alcances que a tarefa precisa. Se o agente não precisa enviar, não dê messages:write: aí a pior coisa que ele consegue fazer é ler.

Terminal

export AMIVU_API_KEY="amivu_test_..."

Ela é gerada, e por isso não envelhece

As rotas, os alcances, os eventos e os códigos de erro da skill saem do mesmo catálogo que a referência, o openapi.json e a coleção leem. Rota nova aparece nos quatro no mesmo commit, ou em nenhum.

Isso importa mais para um agente do que para uma pessoa: quem lê uma documentação desatualizada estranha, procura de novo e acha. Um agente acredita no procedimento e erra com confiança — e o erro aparece como uma chamada que a API recusa, sem explicação óbvia.

Baixe de novo depois de uma versão nova

Não há atualização automática de um arquivo que vive no seu repositório. O changelog diz quando vale repetir o comando do passo 1.

Outros assistentes

O arquivo é Markdown com frontmatter — autossuficiente. Em assistentes que leem um arquivo de regras do projeto, aponte para ele ou cole o conteúdo:

mkdir -p .cursor/rules
curl -o .cursor/rules/amivu-api.md \
  https://developers.amivu.com.br/skills/amivu-api/SKILL.md

Se o seu assistente não aceita arquivo de contexto, o llms.txt é menor e serve para colar direto na conversa.

Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.