Apostila · Skills de IA, volume III de VI

Skills para
construir
produto

Um modelo moderno sabe escrever React, sabe o que é uma migração e sabe testar. Uma skill que lhe ensine isso não acrescenta nada. O que ele não sabe é que a vossa camada de dados não usa ORM, que os componentes vivem em src/ui, que há um teste de acessibilidade obrigatório, e que a rota /legacy não se toca porque três clientes dependem dela. É esse o material de uma skill de produto — e é conhecimento que não está em documentação nenhuma.

12 capítulosdas convenções ao fluxo da equipa
1 demo ao vivodo mesmo pedido com e sem skills
5 skillsem ficha padronizada e datada

↓ role para começar

Capítulo 01 Fundamento

O que muda quando o agente escreve o produto

Skills não tornam o agente melhor a programar. Tornam-no melhor a programar como se programa aqui — e é aí que está a diferença que se sente.

1.1 A distinção que organiza este volume

Competência geral contra convenção local

Um modelo moderno sabe escrever React, sabe o que é uma migração de base de dados e sabe testar. Uma skill que lhe ensine isso não acrescenta nada — é o erro 4 do volume I, cap. 10.

O que ele não sabe é: que a vossa camada de dados não usa ORM, que os componentes vivem em src/ui e não em components, que há um teste de acessibilidade obrigatório antes de qualquer PR, e que a rota /legacy não se toca porque três clientes grandes dependem dela.

É esse o material de uma skill de produto — e é conhecimento que não está em documentação nenhuma, só nas cabeças de quem lá trabalha.

1.2 Os quatro tipos de skill que aparecem num produto

TipoFazExemplo
ConvençãoCodifica como se faz aquiEstrutura de pastas, nomenclatura, formato de commit
ProcedimentoUma sequência com passos e verificaçõesAdicionar uma rota nova, publicar uma versão
CapacidadeTraz scripts que fazem algo deterministaTestar no navegador, validar um esquema, gerar tipos
ReferênciaDocumentação que o modelo não tem actualizadaAPI interna, biblioteca recente, migração de versão

Os dois primeiros são Markdown puro e são os que mais rendem. Os dois últimos justificam scripts/ e references/.

1.3 O tipo «referência» merece uma nota

A skill que resolve o problema do corte de conhecimento

Um modelo tem uma data a partir da qual não sabe nada. Bibliotecas mudam, APIs mudam, e o modelo continua a escrever com confiança a versão que conhecia.

Uma skill de referência resolve isto de forma directa: põe a documentação actual em references/ e instrui o agente a lê-la antes de escrever. A própria Anthropic publica uma assim para a sua API — e o detalhe revelador está na descrição dessa skill: instrui a ler antes de abrir o ficheiro-alvo, e a não saltar o passo porque «parece uma linha só».

É o padrão a copiar: a instrução de quando ler é tão importante como o conteúdo, porque a tendência por omissão é escrever de memória.

1.4 O que este volume é

Delimitação

Volume III de seis. Skills para sites, aplicações, software e MCP. Pressupõe o volume I (o formato) e o volume II (as ferramentas).

Não ensina a programar nem a construir servidores MCP — para isso, MCP, Aceleração de Código com IA, Vibecoding, Arquitetura & System Design e Testing & Automação. Ensina a codificar essas decisões em skills, para não serem repetidas todos os dias.

Exercício 1.1 — O que só se sabe cá dentro

Escreva cinco coisas sobre o seu produto que não estão em documentação nenhuma e que um programador novo levaria semanas a descobrir. Essas cinco são as suas primeiras skills de convenção.

Capítulo 02 Prática

Skills para sites: da página ao sistema

Onde as skills rendem mais em trabalho de web, e a razão pela qual as de design visual são as mais difíceis de acertar.

2.1 O que codificar

2.2 A skill de design visual, e porque é a mais difícil

O problema do «aspecto de modelo por omissão»

Um agente sem direcção produz o mesmo site que toda a gente: o mesmo espaçamento, a mesma sombra suave, o mesmo azul. Não é falta de capacidade — é a média do que existe (O Futuro da Criação Visual, cap. 5.2).

A Anthropic publica uma skill dedicada exactamente a isto — frontend-design — cuja descrição diz que ajuda em «direcção estética, tipografia e escolhas que não se leiam como predefinições de modelo». É a admissão explícita de que o problema existe.

E é a mais difícil de escrever porque o que a resolve é critério, não regra. «Use espaçamento generoso» não instrui nada. «O espaçamento vertical entre secções é 96px; entre elementos de uma secção é 24px; nunca há um terceiro valor» instrui.

