Skills:
instruções que
o agente lê
quando precisa

1.1 O contexto é finito, e o conhecimento não

Uma skill é a saída deste dilema. É uma pasta com instruções que o agente sabe que existem mas só lê quando a tarefa as pede. O índice está sempre presente; o conteúdo entra a pedido.

1.2 A definição, em uma frase

1.3 A analogia que funciona

Pense num colega competente que chega à equipa. Ele não precisa que lhe expliquem programação — precisa que lhe digam as coisas específicas desta casa: como se escreve um commit aqui, onde ficam os ficheiros, que verificações correm antes de entregar, qual é a paleta da marca.

Uma skill é a página do manual interno que ele lê quando a tarefa a exige — não o manual inteiro decorado à entrada. E, tal como um manual interno bom, vale pela especificidade: uma skill que diz «escreva bom código» não acrescenta nada ao que o modelo já sabe.

1.4 Deixou de ser uma coisa de um fornecedor

1.5 O que esta série é, e como está organizada

Pares no catálogo: MCP — que esta série trata por outro ângulo e sem supor que já foi lida —, Agentes de IA, Engenharia de LLM, Aceleração de Código com IA e LLMOps & Avaliação.

2.1 A estrutura de pastas

nome-da-skill/
├── SKILL.md          # obrigatório: metadados + instruções
├── scripts/          # opcional: código executável
├── references/       # opcional: documentação consultada a pedido
├── assets/           # opcional: modelos, imagens, dados
└── ...               # quaisquer outros ficheiros

Só o SKILL.md é obrigatório. Uma skill perfeitamente útil pode ser uma pasta com um único ficheiro de trinta linhas — e a maioria das boas são exactamente isso.

2.2 O cabeçalho, campo a campo

2.3 O ficheiro mínimo que funciona

---
name: relatorio-mensal
description: Gera o relatório mensal no formato da equipa, com as três secções fixas
  e a tabela de indicadores. Use quando pedirem o relatório do mês, o fecho mensal
  ou os números do período.
---

# Relatório mensal

## Estrutura obrigatória
1. Resumo em três linhas, sem números.
2. Tabela de indicadores (ver `references/INDICADORES.md`).
3. «O que isto não diz» — limitações dos dados do período.

## Regras
- Nunca inventar valores em falta. Escrever «sem dados» e contar quantos faltam.
- Datas sempre em formato absoluto.

São dezasseis linhas e é uma skill completa e válida. A tentação de a tornar exaustiva é o erro mais comum de quem começa — o capítulo 10 explica porquê.

2.4 Os limites recomendados

• Mantenha o SKILL.md abaixo de 500 linhas. Acima disso, mova a matéria detalhada para references/.
• Corpo abaixo de ~5000 tokens, recomendado — é o que entra em contexto de uma vez quando a skill activa (capítulo 3).
• Referências a um nível de profundidade a partir da raiz da skill. Cadeias de ficheiros que apontam para ficheiros que apontam para ficheiros são difíceis de seguir e caras em contexto.

2.5 Validar

Existe uma ferramenta de referência para verificar se o cabeçalho é válido e se as convenções de nomenclatura estão cumpridas:

skills-ref validate ./a-minha-skill

Vale a pena corrê-la antes de partilhar seja o que for. Um name que não coincide com o nome da pasta é o erro silencioso mais comum: a skill não é carregada e não há mensagem de erro nenhuma.

3.1 Os três níveis

3.2 A consequência de desenho

Perceber os três níveis muda como se escreve uma skill:

3.3 O teste que revela se a divisão está certa

3.4 O erro que a divulgação progressiva torna caro

4.1 O que a descrição está a fazer

A descrição não é um resumo para humanos. É o único material que o agente tem para decidir, num pedido concreto, se esta skill é relevante — e essa decisão é tomada sem ler o corpo.

4.2 Duas descrições para a mesma skill

O limite é de 1024 caracteres, o que é bastante. A esmagadora maioria das descrições más é curta de mais, não longa de mais.

4.3 Escrever para as palavras de quem pede

4.4 Delimitar também importa

Uma descrição boa diz igualmente quando não usar, quando há risco de confusão com outra skill. Duas skills de documentos que não se delimitam competem em todos os pedidos:

# em vez de duas descrições que dizem "trabalha com documentos"
description: Cria apresentações PPTX do zero a partir de um guião ou estrutura.
  Use para criar slides. Não use para editar um PPTX já existente —
  para isso, use a skill pptx-editor.

4.5 Testar se dispara

5.1 As cinco, e o que cada uma é

5.2 A distinção que mais interessa: skill contra MCP

E as duas combinam-se com frequência, que é onde a distinção se torna útil em vez de académica: um servidor MCP dá acesso ao sistema de bilhetes; uma skill diz como é que nesta equipa se escreve um bilhete — que campos são obrigatórios, como se classifica a gravidade, o que nunca vai no título. O MCP sem a skill produz bilhetes válidos e fora das convenções; a skill sem o MCP produz um texto perfeito que ninguém consegue submeter.

Para o outro lado da fronteira — construir e operar servidores MCP — veja MCP. Este volume não supõe que já a leu.

5.3 A árvore de decisão

5.4 Quando não fazer uma skill

• Usou uma vez e não vai repetir. Um prompt chega e não deixa manutenção.
• É conhecimento geral. «Escreve testes» não acrescenta nada ao que o modelo já sabe. Uma skill vale pela especificidade.
• Muda todas as semanas. Uma skill desactualizada é pior do que nenhuma: dá instruções erradas com ar de autoridade.
• É um dado, não um procedimento. Se é uma lista de valores que muda, pertence a um sistema consultável por MCP, não a um ficheiro estático.
• É uma preferência pessoal única. Pertence à configuração do seu ambiente, não a uma skill que se partilha.

