Quebre uma função em tarefas verificáveis
O que é
Uma função como marketing se divide em processos, e cada processo em entregas menores. Produzir um artigo a partir de um vídeo é uma entrega; administrar marketing inteiro não é. Use a árvore do vídeo como ferramenta para encontrar as folhas que têm começo e fim.
Por que aprender
Quando uma skill faz pesquisa, criação, publicação e análise financeira, uma falha fica difícil de localizar. Separar responsabilidades permite testar cada parte e encadeá-las depois, com entradas e saídas explícitas.
Conceitos-chave
Função: conteúdo
├── Planejar pauta
├── Converter vídeo em artigo
├── Revisar artigo
└── Publicar artigo aprovado
✓ Faça assim
Separe publicação quando ela exige uma decisão diferente.
✗ Evite este erro
Criar uma skill chamada “fazer-tudo” com dezenas de gatilhos.
Pratique antes de revelar
Decomponha “cuidar dos clientes” em três tarefas delimitadas.
Ver resposta comentada
Classificar uma solicitação; rascunhar uma resposta com base na política; preparar um resumo semanal de chamados. Cada uma pode ter um teste diferente.
Conheça o arquivo que guarda o procedimento
O que é
O nome correto é SKILL.md, respeitando a capitalização. Ele começa com metadados YAML entre linhas de três hífens e continua com instruções Markdown. Os campos name e description identificam a skill e sua situação de uso.
Por que aprender
Um erro no cabeçalho pode impedir a descoberta ou prejudicar a seleção. Mantenha o primeiro exemplo mínimo e legível. Campos extras vistos em outras ferramentas não devem ser tratados como obrigatórios no Codex.
Conceitos-chave
---
name: relatorio-semanal
description: Converte CSV de vendas em relatório semanal local. Use ao pedir totais por canal e pendências; não atualiza CRM.
---
# Relatório semanal
1. Validar a entrada.
2. Calcular totais.
3. Gerar relatório e verificar.
Do conceito à ação
- SKILL.md: identificar a condição inicial.
- Metadados YAML: aplicar a decisão descrita.
- Instruções: conferir o efeito no exemplo.
- Recursos opcionais: registrar a evidência de saída.
✓ Faça assim
Comece pelos campos confirmados na documentação oficial.
✗ Evite este erro
Copiar argument-hint de outra ferramenta como requisito do Codex.
Pratique antes de revelar
Qual campo precisa mencionar “CSV de vendas” para ajudar a seleção?
Ver resposta comentada
description. O corpo pode aprofundar o formato, mas o cenário principal precisa estar claro nos metadados de descoberta.
Escolha o escopo da instalação
O que é
Para este laboratório, coloque a pasta da skill em .agents/skills dentro do projeto. Skills de usuário podem ficar em ~/.agents/skills. Escopo de projeto acompanha aquele trabalho; escopo de usuário disponibiliza o procedimento em outros projetos.
Por que aprender
Uma skill específica de um cliente pode causar confusão se for instalada globalmente com um gatilho genérico. Evite cópias independentes com o mesmo nome: com o tempo, você deixa de saber qual versão está sendo executada.
Conceitos-chave
meu-projeto/
.agents/
skills/
relatorio-semanal/
SKILL.md
scripts/
references/
✓ Faça assim
Peça ao Codex o caminho da skill que ele selecionou.
✗ Evite este erro
Assumir que duas skills de mesmo nome são mescladas.
Pratique antes de revelar
Uma skill usa convenções de um único projeto. Onde colocá-la primeiro?
Ver resposta comentada
No escopo do projeto. Só a generalize depois de separar regras específicas e testar os outros contextos. Não é necessário instalá-la globalmente para aprender.
Escreva gatilhos e também não gatilhos
O que é
A descrição deve responder quando usar a skill. Um gatilho explícito é pedir a skill pelo nome; um implícito é descrever uma tarefa compatível. No Codex CLI ou extensão, a documentação apresenta /skills e a menção com $ para seleção explícita.
Por que aprender
Frases amplas como “sempre que falar em relatório” capturam tarefas demais. Teste pedidos que deveriam acionar e pedidos próximos que não deveriam. A ausência de um teste negativo esconde colisões com outras skills.
Conceitos-chave
SIM: “Resuma este CSV de vendas da semana.”
NÃO: “Escreva um relatório de pesquisa sobre energia.”
AMBÍGUO: “Faça meu relatório.” → pedir entrada e objetivo.
EXPLÍCITO: “Use $relatorio-semanal neste arquivo.”
✓ Faça assim
Teste sem citar o nome da skill para avaliar o gatilho implícito.
✗ Evite este erro
Achar que um teste explícito prova a seleção automática.
Pratique antes de revelar
Crie um pedido negativo com a palavra “vendas”.
Ver resposta comentada
“Escreva um anúncio para aumentar as vendas.” Compartilha vocabulário, mas não pede converter CSV em relatório; portanto não pertence ao escopo.
Distribua instruções, referências e scripts
O que é
Deixe no SKILL.md o caminho principal e as condições para consultar material adicional. Uma referência pode guardar a rubrica editorial; um script pode calcular valores. O agente não precisa carregar todos os exemplos longos para descobrir o propósito da skill.
Por que aprender
Essa organização reduz repetição e torna a manutenção mais precisa. A descrição não deve virar um manual inteiro. Ao mesmo tempo, esconder uma regra essencial num arquivo nunca mencionado impede que ela seja aplicada.
Conceitos-chave
No SKILL.md:
“Execute scripts/gerar_relatorio.py para os totais.
Para revisar os comentários, consulte references/rubrica.md.
Se a entrada for inválida, informe a mensagem do validador.”
Do conceito à ação
- Descobrir: identificar a condição inicial.
- Ler o procedimento: aplicar a decisão descrita.
- Consultar o necessário: conferir o efeito no exemplo.
- Executar: registrar a evidência de saída.
✓ Faça assim
Diga quando e para que abrir cada referência.
✗ Evite este erro
Mover o contrato inteiro para um arquivo sem link nem condição.
Pratique antes de revelar
Onde colocar vinte exemplos longos de relatórios?
Ver resposta comentada
Em uma referência dedicada, mantendo no SKILL.md apenas os exemplos mínimos e a instrução de consulta. Dados sensíveis devem ser removidos antes de criar essa biblioteca.
Execute a primeira versão e registre o acionamento
O que é
Abra o projeto no Codex, peça a tarefa com o arquivo de exemplo e confira qual procedimento foi usado. Se a skill não aparecer, verifique caminho, nome, cabeçalho e descrição. A documentação recomenda reiniciar se uma atualização não for detectada.
Por que aprender
Existe diferença entre não descobrir a skill e executá-la mal. Diagnosticar a fase evita reescrever todo o conteúdo por um arquivo no lugar errado. Registre pedido, skill selecionada e artefatos produzidos.
Conceitos-chave
Use $relatorio-semanal com dados/vendas.csv.
Mostre o caminho da skill usada.
Salve a saída em saidas/rodada-01/.
Informe os testes executados e as limitações observadas.
✓ Faça assim
Inspecione os arquivos entregues além da mensagem final.
✗ Evite este erro
Considerar “usei a skill” suficiente para aprovar o resultado.
Pratique antes de revelar
O teste explícito funciona e o implícito não. O que revisar primeiro?
Ver resposta comentada
A descrição e os pedidos de teste. O corpo já demonstrou ser executável; o problema mais provável está na seleção. Verifique também skills concorrentes com escopo parecido.
Confira seu entendimento
Qual descrição delimita melhor a skill?
O que você leva deste módulo
Criar um SKILL.md pequeno, acionável e com testes de gatilho.
- Quebre uma função em tarefas verificáveis.
- Conheça o arquivo que guarda o procedimento.
- Escolha o escopo da instalação.
- Escreva gatilhos e também não gatilhos.
- Distribua instruções, referências e scripts.
- Execute a primeira versão e registre o acionamento.
Próxima ação: guarde o exercício no seu laboratório e registre o que ainda precisa de revisão.