2.3 A regra que vale para todas as skills de front-end

Não escrevaEscreva
«Use uma paleta harmoniosa»«Use apenas os tokens de references/TOKENS.md. Nunca introduza um hexadecimal novo»
«Garanta acessibilidade»«Antes de terminar, corra scripts/a11y.sh. Não entregue com falhas de nível A ou AA»
«Componentes bem organizados»«Um componente por ficheiro, em src/ui/<nome>/, com index.ts, styles.css e test.tsx»
«Escreva CSS moderno»«Use apenas grid e flex. Nunca float, nunca posições absolutas fora de ui/overlay»

2.4 Artefactos e protótipos

Há uma categoria de skill própria para construir peças de interface completas de uma vez — páginas de demonstração, protótipos, artefactos com estado e navegação. A skill oficial web-artifacts-builder serve esse caso, e a sua descrição faz uma delimitação que vale a pena copiar: «para artefactos complexos que exijam gestão de estado, rotas ou componentes — não para HTML simples de ficheiro único».

É a delimitação do volume I, cap. 4.4 aplicada bem: sem ela, a skill dispararia em qualquer pedido de página e traria maquinaria a mais para uma tarefa simples.

Exercício 2.1 — A skill de tokens

Escreva uma skill que contenha apenas os tokens de cor, tipografia e espaçamento do seu produto, com a proibição de introduzir valores novos. É a skill de front-end com melhor retorno e a mais fácil de escrever — e apanha a maior parte da deriva visual.

Capítulo 03 Prática

Skills para aplicações e software

Rotas, estado, camadas, migrações. É onde as skills de procedimento — as que têm passos e verificações — valem mais do que as de convenção.

3.1 As skills de procedimento

Uma skill de procedimento é uma sequência com verificação em cada passo. São as mais valiosas em código de aplicação porque codificam a ordem, que é o que se esquece:

# Adicionar uma rota nova

1. Criar o ficheiro em `src/routes/<nome>/`
2. Registar em `src/routes/index.ts` — ordem alfabética
3. Acrescentar o teste de rota em `tests/routes/`
4. Se a rota exigir autenticação, acrescentar ao mapa em `auth/rotas.ts`
   Esquecer este passo é a causa nº 1 de rotas expostas.
5. Correr `scripts/verificar-rotas.sh` — falha se alguma rota
   não estiver no mapa de autenticação nem na lista de públicas
6. Só então fazer commit
O passo 5 é o que transforma a skill

Sem o script, é uma lista que se pode esquecer. Com ele, a omissão do passo 4 é detectada automaticamente — e o agente corrige sozinho porque o erro diz o que falta.

É a regra do volume I, cap. 6.1: o que é determinista vai para script. E é a razão pela qual esta skill funciona e uma lista de boas práticas não.

3.2 As migrações e o que não se desfaz

É o caso onde a skill mais previne dano, porque o erro é irreversível:

3.3 As skills de referência que evitam código desactualizado

O sintoma que toda a gente conhece

O agente escreve código para a versão anterior da biblioteca — com confiança, sem avisar. Não é alucinação: é a versão que ele conhecia.

A correção é uma skill de referência com a instrução de leitura obrigatória antes de escrever:

description: Referência da nossa API interna e da versão da
  biblioteca X que usamos. LEIA references/API.md ANTES de escrever
  qualquer chamada — não presuma pela memória, mesmo que pareça
  uma linha só.

A frase «mesmo que pareça uma linha só» não é retórica: é exactamente nos casos triviais que o passo é saltado, e é aí que o erro passa despercebido.

3.4 Skills por camada, não por tudo

CamadaSkill própriaPorquê separada
InterfaceTokens, componentes, acessibilidadeQuem trabalha aqui não precisa das regras de base de dados
APIContratos, versões, idempotênciaRegras muito específicas (API Design)
DadosMigrações, esquema, consultasÉ onde o erro é irreversível
InfraestruturaPublicação, reversão, observabilidadeSó é preciso ao publicar

Quatro skills focadas batem uma skill grande, por três razões: activam separadamente (menos contexto), delimitam-se melhor (menos falsos positivos) e podem ter donos diferentes.

Exercício 3.1 — O passo esquecido

Identifique o passo que a sua equipa mais esquece ao acrescentar algo novo. Escreva o procedimento com esse passo e um script que falhe quando ele for omitido. É a skill que mais incidentes evita.

Capítulo 04 Núcleo

Skills que verificam o que foi construído