6.1 scripts/ — o que o modelo faz mal

• Autocontidos, ou com dependências declaradas. Um script que falha por falta de um pacote não instalado é um beco sem saída para o agente.
• Mensagens de erro úteis. O agente lê o erro e tenta corrigir — se o erro for Traceback puro, não tem por onde pegar.
• Casos-limite tratados. Ficheiro vazio, entrada em falta, formato inesperado.
• Declare o ambiente no campo compatibility quando exigir algo fora do comum: compatibility: Requires Python 3.14+ and uv.

6.2 references/ — o que se lê às vezes

Material consultado a pedido: normas, esquemas de dados, tabelas de conversão, regras por domínio. A convenção é ficheiros focados e pequenos, porque o agente carrega o ficheiro inteiro quando lá vai — um REFERENCE.md de 3000 linhas anula a vantagem do nível 3.

references/
├── REFERENCE.md      # referência técnica detalhada
├── FORMS.md          # modelos e formatos estruturados
└── fiscal.md         # regras de um domínio específico

E no corpo do SKILL.md, a indicação de quando ir lá — que é a parte que costuma faltar:

Para faturação intracomunitária, leia `references/fiscal.md` antes de
gerar qualquer valor. Para os restantes casos, as regras acima chegam.

6.3 assets/ — o que se usa sem ler

Modelos de documento, imagens, tipos de letra, ficheiros de configuração, tabelas de dados. A diferença face a references/ é útil: referências são para o agente ler; recursos são para o agente usar. Um modelo de apresentação não precisa de entrar em contexto — precisa de ser copiado e preenchido.

6.4 A skill que só tem Markdown, e é excelente

7.1 Os sete passos

7.2 O que escrever no corpo

7.3 Escrever proibições em vez de conselhos

7.4 O atalho: uma skill que escreve skills

A Anthropic publica uma skill chamada skill-creator cujo trabalho é conduzir a criação de outras: faz as perguntas certas, monta a estrutura de pastas e valida o resultado. Para a primeira skill, é um bom andaime — e vale a pena escrever a segunda à mão, para perceber o que ela estava a fazer por si. Ficha completa no capítulo 12.

7.5 Onde a guardar

Cada ferramenta tem o seu sítio, e o volume II trata disso em detalhe. A decisão que interessa aqui é outra e é de organização:

• Pessoal — só sua, na sua máquina. Bom para preferências e para experimentar.
• Do projeto — versionada no repositório, junto ao código. É a que rende mais: toda a gente que clona o projeto recebe as convenções, e as alterações passam por revisão como qualquer outro ficheiro.
• Da organização — partilhada entre projetos. Exige alguém responsável pela manutenção, senão apodrece (cap. 11).

8.1 Os dois eixos

8.2 O conjunto de casos

8.3 Os sinais de que a skill está errada

• Dispara em tudo. Descrição larga de mais; delimite (cap. 4.4).
• Nunca dispara. Vocabulário errado, ou a competir com outra skill mais específica.
• Dispara e o agente ignora metade. O corpo é longo de mais, ou tem instruções contraditórias — reduza e separe por níveis.
• O resultado varia muito entre execuções. Há ambiguidade: alguma instrução admite duas leituras.
• Funciona numa ferramenta e não noutra. Provavelmente depende de uma capacidade que a segunda não tem (volume II).

8.4 Manter

10.1 Os oito

10.2 O primeiro é o pior, e é o mais fácil de evitar

10.3 O quarto é o mais comum, e ninguém gosta de o admitir

Uma skill que diz «escreva código limpo», «considere os casos-limite» ou «seja rigoroso» não acrescenta nada — o modelo já tentava fazer isso. A skill vale exactamente o que tem de específico da sua casa: o nome do sistema interno, a ordem dos passos que só aqui se faz assim, o caso-limite que vos mordeu em março.

10.4 O sexto é o mais difícil de diagnosticar

Instruções contraditórias não produzem erro: produzem variabilidade. A mesma tarefa dá resultados diferentes em execuções idênticas, porque o modelo resolve o conflito de maneira diferente de cada vez.

Exemplo típico, e passa despercebido durante meses:

- Seja conciso: no máximo três parágrafos.
...trinta linhas depois...
- Documente todos os casos-limite encontrados, um por um.

A correção não é escolher uma: é escrever qual manda quando colidem — «se houver mais de três casos-limite, liste-os e ignore o limite de parágrafos».

10.5 Depurar por ordem

11.1 O que uma skill pode fazer

11.2 As seis verificações antes de instalar

11.3 A instrução escondida

11.4 O que a torna aceitável

11.5 Numa organização

• Skills de terceiros passam por revisão, como qualquer dependência. Um pull request a acrescentar uma skill é um pull request a acrescentar código.
• Fixe a versão. Copie a skill para o seu repositório em vez de a puxar de uma fonte que pode mudar sem aviso.
• Reveja quando actualizar. O diff de uma skill é legível — é Markdown.
• Mantenha um inventário do que está instalado e porquê, com um dono por cada uma. É o mesmo princípio de Governança de IA, cap. 6.

12.1 As sete regras

12.2 Catálogo fundamental

12.3 O que vem a seguir

12.4 Leituras a par

• MCP — o outro lado da fronteira do capítulo 5.2.
• Agentes de IA e Engenharia de LLM — o que corre por baixo.
• LLMOps & Avaliação — o capítulo 8, a sério e em escala.
• Governança de IA — o inventário do capítulo 11.5.
• UX Writing e Microcópia — escrever para as palavras de quem lê, que aqui decide se a skill dispara.