🎯 Purpose (Proposito)
A primeira secao de toda skill define o que ela faz e por que existe. Sem um proposito claro, o Claude interpreta as instrucoes de forma ambigua e o resultado varia a cada execucao.
🎯 Conceito Principal
O Purpose deve responder tres perguntas em no maximo 3 linhas:
- •O QUE: Qual tarefa esta skill executa? (ex: "Faz code review de seguranca")
- •POR QUE: Qual problema ela resolve? (ex: "Previne vulnerabilidades antes do merge")
- •PARA QUEM: Quem vai usar? (ex: "Devs antes de abrir PR")
Exemplo no .md:
# Purpose
Realizar code review focado em seguranca para prevenir vulnerabilidades
antes do merge. Destinado a desenvolvedores que querem validar PRs
sem depender exclusivamente de revisores humanos.💡 Dica Pratica
Um Purpose vago como "ajudar com codigo" vai produzir resultados genericos. Um Purpose especifico como "identificar SQL injection, XSS e auth bypass em codigo Python/FastAPI" produz resultados precisos e acionáveis. Quanto mais especifico, melhor.
📥 Inputs (Entradas)
A secao de Inputs define o que a skill precisa receber para funcionar. Pode ser um arquivo, um diretorio, um URL, texto livre ou parametros especificos passados via $ARGUMENTS.
🎯 Conceito Principal
# Inputs
- **Target**: $ARGUMENTS (arquivo ou diretorio para revisar)
- **Scope**: Se nenhum argumento, usar arquivos modificados no git diff
- **Language**: Auto-detectar a partir da extensao do arquivo
- **Severity**: Default "all" - pode filtrar com "critical-only"💡 Dica Pratica
Sempre defina um fallback para quando $ARGUMENTS estiver vazio. "Se nenhum arquivo especificado, analisar todos os arquivos modificados no ultimo commit" e muito melhor que deixar o Claude adivinhar o que voce quer.
📋 Steps (Passos)
Os Steps sao o nucleo da skill: a sequencia exata de acoes que o Claude deve executar. Passos numerados, claros e em ordem logica. Cada passo deve ser atomico - uma unica acao bem definida.
🎯 Conceito Principal
# Steps
1. Ler o arquivo/diretorio alvo e identificar a linguagem
2. Mapear todos os endpoints, funcoes publicas e pontos de entrada
3. Para cada ponto de entrada, verificar:
- Input validation (sanitizacao, tipos, limites)
- Authentication/Authorization (quem pode acessar)
- Data exposure (dados sensiveis no response)
4. Classificar cada finding por severidade (Critical/High/Medium/Low)
5. Gerar sugestao de fix para cada finding Critical e High
6. Compilar relatorio no formato de saida definido💡 Dica Pratica
A regra dos 5-8 passos: menos que 5 e provavelmente vago demais, mais que 8 e complexo demais para uma unica skill. Se precisa de mais passos, considere dividir em duas skills que se complementam.
✅ Quality Checks (Verificacoes)
Quality Checks sao criterios de validacao que o Claude deve verificar antes de entregar o resultado. E a diferenca entre uma skill que "funciona as vezes" e uma que entrega consistentemente.
🎯 Conceito Principal
# Quality Checks
- [ ] Todos os arquivos do target foram analisados
- [ ] Cada finding tem severidade, descricao e localizacao
- [ ] Findings Critical/High tem sugestao de fix
- [ ] Nenhum falso positivo obvio (ex: test files flagged)
- [ ] Relatorio segue o formato de Output definido
- [ ] Se zero findings, confirmar com "No issues found"💡 Dica Pratica
Quality Checks sao sua rede de seguranca. O Claude realmente verifica esses criterios antes de finalizar. Se voce nao incluir checks, ele vai entregar o primeiro resultado que parecer razoavel, sem validar completude ou precisao.
📤 Output (Saida)
A secao de Output define exatamente como o resultado deve ser formatado. Sem isso, cada execucao produz um formato diferente e voce perde a padronizacao que torna skills uteis.
🎯 Conceito Principal
# Output
Formato: Markdown estruturado
## Security Review: [filename]
**Score**: X/10
**Findings**: N issues (C critical, H high, M medium, L low)
### Critical Issues
| # | Location | Issue | Suggested Fix |
|---|----------|-------|---------------|
| 1 | line:col | desc | fix code |
### Summary
[1-2 frases com avaliacao geral e proximos passos]💡 Dica Pratica
Inclua um exemplo concreto do output esperado na skill. O Claude segue exemplos muito melhor que descricoes abstratas. Mostre como uma tabela deve ficar, como o score deve ser calculado, como o summary deve ser escrito.
✍️ Escrevendo Instrucoes Efetivas
A qualidade de uma skill depende 100% da qualidade das instrucoes. Aqui estao os principios que separam skills mediocres de skills que produzem resultados profissionais.
🎯 Conceito Principal
- •Seja imperativo: "Analise" em vez de "Voce poderia analisar". Commands diretos produzem resultados melhores.
- •Seja especifico: "Verifique SQL injection em queries raw" em vez de "verifique seguranca".
- •Use negativos: "NAO inclua arquivos de teste" e mais claro que "foque em arquivos de producao".
- •Inclua exemplos: Um exemplo concreto vale mais que 10 linhas de explicacao.
- •Defina limites: "Maximo 5 findings por categoria" evita outputs gigantes.
💡 Dica Pratica
Teste sua skill 3 vezes com inputs diferentes antes de considerar "pronta". Na primeira execucao voce descobre ambiguidades, na segunda ajusta edge cases, na terceira confirma consistencia. Skill que funciona so no caso ideal nao e skill, e rascunho.