Como criar skills de IA para advogados e programadores

Uma skill é uma pasta de instruções que um assistente de inteligência artificial carrega sozinho quando reconhece que a tarefa pede aquele conhecimento. Em vez de repetir no chat, toda vez, como o escritório redige uma petição ou como a equipe faz o deploy de um sistema, você escreve isso uma vez, com regras, passo a passo e arquivos de apoio, e o assistente passa a seguir o mesmo padrão. O formato foi publicado pela Anthropic como padrão aberto e funciona nos aplicativos do Claude, no Claude Code e na API. Este guia mostra, passo a passo, como planejar, escrever, testar e proteger uma skill, com exemplos para a advocacia e para quem programa.

O que é uma skill, por dentro

Toda skill é um diretório com um arquivo principal chamado SKILL.md. Esse arquivo começa com um cabeçalho em YAML, um formato simples de chave e valor, com dois campos obrigatórios: name e description. Depois do cabeçalho vem o corpo, em texto comum, com as instruções. A pasta pode ter ainda modelos, tabelas de referência e scripts, que são pequenos programas que o assistente executa quando precisa de um resultado exato, sempre igual.

O assistente não lê tudo de uma vez. A documentação chama isso de revelação progressiva, em três níveis:

• Nível 1: só o nome e a descrição de cada skill instalada ficam visíveis desde o início, para o assistente saber quando cada uma se aplica.
• Nível 2: quando a tarefa combina com a descrição, ele abre o corpo do SKILL.md.
• Nível 3: arquivos de apoio só são abertos se a tarefa exigir.

Por isso a descrição é a parte mais importante: é ela que decide se a skill será usada.

Regras do cabeçalho

As regras oficiais são objetivas:

• name: até 64 caracteres, só letras minúsculas, números e hífens, sem tags XML e sem as palavras reservadas "anthropic" e "claude". Exemplo: revisando-contratos.
• description: obrigatória, até 1.024 caracteres, sem tags XML, dizendo o que a skill faz e quando deve ser usada. Exemplo: "Revisa contratos de prestação de serviços e aponta cláusulas de risco. Usar quando o usuário enviar um contrato ou pedir revisão contratual."
• O guia de boas práticas recomenda, sem tornar obrigatório, escrever a descrição em terceira pessoa e manter o corpo abaixo de 500 linhas. Passando disso, divida em arquivos de referência, sempre a um nível de distância do SKILL.md.

Passo 1: escreva o PRD antes da skill

PRD é a sigla em inglês para documento de requisitos do produto. Parece coisa de empresa de software, mas é só um texto curto que responde, antes de escrever qualquer instrução:

1. Problema: o que dá errado hoje? Exemplo: "as petições de BPC saem com a lista de documentos incompleta".
2. Usuário: quem vai usar? O advogado, o estagiário, o próprio desenvolvedor.
3. Requisitos: o que a skill precisa fazer, item por item.
4. Critérios de aceite: como saber que funcionou. Exemplo: "toda petição sai com a qualificação conferida contra o documento de identidade e com o rol de documentos da tese".
5. Fora de escopo: o que a skill não faz. Isso evita que ela tente resolver tudo e erre.

O PRD vira o esqueleto da skill: os requisitos viram o passo a passo, e os critérios de aceite viram o checklist final.

Passo 2: teste o assistente sem a skill

A documentação recomenda criar as avaliações antes de escrever a documentação longa. Na prática:

• escolha pelo menos três tarefas reais e representativas;
• peça ao assistente que as resolva sem a skill e anote onde ele erra;
• guarde essas tarefas: elas serão a régua para medir se a skill melhorou o resultado.

Esse teste mostra o que realmente precisa ser escrito. O que o assistente já faz bem sozinho não precisa ocupar espaço na skill.

Passo 3: escreva o SKILL.md

As skills que funcionam de verdade, no escritório e na programação, seguem a mesma anatomia. Cada parte tem um motivo:

1. Cabeçalho com gatilhos: a description diz o que a skill faz e as frases que a acionam ("revisar a peça", "conferir antes de protocolar").
2. Por que existe: o erro real que deu origem à regra. Quem lê entende o risco e não "simplifica" a regra depois.
3. Regras inegociáveis, numeradas e curtas.
4. Quando usar e quando não usar, para a skill não invadir tarefas de outra.
5. Passo a passo com conferência a cada etapa.
6. Armadilhas conhecidas: cada erro que já aconteceu vira uma linha.
7. Checklist de saída com resultado binário: "pronto" ou "bloqueado, por este motivo", nunca "quase pronto".
8. Registro de versão: a skill é viva; toda correção entra com data.