É a categoria com maior retorno de todo este volume, e a razão é a assimetria que atravessa a série: gerar barateou, verificar não.

4.1 A assimetria, aplicada a produto

Onde está o gargalo

Um agente escreve uma página em minutos. Saber se ela funciona — se abre, se os botões respondem, se não partiu outra coisa — continua a custar o mesmo. É o argumento de O Futuro da Engenharia de Software, e aqui tem uma consequência directa:

A skill mais valiosa que pode escrever não é a que ensina a construir. É a que ensina a verificar.

4.2 O que uma skill de verificação traz

A skill oficial webapp-testing é o modelo do género: usa Playwright para interagir com a aplicação local, verificar funcionalidade, depurar comportamento, capturar imagens do ecrã e ler os registos do navegador. A parte que importa não é a ferramenta — é o que se dá ao agente:

CapacidadeO que resolve
Interagir com a aplicação a correrO agente deixa de supor que funciona: clica e vê
Capturar o ecrãVerificação visual — o único modo de apanhar um layout partido
Ler os registos do navegadorErros de JavaScript que não aparecem em teste nenhum
Depurar comportamentoFechar o ciclo: escreve, corre, vê o erro, corrige
Porque isto muda mais do que parece

Sem verificação, o agente trabalha às cegas: escreve, entrega e espera que alguém teste. Com verificação, fecha o ciclo sozinho — e a taxa de sucesso em tarefas de vários passos sobe muito, porque o erro é apanhado no passo em que acontece em vez de se compor com os seguintes (é a aritmética de O Futuro da IA, cap. 4).

4.3 As quatro verificações que valem a pena empacotar

4.4 A instrução que fecha o ciclo

# no SKILL.md de qualquer skill de construção

## Antes de considerar terminado

1. Correr `scripts/verificar.sh` (compila, testes, lint)
2. Abrir a página com a skill `webapp-testing` e confirmar:
   - carrega sem erros na consola
   - o fluxo principal funciona do início ao fim
3. Se qualquer passo falhar, corrigir e repetir — não entregar
   com «deve estar bem».

É a instrução mais barata e mais eficaz deste volume. Três linhas, e transformam um agente que entrega e espera num que entrega verificado.

Exercício 4.1 — Feche o ciclo numa

Pegue numa skill de construção que já tenha e acrescente a secção de 4.4. Corra dez tarefas antes e dez depois, e conte quantas entregas voltaram com problemas. É a comparação com e sem do volume I, cap. 8.

Capítulo 05 Núcleo

Skills para MCP: construir a ponte

Uma skill dá conhecimento e um MCP dá acesso — mas construir um servidor MCP é, ele próprio, uma tarefa que beneficia enormemente de uma skill.

5.1 A relação entre os dois, outra vez e com mais detalhe

O volume I estabeleceu a distinção: conhecimento contra acesso. Em produto digital ela aparece em três configurações que vale a pena separar:

ConfiguraçãoO que éQuando
Só skillInstruções sobre como fazer algo com o que já existeConvenções, procedimentos, referência
Só MCPAcesso a um sistema, sem instruções de usoRaro, e costuma ser um erro: o agente sabe chegar lá e não sabe como se usa aqui
MCP + skillAcesso e as convenções de usoO caso normal, e o que produz bons resultados
Skill que constrói MCPUma skill cujo produto é um servidorQuando a equipa vai criar vários (5.2)
A configuração que quase toda a gente falha

Instalar um servidor MCP e esperar bons resultados. O servidor expõe operações; não diz que campos são obrigatórios na vossa casa, como se classifica a gravidade, ou o que nunca vai no título.

O resultado é tecnicamente válido e culturalmente errado. Cada servidor MCP que instalar merece uma skill pequena ao lado, com as convenções de uso. É a skill mais desprezada e a que mais melhora a qualidade percebida do agente.

5.2 A skill que constrói servidores

A Anthropic publica mcp-builder, descrita como guia para criar servidores MCP de qualidade, com ferramentas bem desenhadas, em Python (FastMCP) ou Node/TypeScript. É um exemplo do tipo «procedimento» aplicado a uma tarefa de arquitectura.

O que a torna útil não é saber a sintaxe — o modelo sabe. É codificar as decisões de desenho que separam um servidor MCP bom de um mau, e essas são convenções, não código:

5.3 A skill de convenções de um MCP que já existe

É o padrão mais rentável desta secção, e escreve-se em vinte linhas:

---
name: bilhetes-convencoes
description: Como se escreve um bilhete nesta equipa — campos obrigatórios,
  classificação de gravidade e formato do título. Use sempre que criar,
  editar ou classificar um bilhete através do servidor de bilhetes.
