🧩 O que é uma skill e por que ela muda o resultado
Uma skill é uma pasta com um arquivo de instruções na raiz. O cabeçalho traz nome e uma descrição que diz quando usar. O agente lê só o cabeçalho na maior parte do tempo; quando a tarefa bate com a descrição, carrega o corpo. É por isso que dez skills instaladas não pesam no contexto de uma tarefa que não usa nenhuma.
Copie e rode
Esqueleto mínimo de uma skill (o cabeçalho é o que decide se ela é usada)
---
name: <nome-em-kebab-case>
description: >-
<O que faz, em uma frase.> Use quando <gatilho concreto: o tipo de pedido que
deve acionar isso>. Não cobre <o que fica de fora>.
---
# <Nome>
## Quando usar
<Uma lista curta de situações reais.>
## Procedimento
1. <passo com comando exato>
2. <passo com critério de aceite>
## Erros comuns
- <erro> → <correção mínima>💡 A descrição é a interface
Skill boa com descrição vaga nunca é carregada. Escreva a descrição pensando no pedido que o usuário vai digitar, não no que a skill faz por dentro.
🎬 Skill de ferramenta: vídeo com Remotion em um prompt
Remotion renderiza vídeo a partir de componentes React: você descreve cenas em código, ele exporta MP4. Isso o torna ideal para um agente, que escreve código melhor do que arrasta linha do tempo. Com a skill instalada, o pedido é uma frase; sem ela, o agente reinventa a estrutura do projeto a cada vez e erra o comando de render.
Copie e rode
Criar um projeto Remotion e renderizar um promocional de 30 s a partir do README
Use a skill de Remotion.
Resultado: um vídeo promocional de 30 segundos sobre <PRODUTO/PROJETO>, renderizado em MP4 (1920x1080, 30 fps).
Conteúdo: leia o README desta pasta e extraia os 3 benefícios principais. Uma cena de abertura com o nome, três cenas de benefício, uma cena final com a chamada "<CTA>".
Estilo: <PALETA/TOM, ex.: fundo escuro, tipografia grande, transições curtas>. Trilha: use uma faixa livre de direitos que já exista no projeto, ou deixe sem áudio e me avise.
Onde: ./video/
Prova: caminho do MP4, duração real (`ffprobe`) e um frame de cada cena em ./video/frames/.
Não faça: não baixe áudio de fonte com direitos autorais, não instale nada fora do projeto ./video/.Copie e rode
Comandos que você roda para conferir o resultado sem abrir editor
# duração, resolução, codec
ffprobe -v error -show_entries format=duration -show_entries stream=width,height,codec_name \
-of default=noprint_wrappers=1 video/out.mp4
# extrair um frame por cena (a cada 6 s) para revisão rápida
mkdir -p video/frames && ffmpeg -i video/out.mp4 -vf fps=1/6 video/frames/f%02d.png⚠️ Trilha sonora tem dono
Peça explicitamente faixa livre de direitos ou nenhuma. Um agente que "acha uma música" pode trazer material licenciado para dentro do seu projeto, e o problema aparece na publicação, não no render.
🎨 Skill de gosto: a biblioteca de referência visual
Um redesign pedido sem referência sai genérico: fundo escuro, muito espaço vazio, pouca informação. A correção não é um prompt melhor, é uma biblioteca: páginas que você admira, com anotação do porquê, e regras que podem ser conferidas. O agente deixa de adivinhar o seu gosto e passa a aplicar um documento.
Copie e rode
Guia de design mínimo que o agente consegue seguir e você consegue conferir
---
name: guia-visual-<projeto>
description: >-
Regras visuais de <PROJETO>. Use sempre que a tarefa mudar layout, cor,
tipografia ou componentes de interface deste projeto.
---
# Guia visual
## Referências (o que copiar de cada uma)
- <URL_1> — hierarquia tipográfica: título 3x o corpo, subtítulo em peso médio.
- <URL_2> — densidade: cada tela mostra dados, não só espaço em branco.
- <URL_3> — cor: um acento só, usado no máximo em 3 elementos por tela.
## Regras conferíveis
- Escala de espaçamento: 4 / 8 / 16 / 24 / 40 px. Nada fora dela.
- Contraste do texto principal ≥ 4.5:1; títulos ≥ 3:1.
- Máximo 2 famílias tipográficas; corpo ≥ 16 px.
- Nenhuma tela pode perder informação num redesign: item que existia continua visível.
## Contraexemplos (reprovar na hora)
- Fundo mais escuro e menos conteúdo do que o original.
- Cartões vazios com um ícone e três palavras.
- Gradiente roxo-azul genérico sem relação com a marca.✓ Referência que ensina
- ✓URL + o que copiar dela, em uma linha
- ✓Números: espaçamento, contraste, tamanho
- ✓Lista do que reprovar na hora
- ✓Screenshot de uma tela que você aprova
✗ Referência que não ensina
- ✗"Estilo Apple"
- ✗"Moderno e limpo"
- ✗Lista de URLs sem comentário
- ✗"Use bom gosto"
🔍 Skills de terceiros: achar, auditar, usar
Delegar a busca de uma skill funciona bem. Delegar a decisão de confiar nela, não. O procedimento: o agente encontra candidatas, lê o conteúdo, relata o que os scripts fazem, e só depois de você aprovar é que a skill entra em uso, primeiro num projeto descartável.
Copie e rode
Buscar e auditar uma skill pública antes de instalar
Encontre até 3 skills públicas para <TAREFA>. Para cada uma, NÃO instale e me relate:
1. Repositório, autor, data do último commit, número de estrelas.
2. Todo arquivo executável que ela contém (script, binário) e o que cada um faz, linha a linha nos trechos relevantes.
3. Acessa rede? Para quais domínios? Lê variáveis de ambiente, credenciais, ~/.ssh, ~/.aws, tokens?
4. Precisa de permissão elevada ou instalação global?
Termine com uma recomendação e o risco em uma frase. Não baixe nada para fora de ./sandbox-skills/.✓ Sinais de skill segura
- ✓Sem scripts, só instruções em texto
- ✓Scripts que só leem e escrevem na pasta do projeto
- ✓Autor identificável, histórico de commits
- ✓Sem acesso a credenciais ou rede
✗ Sinais de parar
- ✗Script que lê variáveis de ambiente ou ~/.ssh
- ✗Instalação global ou sudo
- ✗Código ofuscado, base64, curl | bash
- ✗Repositório novo, autor anônimo, zero histórico
⚠️ Sandbox antes de confiança
A primeira execução de uma skill de terceiro roda num projeto descartável, com sandbox restrito à pasta e aprovação a pedido (módulo 1.2). Se ela pedir algo fora disso, essa é a resposta sobre confiar.
🗂️ Organizar seu conjunto de skills
Quando várias skills têm descrições parecidas, o carregamento vira loteria. Duas saídas: gatilhos mutuamente exclusivos nas descrições, ou marcar as antigas como invocação direta apenas, sem gatilho automático. A segunda é o que se faz com versões legadas que precisam existir para manter trabalho antigo.
| Situação | Sintoma | Correção |
|---|---|---|
| Duas skills, mesmo assunto | A errada é carregada | Descrições excludentes: "use quando X e NÃO quando Y" |
| Versões (v1..v5) da mesma skill | Conflito permanente | Só a atual tem gatilho; as antigas viram invocação direta |
| Skill nunca carrega | Ignorada em toda tarefa | Descrição genérica; reescreva com o pedido literal do usuário |
| Skill carrega demais | Entra em tarefa que não é dela | Adicione a cláusula "Não cobre..." na descrição |
Higiene do conjunto
Uma skill, um resultado
Se a descrição precisa de "e também", são duas skills.
Gatilho no vocabulário do usuário
Escreva a descrição com as palavras que você digita, não com jargão interno.
Projeto contra global
Regra que vale só num repositório vai no AGENTS.md dele; skill global é para procedimento que atravessa projetos.
Revisão trimestral
Skill não usada em três meses: apague ou marque como invocação direta. Conjunto pequeno escolhe melhor.
🧪 Prática: escrever a sua primeira skill
Roteiro (30 min)
Escolha o procedimento
Algo que você explica ao agente toda semana: como você quer commits, como monta um relatório, como publica um post.
Escreva o corpo primeiro
Passos com comandos exatos e critérios de aceite. Depois escreva a descrição a partir do pedido que você digitaria.
Teste o gatilho
Sessão nova, pedido natural. A skill tem que ser carregada sem você citá-la.
Teste a execução
Rode a tarefa. Onde o agente improvisou, falta um passo no arquivo.
Corrija com o erro real
Cada erro vira uma linha na seção "Erros comuns". A skill melhora por uso, não por planejamento.
Copie e rode
Testar se o gatilho da sua skill funciona (sessão nova, sem citar o nome)
<Escreva aqui o pedido natural, do jeito que você digitaria num dia normal.>
Antes de executar, me diga: quais skills você carregou para esta tarefa e por quê?💡 Escreva a skill depois de fazer na mão
Skill escrita antes da primeira execução vira ficção. Faça a tarefa uma vez conversando, anote onde você corrigiu o agente, e transforme essas correções no corpo da skill.
🧪 Teste rápido do módulo
Três perguntas. Clique numa opção para ver a resposta.
1. Uma skill que você escreveu nunca é carregada. Causa mais provável:
2. Qual é a diferença entre skill e MCP?
3. O redesign "do zero" saiu genérico. A correção estrutural é:
📋 Resumo do módulo
Próximo módulo:
2.2 - MCP e trabalhos longos