Três cuidados de redação, todos da documentação oficial:

• Seja conciso. Cada parágrafo precisa justificar o espaço que ocupa. Não explique o que é uma petição; explique como o seu escritório faz.
• Ajuste a liberdade à fragilidade. Revisão de texto aceita várias abordagens: instrução em texto basta. Um procedimento que não pode variar, como uma migração de banco de dados, merece um script exato com a ordem "não altere o comando".
• Use sempre os mesmos termos. Se chamou de "qualificação das partes", não troque por "dados do cliente" no parágrafo seguinte.

Modelo 1, advocacia: o sócio revisor antes do protocolo

A skill mais valiosa de um escritório é a que impede uma boa peça de morrer por um erro bobo. Ela não reescreve: aponta o que corrigir, com a localização de cada problema.

---
name: revisando-peca-antes-do-protocolo
description: Faz a auditoria final de uma peça jurídica pronta, antes do protocolo, em cinco frentes (fatos e provas, qualificação, fundamentos, coerência e pedidos) e devolve uma nota técnica. Usar quando o usuário pedir para revisar a peça, conferir antes de protocolar, checar jurisprudência ou conferir coerência.
---
# Revisão final antes do protocolo

## Por que existe
Uma peça excelente já perdeu força por um CNPJ do réu copiado para o RG do cliente, herdado de uma minuta antiga. Esta skill confere tudo contra os autos, nunca contra minutas.

## Regras inegociáveis
1. Toda afirmação sobre os autos indica documento e página. Sem localização: NÃO LOCALIZADO.
2. Nome, CPF, RG, estado civil e endereço conferidos contra o documento de identidade e o comprovante de residência dos autos.
3. Prazo só vale com o registro do sistema do tribunal. Sem ele: PRAZO NÃO CONFERIDO.
4. Julgado ou artigo de lei só entra se estiver aberto na fonte oficial. De memória, nunca.
5. A revisão aponta erro, não preferência de estilo. O que está certo não se "arruma".

## Quando não usar
- Para redigir a peça (isso é de outra skill).
- Sem os autos completos: pedir os documentos antes de começar.

## Passo a passo
1. Ler a peça inteira e os documentos citados.
2. Conferir a qualificação de cada parte, campo a campo.
3. Conferir cada fato contra a prova indicada (documento e página).
4. Conferir cada fundamento na fonte oficial.
5. Conferir se cada tese termina em um pedido correspondente e se nenhum capítulo contradiz outro.

## Armadilhas conhecidas
- Dado herdado de minuta anterior.
- Pedido sem tese que o sustente, ou tese sem pedido.
- Artigo de lei com inciso trocado.

## Checklist de saída
- [ ] Nota técnica com cada item marcado CONFERIDO (fonte e página) ou NÃO CONFERIDO (motivo).
- [ ] Resultado final: APROVADA ou DEVOLVIDA, com a lista exata do que corrigir.

## Versão
- 2026-10-16: criada a partir de um erro real de qualificação.

Modelo 2, operação: quando o caminho direto trava

Serve para qualquer equipe que usa IA para operar sistemas (tribunais, portais, painéis): em vez de parar no primeiro bloqueio, a skill ensina a procurar a porta vizinha, com limites claros.

---
name: resolvendo-bloqueios-de-operacao
description: Quando uma ação trava pelo caminho direto (botão desabilitado, página que não carrega, upload recusado), testa até três vias alternativas na mesma conta e prova o resultado. Usar quando o usuário disser "resolva", "faça os cliques" ou quando uma ferramenta devolver bloqueio.
---
# Quando o botão não aparece, achar a outra porta

## Regras inegociáveis
1. Ordem já dada não se pergunta de novo: a dúvida operacional se resolve tentando.
2. No máximo três vias por bloqueio. Depois disso, relatar o erro exato e o único gesto que falta ao usuário.
3. Olhar antes de afirmar: captura de tela ou leitura da página antes de dizer que algo não existe.
4. Provar por dois sinais (a tela e um registro) antes de dizer "feito".
5. Sem via alternativa para: senha, código de verificação, pagamento, exclusão definitiva e envio de mensagem sem ordem. Nesses casos, dizer em uma linha o que só o usuário pode fazer.

## Passo a passo
1. Nomear o bloqueio com a mensagem exata.
2. Tentar a via vizinha: a mesma conta em outro navegador, a versão web do aplicativo, outra ferramenta.
3. Conferir o estado antes de repetir qualquer clique de "enviar" ou "salvar".

## Checklist de saída
- [ ] Resultado provado por dois sinais, ou relatório com as três tentativas e o gesto que falta.

Modelo 3, programação: código real ou nada