---

# Convenções de bilhetes

## Obrigatório em todos
- Título: verbo no infinitivo + objecto. Máx. 60 caracteres. Nunca «bug em X».
- Componente: um dos de `references/COMPONENTES.md`. Nunca inventar.
- Gravidade: ver a tabela abaixo — não é uma opinião, é uma tabela.

## Gravidade
| Nível | Critério objectivo |
| P1 | Serviço indisponível, ou perda de dados |
| P2 | Funcionalidade principal partida, sem alternativa |
| P3 | Partido, com alternativa conhecida |
| P4 | Incómodo, melhoria |

## Nunca
- Nunca criar um bilhete sem componente.
- Nunca pôr o nome de um cliente no título (vai para o corpo).

Vinte linhas, e o agente passa de produzir bilhetes válidos a produzir bilhetes que a equipa aceita. É a diferença entre acesso e conhecimento, num exemplo.

Exercício 5.1 — A skill do seu MCP

Para cada servidor MCP que a sua equipa usa, escreva a skill de convenções correspondente. Se não usa nenhum, escreva a de um sistema que use por outra via — as convenções são as mesmas. Ver MCP para o outro lado.

Capítulo 06 Prática

As skills de repositório, que são as que mais rendem

Não são vistosas e são as que mudam mais o dia a dia. Quatro skills que qualquer projeto beneficia de ter.

6.1 As quatro

1 · Orientação do repositório

Onde vive o quê, o que não se toca, e a razão. É a skill de onboarding, e serve tanto ao agente como a quem entra na equipa.

2 · Formato de commit e PR

Com validação por script. É a do exercício do volume I, cap. 9.

3 · Antes de entregar

A lista de verificação: compila, testes, lint, acessibilidade, e o passo específico do vosso projeto que toda a gente esquece.

4 · Zonas proibidas

O código que não se toca, e porquê. É a que evita mais estragos e a que menos gente escreve.

6.2 A quarta merece detalhe

O agente não sabe o que é perigoso

Um agente competente vê código estranho e propõe limpá-lo. É exactamente a alteração que causa o incidente — porque aquela condição estranha protege um cliente grande, e não há nada no código que o diga (Código Legado, cap. 11.2).

# Zonas de cuidado

## `src/legacy/faturacao/` — NÃO REFACTORIZAR
Três clientes empresariais dependem do formato exacto de saída.
Alterações aqui exigem aviso prévio e teste com dados reais.
Se parecer que há código morto, não está morto: ver ficha #4471.

## `src/pagamentos/` — só com testes de caracterização
Nunca alterar sem cobrir primeiro. Nunca repetir uma operação
automaticamente: não é idempotente.

## `config/regioes.json` — gerado
Editar a fonte em `scripts/gerar-regioes.py`, nunca o ficheiro.

Cada bloco destes vem de um incidente real, e é a forma mais barata de garantir que não se repete.

6.3 A skill de orientação, e o efeito secundário que compensa

Uma skill que descreve o repositório — onde estão as coisas, como se corre localmente, o que é gerado e o que é escrito à mão — é simultaneamente documentação para pessoas.

É o argumento do volume II, cap. 10.4, e em produto tem um valor extra: é a única documentação interna cujo desactualizar-se se nota imediatamente, porque o agente começa a errar. Documentação que ninguém lê apodrece em silêncio; esta protesta.

Exercício 6.1 — As zonas proibidas

Reúna a equipa vinte minutos e liste o código que ninguém deve tocar sem avisar, com a razão de cada um. Escreva-o como skill. É provavelmente o melhor retorno por minuto investido de toda esta série.

Capítulo 07 Prática

Compor: cadeias, roteadores e skills que chamam skills

Um produto real precisa de várias skills a trabalhar juntas. Há dois padrões que funcionam e um que parece boa ideia e não é.

7.1 O padrão da cadeia

Uma skill de procedimento que nomeia outras skills nos seus passos:

## Publicar uma versão
1. Verificar com a skill `antes-de-entregar`
2. Correr os testes de navegador com `webapp-testing`
3. Gerar as notas de versão com `notas-de-versao`
4. Só então correr `scripts/publicar.sh`

Funciona bem porque cada skill continua a ser útil sozinha e a cadeia só acrescenta ordem. É o padrão a preferir.

7.2 O padrão do roteador

Uma skill cujo trabalho é escolher outras

