Como escrever e testar padrões para SKILL.md: guia de engenharia completo

1. Arquitetura e seções obrigatórias do arquivo SKILL.md

O arquivo SKILL.md é uma ferramenta de engenharia que transforma um modelo de linguagem universal em um engenheiro especializado, preparado para executar um tipo específico e regulamentado de tarefa. Ele não duplica os invariantes globais do projeto, mas adiciona a eles conhecimento processual estreito e altamente específico.

Antes de criar uma habilidade para seu próprio repositório, estude obrigatoriamente o arquivo de configuração geral das regras do projeto (AGENTS.md ou CLAUDE.md). Esses documentos sistêmicos são a fonte absoluta da verdade para regras críticas de segurança e comandos de build. A tarefa da Skill é ensinar ao agente a estrutura e a sequência dos passos, referenciando as regras sistêmicas, em vez de copiá-las.

Análise detalhada das seções obrigatórias

1. Description no Frontmatter: É o único bloco de texto que o agente lê antes de decidir carregar a habilidade. Deve ser formulado como uma condição preditiva de ativação («Use quando...»), e não como um título abstrato do tópico.
2. When to trigger (Quando ativar): Uma lista expandida de solicitações diretas, erros nos logs ou operações no git que exigem que a habilidade seja acionada.
3. Procedure (Procedimento Regulamentado): Um algoritmo numerado de ações com nomes exatos de comandos locais e caminhos validados para arquivos.
4. Pitfalls (Armadilhas): Um catálogo de falhas registradas no passado. Cada entrada segue a fórmula: Ação incorreta específica → Falha técnica exata → Receita de correção.

2. Estrutura de localização: sincronização entre Codex e Claude Code

Nos fluxos de trabalho modernos, os desenvolvedores frequentemente utilizam simultaneamente vários clientes (por exemplo, OpenAI Codex no terminal ou IDE e Claude Code). Ambos os runtimes suportam a especificação aberta de habilidades, mas esperam encontrá-las em diferentes diretórios do projeto.

Caminhos de localização dos arquivos de habilidade para os runtimes Codex e Claude Code ЗбільшитиCaminhos de localização dos arquivos de habilidade para os runtimes Codex e Claude Code

Matriz de caminhos para os runtimes

3. Critérios de prontidão e validação de skills em estágio inicial

Antes de transferir uma habilidade para o repositório da equipe, avalie-a usando uma escala padronizada de qualidade de engenharia:

• Falsificabilidade do gatilho: Você consegue citar pelo menos 2 solicitações adjacentes na mesma área temática nas quais a habilidade NÃO deve ser acionada.
• Auditoria de comandos: Cada comando executável no procedimento existe na seção Local Commands do arquivo sistêmico AGENTS.md.
• Armadilhas factuais: Cada item na seção Pitfalls descreve um incidente real da prática, e não uma advertência genérica como «tenha cuidado».
• Compactação de contexto: A leitura do texto da habilidade leva no máximo 2–3 minutos (até 500 linhas).
• Zero duplicação: Nenhum parágrafo copia regras gerais do AGENTS.md.

4. Padrões de composição: roteadores, referências e cadeias

Fluxos de trabalho reais raramente estão isolados em um único arquivo. Tentar descrever tudo em um único SKILL.md monolítico leva ao inchaço do contexto e à queda da atenção do modelo. Utilize três padrões arquiteturais comprovados:

Padrão 1: Entry Router (Skill-Roteador)

Uma habilidade geral atua como um mapa de roteamento. Ela analisa a intenção do usuário e delega a tarefa a sub-habilidades especializadas:

Padrão 2: Arquivos de Referência

O arquivo principal SKILL.md contém apenas o algoritmo de alto nível, enquanto detalhes complexos, tabelas e gramáticas são movidos para o diretório references/:

Padrão 3: Skill Chain (Cadeia de Skills)

As habilidades referenciam umas às outras como a próxima etapa lógica através do campo relatedPaths ou de uma diretiva textual:

5. Estratégias de refatoração: quando dividir e quando unir skills

A escolha entre dividir ou consolidar habilidades determina a robustez do seu sistema de automação.

6. Contrato de versionamento e pipeline de build para skills flagships

Em bases de código complexas, as habilidades são divididas em três níveis tecnológicos quanto à forma de distribuição e build:

Matriz de build e localização de diferentes tipos de habilidades no sistema ЗбільшитиMatriz de build e localização de diferentes tipos de habilidades no sistema

7. Metodologia de teste: cinco verificações obrigatórias de qualidade

Escrever instruções é apenas o começo. Para que a habilidade funcione de forma confiável em produção, ela deve passar sequencialmente por 5 etapas de teste:

Detalhes do protocolo de teste

1. Trigger Probe (Verificação do Gatilho): Formule 3 solicitações que devem ativar a habilidade e 2 que devem ser rejeitadas. Verifique se a descrição no frontmatter delimita claramente esses casos.
2. Procedure Walk-Through (Execução Real): Percorra cada passo manualmente em um stand-in ativo. Se faltarem dados de entrada para executar um passo, a habilidade omitiu uma condição importante.
3. Pitfall Audit (Auditoria de Falhas): Certifique-se de que cada armadilha descrita ocorreu realmente na prática e que a solução proposta é funcional.
4. Scope Test (Teste de Escopo): Defina o propósito da skill em uma única frase simples. Se a frase exigir a conjunção «e também», a habilidade deve ser dividida em duas partes.
5. Staleness Check (Controle de Obsolescência): Compare cada comando CLI com a configuração atual do repositório e as versões atuais das dependências.

8. Anatomia dos antipadrões: como distinguir uma skill funcional de um rascunho

Comparar erros típicos permite realizar rapidamente uma autoauditoria antes de salvar a habilidade.

9. Prevenção de armadilhas: recusa da duplicação do AGENTS.md

A armadilha mais traiçoeira no desenvolvimento de habilidades é a duplicação dos invariantes globais do projeto (por exemplo, regras contra travessões longos, requisitos de cantos arredondados no CSS ou proibição de push direto na main).

Indexação segura de alterações no Git

Durante a execução de procedimentos de commit dentro das habilidades, sempre aplique uma verificação de existência do caminho antes de adicionar ao staging:

10. Checklist final de prontidão para produção

Antes de fixar a habilidade criada no Git, verifique o cumprimento de cada item:

• A habilidade está sincronizada em ambos os diretórios: .agents/skills/<name>/SKILL.md e .claude/skills/<name>/SKILL.md.
• O campo description começa com as palavras «Use quando...» e define limites claros de ativação.
• Todas as 5 etapas do protocolo de teste (Trigger, Procedure, Pitfall, Scope, Staleness) foram aprovadas com sucesso.
• O texto não contém frases marcadoras de incerteza («conforme necessário», «de maneira adequada»).
• Todos os comandos de console foram testados no terminal ativo do projeto.
• Os invariantes globais são formatados como referências ao AGENTS.md, sem cópia direta do texto.