Para quem programa, a skill que mais economiza retrabalho é a que proíbe o código "de exemplo" entregue como se fosse pronto.

---
name: entregando-codigo-real
description: Regra de entrega de qualquer código (script, integração, módulo): ou roda de ponta a ponta, ou o bloqueio é declarado com a solução exata. Proíbe trechos de exemplo, simulações não rotuladas e pendências escondidas. Usar sempre que entregar código, inclusive scripts rápidos.
---
# Código real ou nada

## Por que existe
Código ilustrativo entregue como pronto parece funcionar e não roda. O custo aparece depois, em produção, quando ninguém lembra que era "só um exemplo".

## Regras inegociáveis
1. Nada de marcadores de pendência, simulações sem rótulo ou "resto igual" na entrega.
2. Dependências declaradas com versão fixa.
3. Tratamento de erro em toda chamada externa.
4. Instruções de execução e de teste junto com o código.
5. Testes e build rodados de verdade antes de dizer que terminou; a saída do comando acompanha a entrega.

## Passo a passo
1. Escrever o teste que prova o comportamento esperado.
2. Implementar até o teste passar.
3. Rodar tudo (testes, verificação de tipos, build) e anexar o resultado.
4. Registrar no histórico do projeto o que mudou e por quê.

## Checklist de saída
- [ ] Status final: PRONTO PARA RODAR, ou BLOQUEADO com a causa e a solução exata.

Mais ideias para começar

• Advocacia: controle de prazos (fonte única: o sistema do tribunal, nunca o nome de uma pasta); revisão de contrato com uma tabela de cláusulas de risco num arquivo de apoio aberto só quando há contrato para revisar.
• Programação: revisão de código com o que bloqueia uma entrega; deploy com validação a cada etapa, num ciclo de rodar o validador, corrigir e repetir até passar; entrega contínua com manifesto de integridade e conferência de tamanho de cada arquivo.

Passo 4: teste, compare e versione

Rode de novo as três tarefas do passo 2, agora com a skill, e compare com o resultado anterior. A recomendação oficial é testar com todos os modelos que você pretende usar, porque um modelo menor pode precisar de mais detalhe do que um maior. Observe também se a skill é acionada quando deveria: se não for, o problema quase sempre está na descrição.

Guarde a pasta da skill num controle de versões, como o Git, e anote em cada mudança o motivo. Quando o assistente errar, a correção vai para a skill, e não só para a tarefa daquele dia. Assim o mesmo erro não se repete.

Passo 5: segurança, sigilo e dados pessoais

Uma skill tem o mesmo poder de um programa instalado. A documentação oficial recomenda:

• usar só skills criadas por você ou vindas de fonte confiável;
• auditar tudo antes de usar (instruções, scripts e imagens), procurando chamadas de rede inesperadas e acessos a arquivos que não combinam com a finalidade declarada;
• desconfiar de skills que buscam conteúdo em endereços externos, porque esse conteúdo pode trazer instruções maliciosas.

Para quem advoga, há ainda o dever legal de sigilo. O Estatuto da Advocacia garante a inviolabilidade dos arquivos e das comunicações do advogado relativas ao exercício da profissão e trata como infração violar, sem justa causa, o sigilo profissional (Lei nº 8.906/1994, art. 7º, II, e art. 34, VII). O Código Penal tipifica como crime revelar, sem justa causa, segredo de que tem ciência em razão da profissão e cuja revelação possa produzir dano a outrem (art. 154). E a Lei Geral de Proteção de Dados exige medidas técnicas e administrativas para proteger dados pessoais contra acessos não autorizados e vazamentos (Lei nº 13.709/2018, art. 6º, VII e VIII, e art. 46).

Na prática, isso vira regra dentro da skill:

• nunca colocar dados reais de clientes nos exemplos; use nomes e números fictícios;
• nunca escrever senha, token ou chave de API dentro da skill ou do chat;
• exigir revisão humana antes de qualquer peça, contrato ou código sair do escritório;
• registrar a regra "só cite o que está aberto no documento", proibindo número de processo, julgado ou artigo de lei de memória.

O que muda na prática

Com uma skill bem escrita, o padrão do escritório ou da equipe deixa de depender da memória de quem pede. O roteiro é sempre o mesmo:

1. Escreva o PRD.
2. Teste o assistente sem a skill.
3. Escreva um SKILL.md curto, com descrição precisa e checklist.
4. Teste de novo, compare e versione.
5. Proteja sigilo e dados pessoais desde o primeiro exemplo.

Cada correção gravada na skill vira uma melhoria permanente, em vez de um ajuste que se perde na próxima conversa.