Com muitas skills, a activação degrada-se (volume II, cap. 8.4). O padrão do roteador resolve-o: uma skill de entrada, com descrição larga, que lê o pedido e indica quais as skills específicas a carregar.

É a arquitectura que uma colecção grande de skills de jogos usa para cobrir dez motores diferentes sem encher a listagem — em vez de sessenta e oito descrições permanentes em contexto, há uma que encaminha.

Quando compensa: mais de vinte skills no mesmo domínio. Quando não: abaixo disso, acrescenta um salto sem ganho.

7.3 O padrão que parece boa ideia e não é

A skill grande que faz tudo

A tentação é juntar as convenções todas num SKILL.md de mil linhas — «assim está tudo num sítio». Três problemas, todos previsíveis:

Um: carrega inteira sempre que activa, mesmo para uma tarefa pequena. Dois: a descrição fica larga e dispara em tudo. Três: o agente lê e segue metade — instruções demais competem entre si (volume I, cap. 10, falha 5).

Quatro skills de cem linhas batem uma de quatrocentas, sempre, por ativarem separadamente e por se poderem delimitar melhor.

7.4 Como delimitar skills vizinhas

SkillA linha na descrição que evita o conflito
criar-rota«Não use para alterar rotas existentes — para isso, alterar-rota.»
tokens-visuais«Não use para lógica de componente, só para valores de cor, tipo e espaço.»
migracao-bd«Use apenas para alterações de esquema. Para consultas, consultas-bd.»

Custa uma linha por skill e resolve a maior parte dos falsos positivos entre skills do mesmo domínio.

Exercício 7.1 — Parta a maior

Pegue na sua skill mais longa e parta-a em duas ou três, cada uma com a linha de delimitação. Meça a activação antes e depois com os dez pedidos do volume I, cap. 4.5.

Capítulo 08 Crítica

Onde as skills falham em produto

Seis modos de falha específicos deste domínio, para lá dos oito gerais do volume I.

8.1 Os seis

FalhaSintomaCorreção
1 · Convenção desactualizadaO agente segue uma regra que a equipa abandonou há meses — com confiançaDono nomeado e revisão trimestral. Uma skill errada é pior que nenhuma
2 · Conhecimento geral disfarçadoDispara e não muda nadaO teste do corte (volume I, cap. 10.3)
3 · Sem verificaçãoEntrega código que não correA secção «antes de considerar terminado» (cap. 4.4)
4 · Regras contraditórias entre skillsComportamento muda conforme a que disparaUma skill manda em cada assunto; delimitar (cap. 7.4)
5 · Depende de ambienteFunciona local, falha em CI ou na nuvemcompatibility, e scripts autocontidos
6 · Skill que autoriza demaisallowed-tools largo de mais em código de produçãoAprovar o mínimo. Nunca comandos destrutivos

8.2 A primeira é a mais perigosa, e é silenciosa

Uma convenção morta continua a ser aplicada

A equipa decidiu em março passar a usar outra abordagem. Ninguém actualizou a skill. Seis meses depois, o agente continua a escrever código na convenção antiga, e a produzi-lo com toda a confiança — porque uma skill é uma instrução, não uma sugestão.

É pior do que não ter skill nenhuma: sem ela, o agente seguiria o padrão do código à volta e acertaria. Com ela, contradiz activamente o que a equipa faz.

A defesa é de processo, não técnica: quando se muda uma convenção, a alteração à skill vai no mesmo pull request. Se ficar para depois, fica para nunca.

8.3 A sexta, e o limite de confiança

O campo allowed-tools pré-aprova ferramentas. É cómodo e é a única parte de uma skill que reduz as barreiras de segurança. Em código de produção:

8.4 O teste de sanidade trimestral

Quinze minutos, quatro perguntas

Para cada skill do repositório: 1) a convenção que codifica ainda vale? 2) disparou alguma vez neste trimestre? 3) tem dono? 4) os casos de teste passam?

Um «não» em qualquer das quatro é uma acção: actualizar, apagar, atribuir ou corrigir. Apagar é resposta legítima e é a mais subutilizada.

Exercício 8.1 — A auditoria das quatro perguntas

Corra 8.4 nas skills do seu repositório e conte quantas falham pelo menos uma. É frequente descobrir que um terço não disparou nunca — e essas estão a pagar contexto sem devolver nada.

Capítulo 09 Método aplicado · Demo

Uma funcionalidade, do pedido à entrega

Role devagar. Um pedido banal — «acrescenta uma página de definições» — com e sem skills, lado a lado.

O pedido

Código competente, e errado para esta casa

