🧩 Entenda o que é uma skill
Skill é uma capacidade reutilizável que orienta o agente numa tarefa específica: analisar repositório, gerar especificação, criar plano, reproduzir bug, gerar testes, revisar arquitetura, revisar segurança, atualizar documentação, preparar pull request, modernizar módulo legado, analisar incidente, validar deploy.
Como ler: as caixas em ciano são skills — cada uma amplia o que o agente consegue fazer bem. A linha tracejada em volta são as rules: elas não ensinam nada, apenas definem por onde ninguém passa. Adicionar skill sem cercado é como aumentar potência sem freio.
Capacidade
Skill amplia
Limite
Rule cerca
Reuso
Menos variação
Uma tarefa
Por skill
🧱 Estruture uma skill
Dez campos bastam. Os dois que mais separam uma skill útil de um prompt salvo são "quando usar" (faz o agente escolher certo) e "ações proibidas" (evita o dano).
🧪 Exercício copiável — sua primeira skill
Objetivo: transformar um prompt que você já repete numa skill versionada. Crie skills/<nome>/SKILL.md com este esqueleto.
# Skill: <nome curto e verbal, ex.: revisar-api> ## Objetivo <o que esta skill entrega, em uma frase> ## Quando usar <gatilhos concretos: "quando o diff altera arquivos em src/api/"> ## Quando NÃO usar <casos em que outra skill é melhor> ## Entradas - <spec, diff, caminho, log... o que precisa existir antes> ## Ferramentas permitidas - <leitura de arquivos, execução de testes, busca... e nada além> ## Etapas 1. <passo> 2. <passo> 3. <passo> ## Ações proibidas - <não alterar testes, não instalar dependências, não commitar...> ## Tratamento de falhas - <se X falhar, pare e relate; não tente contornar> ## Formato da saída <estrutura exata: tabela, lista com severidade, arquivo:linha...> ## Verificações obrigatórias - <o que rodar antes de declarar pronto, com a saída real anexada>
Como verificar: peça a alguém do time para usar a skill numa tarefa real sem você explicar nada. Se essa pessoa precisar perguntar algo, o que faltou vira campo novo. Skill boa é a que funciona sem o autor por perto.
Quando usar
O campo mais importante
Proibições
Dentro da própria skill
Formato
Torna componível
Verificação
Fecha o loop
🗂️ Escolha quais skills criar primeiro
Priorize por frequência × variação de qualidade: tarefas que você repete muito e que hoje saem diferentes dependendo de quem faz. Skill de tarefa rara é manutenção sem retorno.
✓ Boas primeiras skills
- ✓Gerar especificação a partir de uma tarefa
- ✓Revisar PR com lente de segurança
- ✓Reproduzir bug e escrever o teste que falha
- ✓Preparar PR com evidências anexadas
✗ Skills que não se pagam
- ✗"Fazer qualquer coisa no repositório" (genérica demais)
- ✗Tarefa que acontece uma vez por semestre
- ✗Processo que ainda muda toda semana
- ✗Trinta skills criadas antes de usar a primeira
💡 Dica prática
Comece com três a cinco skills. Se em um mês uma delas não foi usada, ela não era prioridade — apague. Coleção grande de skills não usadas tem o mesmo problema de documentação morta: entra no contexto e atrapalha.
Frequência
Primeiro critério
Variação
Onde há mais ganho
3 a 5
Não trinta
Não usada
Apague
📏 Entenda o que são rules
Rules são regras permanentes ou condicionais que limitam o comportamento dos agentes. Elas valem em toda tarefa, independentemente da skill usada. Rules reduzem decisões arbitrárias.
Conjunto base — copie e adapte
- nunca alterar testes para esconder uma falha - nunca inserir segredos no repositório - não adicionar dependência sem justificar - preservar APIs públicas - não executar deploy sem aprovação - não modificar banco de produção diretamente - não remover logs de segurança - produzir evidência dos testes - limitar o número de tentativas - parar quando o custo ultrapassar o limite - pedir aprovação antes de ações destrutivas - não realizar refatoração fora do escopo
Permanente
Vale em toda tarefa
Arbitrariedade
É o que a rule corta
Clara
Uma linha, sem ambiguidade
Poucas
Lista longa é ignorada
🔐 Escreva rules de segurança e compatibilidade
Este é o núcleo duro: as regras cuja violação custa caro e é difícil de reverter. Elas merecem estar escritas — e, sempre que possível, viradas gate automático.
Nunca alterar testes para esconder falha
É a regra que protege o próprio conceito de "pronto". Sem ela, todo o resto do curso perde o sentido — o verificador deixa de ser confiável.
Nunca inserir segredos no repositório
Combine com o gate de detecção de segredos do módulo 3.3. Regra e verificação juntas: uma orienta, a outra impede.
Preservar APIs públicas e produzir evidência
Contrato público não muda sem versionamento. E toda entrega vem com a saída real dos testes — evidência é obrigação, não cortesia.
⚠️ Atenção
Rule sem verificação depende de obediência — e obediência de um sistema probabilístico não é garantia. Sempre que a regra for crítica e automatizável, transforme-a em gate. A rule continua valendo para orientar; o gate é quem impede.
Teste intocável
Protege o "pronto"
Segredo
Rule + gate
API pública
Contrato preservado
Evidência
Obrigação
🎚️ Use rules para limitar autonomia
Limite de tentativas, teto de custo, aprovação antes de ações destrutivas, proibição de refatoração fora do escopo: é a versão escrita e permanente dos limites que você configurou na trilha 2.
🔗 Onde cada peça vive
- •Rule (texto, sempre válida): "pedir aprovação antes de ações destrutivas".
- •Harness (configuração): a permissão que simplesmente não existe para o agente.
- •Gate (verificação): o pipeline que barra a mudança se a regra foi violada.
- •As três camadas se reforçam. Depender de uma só é aposta.
Checagem rápida: você escreveu a rule "nunca commitar segredo". Isso é suficiente?
Rule
Orienta
Harness
Nem dá a permissão
Gate
Impede na saída
Três camadas
Se reforçam
📌 Resumo do Módulo
Próximo Módulo:
5.3 - Governança e níveis de autonomia: quem é o agente e até onde ele vai.