Aula 4
Skills: conhecimento procedural versionado
O que é uma skill
Uma pasta com um SKILL.md, versionada no repositório, que ensina o agente a executar uma tarefa.
.claude/skills/nova-migracao/ ├── SKILL.md # name, description e os passos ├── scripts/ # executados, não lidos ├── references/ # lidos se precisar └── assets/ # templates, exemplos
Um exemplo: SKILL.md
---
name: nova-migracao
description: Cria uma migração SQL seguindo as convenções do projeto.
Use ao adicionar ou alterar tabela, coluna ou índice.
metadata:
intencao: executiva
interacao: interativa
---
# Nova migração
1. Rode scripts/checar.sh para ver a última migração aplicada.
2. Copie assets/template.sql para db/migrations/AAAAMMDD_<nome>.sql.
3. Siga os nomes de tabela e índice de references/convencoes.md.
4. Mostre o SQL ao usuário e peça confirmação antes de aplicar.
5. Rode npm test. Se falhar, desfaça a migração e explique o erro.
O frontmatter é o que o agente vê sempre. O corpo só entra quando a description casa com o pedido.
Divulgação progressiva
Metadados, sempre no contexto
name e description, cerca de 100 tokens
Corpo, quando a skill é relevante
O SKILL.md inteiro entra na janela
Arquivos, sob demanda
Referências abertas e scripts executados só se o passo exigir
Skill é uma decisão de delegação
Toda skill declara quanto o agente pode fazer sozinho.
Assistiva
Orienta ou analisa, sem ação irreversível.
Executiva
Produz efeito real: escreve arquivo, abre merge request, faz deploy.
Modos de interação
Interativa
Pede entrada do usuário antes ou durante a execução.
Reativa
Disparada pelo usuário, vai até o fim sem perguntar mais nada.
Autônoma
Dispara sozinha, por agenda ou evento, sem ninguém pedir.
Risco
O pior que acontece se a skill rodar até o fim sem humano no laço.
Nenhum
Só leitura e análise.
Baixo
Arquivo local ou artefato reversível.
Médio
Abre MR ou ticket, manda mensagem, altera estado de um serviço.
Alto
Mudança em produção ou em sistema regulado da organização.
502 skills de um catálogo corporativo
O tamanho de cada skill: número de palavras no corpo do SKILL.md.
Uma empresa com cerca de 8 mil engenheiros. Mediana de 734 palavras por skill. Fonte: Pinto, One in Three Enterprise Agent Skills Misrepresent Their Own Autonomy, preprint, 2026.
O que se delega
Nenhum domínio tem maioria. Dados e ML lideram com 23%.
Quanto humano fica no laço
As 502 skills, por modo de interação.
| Modo | O humano... | Total |
|---|---|---|
| Interativa | responde durante a execução | 59% |
| Reativa | só dispara, e espera o fim | 31% |
| Autônoma | nem dispara | 11% |
- Na maioria, ainda tem alguém no laço. O caso mais comum é a skill que conduz o processo, pergunta, e não faz nada irreversível
- Mas 11% das skills, 53 no total, disparam sozinhas, sem ninguém pedir: monitoramento, alertas, relatórios agendados
Declarado e executado
A skill faz o que o rótulo diz?
Declarado
O que a skill diz de si mesma: assistiva ou executiva.
Executado
O que o corpo permite: tem bloco de shell? Para e pergunta ao usuário?
- Sub-declarada: diz que só orienta, mas roda shell
- Super-declarada: diz que age, mas para e pede confirmação
Uma em cada três skills não bate com o rótulo
As 502 skills, comparando o que dizem de si mesmas com o que o corpo permite.
| Célula | Diz que... | Na prática... | Total |
|---|---|---|---|
| Alinhada assistiva | só orienta | só orienta | 52% |
| Alinhada executiva | age | age, sem parar | 15% |
| Super-declarada | age | para e pede confirmação | 20% |
| Sub-declarada | só orienta | roda shell em sistema real | 13% |
- Somando as duas últimas linhas, 33% das skills não fazem o que o rótulo diz. E todas passaram pela revisão do catálogo
- A sub-declarada é a mais perigosa: quem revisa pelo rótulo a trata como baixo risco
Exercício: três skills para o PR da aula 3
Uma skill de cada modo, cada uma cobrindo um momento diferente daquele PR.
- Interativa: planejar o PR. A skill pergunta escopo, arquivos afetados e critério de pronto antes de qualquer código
- Reativa: fechar o PR. Disparada por vocês, roda os testes, atualiza a documentação e abre o PR, sem perguntar nada
- Autônoma: vigiar o PR. Dispara sozinha quando o CI falha, por hook ou GitHub Action, e comenta a causa provável
Declarem em metadata a intenção e o modo de cada uma. Registrem em diario/2026-09-22.md se cada skill fez o que declarava, e em qual célula da matriz caiu.
Commit no dia. Leitura da semana: From Anatomy to Smells: An Empirical Study of SKILL.md (arxiv.org/abs/2607.01456).