Sem skills, o agente produz algo perfeitamente razoável: um componente bem escrito, cores comuns, uma rota que funciona. Nada disto é um erro de programação — é um erro de convenção, e é invisível para quem não conhece o projeto.

É a distinção do capítulo 1.1: o modelo tem a competência geral e não tem a convenção local. As quatro skills seguintes não o tornam melhor programador. Dizem-lhe onde está.

Skill 1 — orientação

Doze linhas, e a estrutura deixa de ser adivinhada

Onde vivem os componentes, com que ficheiros, e — a parte que quase ninguém escreve — que src/components/ está congelado. Sem essa segunda linha, o agente vê a pasta antiga, conclui que é ali, e acerta no sítio errado (cap. 6.2).

Skill 2 — tokens

A proibição é que funciona, não o conselho

«Use apenas estes valores; nunca introduza um hexadecimal novo» é verificável. «Use uma paleta harmoniosa» não é (cap. 2.3).

E repare no efeito secundário: o espaçamento passa a ter dois valores em vez de sete. É a deriva visual a parar — e é o problema que a apostila de Cor descreve, resolvido do lado da execução.

Skill 3 — procedimento

O passo que se esquece passa a ser um erro que falha

O passo 4 — registar a rota no mapa de autenticação — é o que toda a gente esquece, e o resultado é uma rota exposta. A skill enumera-o; o script do passo 5 torna a omissão detectável (cap. 3.1).

É a diferença entre uma lista que se pode ignorar e um procedimento com controlo. E o agente corrige sozinho, porque o erro diz o que falta.

Skill 4 — verificar

Um erro real, apanhado antes de sair

À primeira execução há um erro na consola que nenhum teste unitário apanharia. O agente vê-o, corrige e volta a correr — o ciclo fecha-se sem intervenção humana (cap. 4).

Sem esta skill, aquele erro chegava a quem revia o pull request, e custava uma ida e volta completa. É a skill com melhor retorno das quatro, e é a que menos gente escreve.

O resultado

Cerca de 120 linhas de Markdown e um script de 12

Escritas uma vez, aplicadas em todas as tarefas seguintes, por toda a equipa, e revistas como código.

E vale a pena reparar no que não mudou: a competência do modelo é exactamente a mesma nas duas colunas. Ele já sabia programar. O que faltava era o contexto — e o contexto cabe em 120 linhas.

É a tese deste volume inteiro, e a razão pela qual as skills de convenção rendem mais que as sofisticadas: o que separa código bom de código aceite não é técnica, é conhecimento local.

Exercício 9.1 — A comparação, no seu projeto

Peça ao agente uma tarefa pequena sem skills e anote tudo o que teria de corrigir na revisão. Cada correcção é uma linha de skill por escrever. Escreva-as e repita o pedido.

Capítulo 10 Operação

Skills no fluxo de trabalho da equipa

Onde encaixam num processo real: revisão, integração contínua, e a decisão de quem escreve o quê.

10.1 Nos três momentos

MomentoSkills que valem
Ao escreverOrientação, tokens, procedimentos, referência
Ao reverUma skill de revisão com os critérios da equipa — o que se rejeita e porquê
Na integração contínuaOs scripts das skills, corridos também aqui
O detalhe que fecha o sistema

Se o script de uma skill corre também na integração contínua, a regra deixa de depender de a skill ter disparado. A skill ensina; a integração contínua obriga.

É a arquitectura certa: um agente que não usou a skill ainda assim não consegue integrar código que a viola — e uma pessoa que escreveu à mão também não.

10.2 A skill de revisão

É a menos óbvia e das mais úteis. Em vez de dizer como escrever, diz o que rejeitar:

## Rejeitar sempre
- Rota nova sem entrada no mapa de autenticação
- Hexadecimal fora dos tokens
- `any` em TypeScript sem comentário a justificar
- Migração que renomeia uma coluna (ver `migracao-bd`)
- Teste que só verifica que não rebenta

## Assinalar, sem bloquear
- Componente com mais de 200 linhas
- Função com mais de 4 parâmetros

## Nunca comentar
- Estilo formatável automaticamente — isso é do formatador, não da revisão

A terceira secção é a que torna a skill boa: dizer o que não comentar evita revisões cheias de ruído que ninguém lê.

10.3 Quem escreve as skills

Exercício 10.1 — A regra dupla

Pegue numa regra que tenha só na skill e acrescente o script correspondente à integração contínua. A regra passa a existir nos dois sítios — ensinada e imposta.

Capítulo 11 Prática

Começar num projeto que já existe

