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

> Guia profissional para o desenvolvimento de skills para agentes de IA: as 4 seções obrigatórias do SKILL.md, sincronização entre Codex e Claude Code, padrões de composição, 5 testes essenciais e proteção contra regressões.

## 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.

```mermaid
flowchart TD
    subgraph Structure ["Чотири обов'язкові компоненти якісного SKILL.md"]
        F["1. Description у Frontmatter<br><i>(Формулюється строго як УМОВА, а не тема)</i>"]
        T["2. When to Trigger<br><i>(Точні контекстні критерії та ключові слова)</i>"]
        P["3. Procedure<br><i>(Нумеровані кроки з реальними командами й шляхами)</i>"]
        Pit["4. Pitfalls & Anti-Patterns<br><i>(Дія + Наслідок + Точне виправлення)</i>"]
    end

    F --> T --> P --> Pit
```

### 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*.

> [!NOTE]
> Se a habilidade terminar com um procedimento de release ou deploy, não duplique o pipeline dentro da própria habilidade. Em vez disso, conclua o algoritmo com a instrução: «Execute a skill ship-pipeline».

---

## 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](/api/guides-media/ai_agents/testing-and-writing-skill-md-patterns-guide/images/testing-and-writing-skill-md-patterns-guide-extra-01.webp)

### Matriz de caminhos para os runtimes

| Runtime / Agente | Caminho alvo do arquivo SKILL.md | Particularidades da detecção |
| :--- | :--- | :--- |
| **OpenAI Codex** | `.agents/skills/<name>/SKILL.md` | Lido pelo agente Codex durante a varredura de ferramentas locais |
| **Anthropic Claude Code** | `.claude/skills/<name>/SKILL.md` | Lido pelo Claude Code durante a inicialização do ambiente da sessão |

> [!IMPORTANT]
> **Requisito de sincronização dual:** Se a habilidade for adicionada apenas em `.claude/skills/`, ela será totalmente invisível para os agentes Codex, e vice-versa. Sempre crie e mantenha a habilidade em ambos os diretórios ou configure links simbólicos (symlinks).

---

## 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`.

```mermaid
flowchart LR
    Draft["Чорновий Skill<br><i>(Розмитий опис, копії правил, абстрактні кроки)</i>"] --> Review{"Валідація чернетки"}
    Review -->|Виявлено недоліки| Fix["Виправлення формулювань і команд"]
    Fix --> Review
    Review -->|Всі критерії виконано| Prod["Production-Ready Skill"]
```

---

## 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:

```text
Solicitação: "Otimizar o desempenho das consultas ao banco de dados"
  └── db-router (Entry Router)
        ├── Encaminha para: neon-migrations (se forem necessárias alterações na estrutura)
        └── Encaminha para: drizzle-index-optimizer (se forem necessários índices)
```

### 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/`:

```text
.claude/skills/fleet-coordinator/
├── SKILL.md                   # Pipeline curto de orquestração
└── references/
    ├── agent-roles.md         # Descrição das especializações e matriz de papéis
    └── file-ownership.md      # Regras para prevenção de conflitos de escrita
```

### 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:

```markdown
> Após a validação bem-sucedida do esquema, execute obrigatoriamente a habilidade drizzle-migration-runner.
```

---

## 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.

:::tabs
@tab Dividir a habilidade
- **Condições de disparo distintas:** Os cenários exigem configurações opostas (por exemplo, auditoria de código sem permissão de escrita versus migração de banco de dados com alteração direta do schema).
- **Superfícies de produto diferentes:** A skill tenta regular simultaneamente a landing page (design-code, Tailwind) e o servidor backend (NestJS, SQL).
- **Sobrecarga de contexto:** O volume de texto excede 500 linhas e o agente começa a confundir os passos.
@tab Unir habilidades
- **Vínculo indissociável:** Duas skills minúsculas nunca são chamadas separadamente, e a execução de uma sem a outra carece de sentido prático.
- **Duplicação de código:** A divisão faz com que o mesmo bloco de verificações seja duplicado em dois arquivos.
:::

