Construa uma skill com um trabalho claro
Organize arquivos, escreva metadados e teste quando a skill deve entrar em ação.
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: responsabilidade ampla.
- Processo: sequência de trabalho.
- Tarefa: entrega delimitada.
- Composição: uma saída alimenta outra tarefa.
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: identificador da skill.
- description: quando usar e fronteiras.
- Markdown: instruções executáveis em linguagem natural.
- Recursos opcionais: só quando fazem falta.
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
- Projeto: procedimento compartilhado com o repositório.
- Usuário: reutilização pessoal.
- Caminho: localização concreta a inspecionar.
- Duplicação: risco de versões divergentes.
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
- Positivo: caso que pertence ao escopo.
- Negativo: tarefa parecida, mas diferente.
- Ambíguo: falta informação para decidir.
- Explícito: ajuda a diagnosticar descoberta.
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
- SKILL.md: procedimento e roteamento.
- references/: detalhes consultados sob condição.
- scripts/: operações verificáveis.
- assets/: modelos e arquivos usados na saída.
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
- Descoberta: a skill aparece?
- Roteamento: ela é escolhida?
- Execução: os passos são seguidos?
- Aceite: a saída atende ao contrato?