A ordem por que se introduzem skills num produto a meio, para produzir efeito na primeira semana em vez de na terceira.

11.1 A ordem

1 · Zonas proibidas. Vinte minutos com a equipa. Evita o maior estrago e não exige acordo nenhum sobre o futuro.

2 · Orientação do repositório. Onde vive o quê. Serve também a quem entra na equipa.

3 · Antes de entregar. A lista de verificação, com script. É a que fecha o ciclo (cap. 4.4).

4 · Tokens visuais, se houver interface. A que mais reduz correcções de revisão.

5 · Um procedimento — o passo que a equipa mais esquece (cap. 3.1).

6 · Só depois, skills de referência, revisão e as específicas de domínio.

Cinco skills, cerca de 150 linhas, uma tarde. É o mínimo que produz efeito visível — e é deliberadamente pequeno, porque uma pasta com trinta skills escritas de uma vez não é mantida por ninguém.

11.2 O erro de começar pelo ambicioso

A skill que descreve a arquitectura toda

A tentação é começar por documentar o sistema inteiro numa skill. Falha por três razões conhecidas: demora semanas a escrever, fica longa de mais para ser seguida (volume I, cap. 10), e desactualiza-se antes de estar terminada.

As cinco de 11.1 escrevem-se numa tarde e cada uma resolve um problema concreto que já aconteceu. Comece pelo que já doeu.

11.3 Como saber que está a resultar

Exercício 11.1 — As cinco, esta semana

Escreva as cinco de 11.1 para um projeto real, versionadas no repositório, e use-as uma semana. Depois conte os comentários de revisão que deixaram de ser precisos.

Capítulo 12 Ofício · Catálogo

O que fica, e cinco skills para produto

As regras deste domínio, e o catálogo comentado — em ficha padronizada e datada.

12.1 As sete regras

1 · Convenção, não competência

O modelo já sabe programar. O que falta é saber como se programa aqui.

2 · Verificar rende mais que construir

A skill que fecha o ciclo é a de melhor retorno. Gerar barateou; verificar não.

3 · Proibições e scripts

«Nunca X» e um script que falha quando X acontece. Conselhos não se verificam.

4 · Zonas proibidas primeiro

O agente não sabe o que é perigoso. Dizer-lho evita o maior estrago, e custa vinte minutos.

5 · Muitas pequenas, não uma grande

Activam separadamente, delimitam-se melhor, e podem ter donos diferentes.

6 · MCP dá acesso; a skill dá as convenções

Um servidor sem skill produz resultados válidos e culturalmente errados.

7 · A regra vive em dois sítios

Na skill, que ensina; e na integração contínua, que obriga.

E uma oitava

A alteração à skill vai no mesmo pull request da mudança de convenção. Se ficar para depois, fica para nunca.

12.2 Catálogo: cinco skills para produto digital

Como ler estas fichas

Formato fixo em toda a série: nome, autor, o que faz, porque importa, a favor, contra, ligação, licença e data de verificação. É a parte que envelhece mais depressa — verifique a ligação e aplique o volume I, cap. 11 antes de instalar.

E a advertência que se repete: nenhuma destas skills substitui as suas. As de terceiros dão andaime e método; o que faz diferença no seu produto é o conhecimento que só existe cá dentro (cap. 1.1).

mcp-builder Anthropic · repositório oficial

Guia para criar servidores MCP de qualidade, com ferramentas bem desenhadas, em Python (FastMCP) ou Node/TypeScript (SDK do MCP). Cerca de 240 linhas.

Porque importa: Codifica as decisões de desenho que separam um servidor MCP utilizável de um inutilizável — granularidade das ferramentas, descrições que dizem quando usar, erros accionáveis, saída compacta. Nada disso é sintaxe, e é tudo o que decide a qualidade.

A favor
  • Escrita por quem definiu o protocolo
  • Cobre as duas pilhas mais usadas, com o mesmo critério
  • Bom exemplo do tipo «procedimento» aplicado a arquitectura
Contra
  • Source-available, não código aberto — ler a licença antes de uso comercial
  • Assume que já se percebe o que é MCP (ver MCP)
  • Não substitui a skill de convenções do seu MCP concreto (cap. 5.3)

https://github.com/anthropics/skills/tree/main/skills/mcp-builder ·licença Source-available · ver LICENSE.txt·verificado em setembro de 2026

webapp-testing Anthropic · repositório oficial

Ferramentas para interagir com aplicações web locais usando Playwright: verificar funcionalidade, depurar comportamento de interface, capturar imagens do ecrã e ler os registos do navegador. Cerca de 96 linhas.