> [!TIP]
> Em 90% dos casos, a decisão correta é justamente a **divisão**. A tentativa de criar uma «skill universal para todo o backend» inevitavelmente se transforma em um monólito ineficiente com alto nível de alucinações.

---

## 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](/api/guides-media/ai_agents/testing-and-writing-skill-md-patterns-guide/images/testing-and-writing-skill-md-patterns-guide-extra-02.webp)

| Tipo de Habilidade | Onde o código-fonte é editado | Pipeline de Build | Propósito |
| :--- | :--- | :--- | :--- |
| **Skill de Repositório (privada)** | `.agents/skills/<name>/SKILL.md` + `.claude/skills/<name>/SKILL.md` | **Não necessário** (lida diretamente) | Regras internas da equipe para o projeto atual |
| **Flagship Público (multi-arquivo)** | `skills-source/<slug>/` + metadados no script de geração | `node scripts/build-flagship-skills.mjs skills-source/` | Soluções modulares complexas com arquivos de referência para o marketplace |
| **Pública de arquivo único** | `baseSkills` em `lib/library/skills.ts` | **Não necessário** | Habilidades básicas leves para o catálogo da plataforma |

> [!WARNING]
> **Proibição de edição manual de arquivos gerados:** Nunca edite manualmente o arquivo compilado de uma skill flagship. Todas as alterações devem ser feitas exclusivamente na pasta de origem `skills-source/<slug>/`, seguida pela execução do script de compilação.

---

## 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:

```mermaid
flowchart TD
    T1["1. Trigger Probe<br><i>(3 позитивні + 2 негативні запити)</i>"] --> T2["2. Procedure Walk-Through<br><i>(Наскрізний запуск на реальному репозиторії)</i>"]
    T2 --> T3["3. Pitfall Audit<br><i>(Перевірка формули: Дія + Збій + Фікс)</i>"]
    T3 --> T4["4. Scope Test<br><i>(Перевірка єдиної відповідальності одним реченням)</i>"]
    T4 --> T5["5. Staleness Check<br><i>(Звірка команд і шляхів з актуальним репозиторієм)</i>"]
    T5 --> Ready["Схвалено до коміту"]
```

### 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.

| Característica | Rascunho (Draft) | Habilidade pronta para produção (Ready) |
| :--- | :--- | :--- |
| **Formulação do gatilho** | Descreve um tópico amplo: *«Para trabalhar com banco de dados»* | Define uma condição precisa: *«Use ao criar migrações Drizzle»* |
| **Descrição dos passos** | Instruções vagas: *«execute o linter conforme necessário»* | Comandos claros: *«execute npm run lint:fix»* |
| **Descrição dos riscos** | Desejo genérico: *«tenha cuidado com os arquivos»* | Falha concreta: *«git add de um caminho inexistente interromperá o staging»* |
| **Fontes das regras** | Copia o texto do `AGENTS.md` em seu conteúdo | Contém uma referência direta à seção no `AGENTS.md` |
| **Sincronização** | Criada apenas em `.claude/skills/` | Sincronizada simultaneamente em `.agents/` e `.claude/` |

---

## 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).

```text
Por que a duplicação destrói o sistema:
1. O engenheiro copia uma regra do AGENTS.md para o corpo do SKILL.md.
2. Um mês depois, o comitê de arquitetura atualiza a regra no AGENTS.md.
3. Dentro do SKILL.md, permanece uma formulação obsoleta.
4. O agente recebe dois sinais de sistema conflitantes e começa a alucinar.
```

### 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:

```bash
# Небезпечно (якщо файл відсутній, вся команда переривається з помилкою):
git add src/generated/schema.ts src/types/db.ts

# Безпечно (додаються лише реально існуючі файли):
[ -e src/generated/schema.ts ] && git add src/generated/schema.ts
[ -e src/types/db.ts ] && git add src/types/db.ts
```

---

## 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.