📁 Anatomia: pasta + SKILL.md
Uma skill é fundamentalmente uma pasta — não apenas um arquivo. O nome da pasta é o identificador da skill; o arquivo SKILL.md é o cérebro. Tudo que existe dentro dessa pasta serve à skill.
✓ Estrutura correta
- ✓
~/.claude/skills/minha-skill/SKILL.md - ✓Pasta em kebab-case, SKILL.md na raiz
- ✓Subpastas scripts/ e references/ opcionais
- ✓Cada arquivo com responsabilidade clara
✗ Erros comuns
- ✗SKILL.md solto em ~/.claude/ sem pasta
- ✗Pasta com espaços ou camelCase no nome
- ✗Tudo misturado em um SKILL.md gigante
- ✗Scripts inline no markdown em vez de arquivos
📄 Frontmatter YAML
O frontmatter é o bloco YAML entre os delimitadores --- no topo do SKILL.md. É aqui que você declara a identidade da skill e como ela deve ser ativada.
---
name: formato-curso
description: |-
Template e padrões de design para criar páginas HTML
de cursos no formato INEMA.CLUB.
Use esta skill SEMPRE que o usuário pedir para criar,
editar ou revisar páginas HTML de curso — incluindo
index de trilhas, páginas de módulos, componentes.
SKIP: páginas web genéricas sem contexto de curso INEMA.CLUB.
---
# Formato Curso - INEMA.CLUB
# (corpo do SKILL.md começa aqui)💡 Dica: o campo name = identificador
O name no frontmatter deve ser idêntico ao nome da pasta. Isso cria coerência: a pasta formato-curso/ contém um SKILL.md com name: formato-curso. O agente usa esse nome para referenciá-la em logs e para invocar via /formato-curso.
✓ Frontmatter válido
- ✓Delimitadores
---no início e fim - ✓Indentação com 2 espaços (nunca tabs)
- ✓Campos
nameedescriptionpresentes - ✓Description em linguagem natural clara
✗ Frontmatter inválido
- ✗YAML com tabs em vez de espaços
- ✗Falta de
---de fechamento - ✗Description vazia ou de 1 palavra
- ✗Campos extras não reconhecidos (sem efeito)
📝 Corpo em Markdown
Após o frontmatter, o corpo do SKILL.md é Markdown puro. É aqui que você programa o comportamento real da skill: o que fazer, em que ordem, e o que nunca fazer.
# Nome da Skill
Parágrafo de contexto curto — o que esta skill faz.
## Referências
Sempre leia estes arquivos antes de agir:
1. **`references/MASTER.md`** — Templates completos
2. **`references/CHECKLIST.md`** — Verificação final
## Fluxo de Trabalho
1. Entender o que será criado
2. Ler referências relevantes
3. Criar seguindo os templates
4. Verificar com o checklist
## Hard Rules
- **NUNCA** usar seta ▶ em tópicos (usar número em círculo)
- **SEMPRE** incluir INEMA.CLUB em todas as páginas
- **JAMAIS** simplificar o nav para páginas internasSeções recomendadas no corpo
Contexto / Referências
Lista de arquivos que o agente deve ler antes de agir. Ponteiro para a documentação detalhada em references/.
Fluxo de Trabalho
Passos numerados que o agente executa em ordem. Inclui gates de confirmação antes de ações custosas.
Erros Críticos / Hard Rules
Regras invioláveis em MAIÚSCULAS. O que NUNCA fazer. Protege contra os erros mais caros e irreversíveis.
Tabelas de Referência Rápida
Tabelas de decisão, mapeamentos de cores, listas de componentes. Informação densa em formato escaneável.
💡 Tamanho ideal do SKILL.md
O SKILL.md é lido completamente a cada ativação. 50–150 linhas é o sweet spot: denso o suficiente para programar o comportamento, conciso o suficiente para não desperdiçar tokens. Conteúdo maior vai para references/.
🗂️ Onde ficam as skills
Skills podem existir em dois escopos: global (disponível em todos os projetos) ou local (restrito ao projeto atual). A escolha depende de quão específica é a skill.
🗺️ Mapa de localização
Global (~/.claude/skills/)
Skills utilitárias reutilizáveis em qualquer projeto. Exemplos: formato-curso, n8n-code-python, claude-api.
└── skills/
├── formato-curso/
├── n8n-code-python/
└── ads-skill/
Local (.claude/skills/)
Skills específicas do projeto atual. Não aparecem em outros repositórios. Exemplo: skill com lógica de negócio do cliente.
└── .claude/
└── skills/
└── projeto-especifico/
📊 Regra de precedência
Quando existe uma skill com o mesmo nome em ambos os escopos, a local sobrescreve a global. Isso permite que projetos específicos customizem o comportamento de uma skill global sem alterar a original.
✓ Use global quando
- ✓A skill é útil em múltiplos projetos
- ✓Não contém dados sensíveis de clientes
- ✓É um utilitário genérico (formatter, analyzer)
✓ Use local quando
- ✓Contém lógica de negócio específica
- ✓Referencia APIs privadas do projeto
- ✓Deve ser versionada junto ao código
🔍 Como o agente descobre e ativa
O processo de descoberta e ativação acontece em duas fases: descoberta passiva (ao iniciar) e ativação ativa (quando a mensagem é relevante).
💡 Lazy loading: economia de tokens
O agente NÃO lê o corpo completo de todas as skills em cada sessão. Apenas os metadados (name + description) são injetados. O corpo completo é carregado somente quando a skill é ativada. Isso mantém o contexto leve mesmo com dezenas de skills instaladas.
⚖️ Skill vs prompt vs comando
Três ferramentas, três propósitos. Escolher a errada não quebra nada — mas escolher a certa economiza horas.
Tabela comparativa
| Critério | Skill | Prompt | Comando |
|---|---|---|---|
| Persistência | Permanente (arquivo) | Stateless | Salvo em config |
| Complexidade | Multi-etapa, scripts | Instrução pontual | Atalho de prompt |
| Regras rígidas | Sim (hard rules) | Não | Não |
| Arquivos auxiliares | Sim (scripts/, refs/) | Não | Não |
| Melhor para | Workflows complexos | Tarefas pontuais | Atalhos rápidos |
💡 Regra de ouro
Se você vai repetir o mesmo conjunto de passos mais de 3 vezes, crie uma skill. Se é pontual e específico, use um prompt inline. Se é um atalho para um prompt que você digita frequentemente, crie um comando slash.
🧩 Resumo do Módulo
Próximo Módulo:
3.2 — Description e triggers: como escrever o campo description que faz a skill disparar na hora certa