Porque importa: É a skill com melhor retorno deste volume. Fecha o ciclo do agente — deixa de entregar às cegas e passa a verificar o que construiu, o que faz subir muito a taxa de sucesso em tarefas de vários passos.

A favor
  • Dá ao agente olhos: captura de ecrã e registos do navegador
  • Apanha erros de consola que nenhum teste unitário vê
  • Curta, focada, e fácil de compor com skills de construção (cap. 7.1)
Contra
  • Exige Playwright instalado — declarar em compatibility
  • Não corre no contentor da API (volume II, cap. 5.3)
  • Verifica que funciona, não que está bem desenhado

Combine-a com a instrução de 4.4. A skill dá a capacidade; a instrução obriga a usá-la.

https://github.com/anthropics/skills/tree/main/skills/webapp-testing ·licença Source-available · ver LICENSE.txt·verificado em setembro de 2026

frontend-design Anthropic · repositório oficial

Orientação para desenho visual distinto e intencional ao construir ou remodelar interfaces: direcção estética, tipografia, e escolhas «que não se leiam como predefinições de modelo». Cerca de 71 linhas.

Porque importa: É a admissão explícita, pela própria Anthropic, de que o resultado por omissão de um agente é a média do que existe — e a tentativa de lhe dar critério. Vale tanto pelo problema que nomeia como pelo conteúdo.

A favor
  • Ataca um problema real que quase ninguém nomeia
  • Curta o suficiente para se ler inteira e adaptar
  • Bom ponto de partida para a sua própria skill de direcção visual
Contra
  • É genérica por natureza — critério estético universal não existe
  • Não substitui os seus tokens: use as duas (cap. 2.3)
  • O resultado continua a depender muito do pedido

Leia-a e reescreva-a com as decisões concretas do seu produto. É melhor andaime que produto final.

https://github.com/anthropics/skills/tree/main/skills/frontend-design ·licença Source-available · ver LICENSE.txt·verificado em setembro de 2026

Unity-Technologies/skills Unity Technologies · oficial

Colecção oficial de skills da Unity para agentes de código: 22 skills cobrindo criação de projeto, interface (UGUI, UIToolkit, IMGUI), física, multijogador, compras integradas, localização, otimização de áudio, web e TextMeshPro, Shader Graph, e a linha de comandos da Unity.

Porque importa: É o primeiro exemplo de um fabricante de motor a publicar skills oficiais — o padrão que outras plataformas vão seguir. Para quem trabalha em Unity, é conhecimento de primeira mão em vez de terceira.

A favor
  • Oficial: sai de quem faz o motor
  • 22 skills focadas por tarefa, em vez de uma grande
  • Cobre áreas onde o modelo erra mais — serviços, otimização, ferramentas
Contra
  • Licença não padrão — verificar antes de uso comercial
  • Versionamento face às versões da Unity exige atenção
  • Volume grande: instalar as 22 tem custo de contexto (volume II, cap. 8.4)

Tratado em detalhe no volume VI — Jogos e 3D.

https://github.com/Unity-Technologies/skills ·licença Ver repositório·verificado em setembro de 2026

rampstackco/claude-skills rampstackco · comunidade

Colecção agnóstica de pilha cobrindo o ciclo de vida de um site: marca, desenho, conteúdo, SEO, desenvolvimento e operação. Dezenas de skills, de auditoria de acessibilidade a revisão de código web, estratégia de conteúdo e direcção de arte.

Porque importa: É o exemplo mais completo de uma colecção pensada como sistema e não como skills soltas — e mostra o padrão do capítulo 7: muitas skills focadas, delimitadas entre si, em vez de uma grande.

A favor
  • Licença MIT, permissiva e clara
  • Cobertura ampla do ciclo real de um projeto web
  • Boa fonte para estudar delimitação entre skills vizinhas
Contra
  • Curadoria da comunidade: qualidade desigual entre entradas — aplique o volume I, cap. 11
  • Muitas skills implicam o problema de orçamento de listagem
  • Convenções genéricas: valem como andaime, não como as suas

Não instale a colecção inteira. Escolha as três ou quatro do seu caso e adapte-as.

https://github.com/rampstackco/claude-skills ·licença MIT·verificado em setembro de 2026

12.3 Leituras a par

Exercício 12.1 — O incidente que vira skill

Pegue no último incidente do seu produto e responda: que linha de skill o teria evitado? Escreva-a. Repita para os três incidentes anteriores. É a forma mais fiável de construir uma pasta de skills que vale alguma coisa.