← Voltar ao curso
Nível 1 — Fundamentos · Módulo 1.5 — Skills: ensine seu jeito uma vez só

1.5.2 · Sua primeira Skill

5 min de vídeo TODOS

Objetivo: ao final, o consultor escreveu uma skill funcional de ponta a ponta, e sabe onde salvar o arquivo.

O que você precisa levar desta aula

  1. Estrutura: uma pasta com o nome da skill, contendo SKILL.md (esse nome exato).
  2. A descrição precisa dizer o que a skill faz e quando usar, com as palavras que você realmente usa.
  3. Diga qual é o formato da saída, e escreva itens verificáveis.

Onde o arquivo mora

~/.claude/skills/revisao-spec-funcional/SKILL.md

No Windows:

C:\Users\<seu-usuario>\.claude\skills\revisao-spec-funcional\SKILL.md

Essa é a localização pessoal: a skill segue você em todos os projetos. A localização de projeto e a biblioteca do time são a aula 1.5.4.

A skill completa — copie e adapte

---
name: revisao-spec-funcional
description: Revisa uma spec funcional antes do envio ao cliente usando o
  checklist da Wayon. Use ao revisar spec, FS, especificação funcional
  ou documento de desenho.
---

# Revisão de spec funcional — checklist Wayon

Verifique os itens abaixo na spec fornecida. Reporte cada um como **OK**
ou **PENDENTE**, sempre com a evidência (cite a seção). Ao final, liste
apenas os PENDENTES, em ordem de gravidade.

Não reescreva a spec. O objetivo é apontar, não corrigir.

## Completude
1. Toda regra de negócio tem o cenário de exceção correspondente
2. Todo campo novo tem tipo, tamanho e obrigatoriedade definidos
3. Todo erro previsto tem código, mensagem ao usuário e ação de recuperação
4. Há critério de aceite verificável para cada requisito

## Rastreabilidade
5. A spec referencia o gap ou RICEFW de origem
6. Há referência ao documento de desenho que a originou
7. Mudanças em relação à versão anterior estão marcadas

## Consistência
8. A terminologia é a do cliente, não a genérica do produto
9. Não há contradição entre seções
10. Os nomes de objeto seguem a convenção do cliente

## Riscos
11. Premissas não confirmadas estão declaradas explicitamente
12. Dependências de outros RICEFW ou de terceiros estão identificadas

Regras do frontmatter

Campo Regra
name Minúsculas, hífen entre palavras. Sem espaço, sem acento, sem maiúscula
description Uma ou duas frases. Diz o que faz e quando usar. Inclui as palavras que você usa de verdade

Erros que impedem a skill de carregar:

--- name: revisao spec ---              ❌ espaço no name; frontmatter em uma linha
name: Revisão-Spec                      ❌ maiúscula e acento; falta o ---
---
name: revisao-spec
---                                     ❌ sem description: nunca vai disparar

Três regras para o corpo

  1. Diga o formato da saída. "Reporte cada item como OK ou PENDENTE, com a evidência" — sem isso você recebe prosa e garimpa.
  2. Escreva itens verificáveis. "Todo campo novo tem tipo, tamanho e obrigatoriedade" é verificável. "A spec está bem escrita" não é.
  3. Diga o que não fazer, quando importa. "Não reescreva a spec; aponte" evita que ele passe por cima do seu trabalho.

Depois de salvar

Reinicie a sessão do Claude para que ele descubra a skill nova. Para confirmar que carregou, faça um pedido que case com a descrição — a interface indica quando uma skill é acionada.

Quiz — 3 questões — identifique o erro em cada frontmatter

1.--- name: Revisão de Spec description: Revisa specs. ---
  • a)A descrição está curta demais

    Está curta e ruim, sim, mas não é o erro que impede o carregamento.

  • b)O name tem espaços, maiúscula e acento

    Correto. name precisa ser minúsculo, com hífen e sem acento: revisao-spec-funcional. A descrição também precisa melhorar — sem dizer "quando usar", ela dispara mal.

  • c)Falta um campo obrigatório

    name e description estão presentes. O problema é o formato do name.

Ver resposta e por quê
❌a) Está curta e ruim, sim, mas não é o erro que impede o carregamento.
✅b) Correto. name precisa ser minúsculo, com hífen e sem acento: revisao-spec-funcional. A descrição também precisa melhorar — sem dizer "quando usar", ela dispara mal.
❌c) name e description estão presentes. O problema é o formato do name.
2.--- name: revisao-spec-funcional --- # Revisão de spec ...
  • a)Falta o corpo do procedimento

    O corpo está lá.

  • b)Falta a description — sem ela a skill nunca dispara

    Correto. A descrição é o gatilho; sem ela o Claude não tem como reconhecer quando usar a skill.

  • c)O name está errado

    O name está correto: minúsculo, com hífen, sem acento.

Ver resposta e por quê
❌a) O corpo está lá.
✅b) Correto. A descrição é o gatilho; sem ela o Claude não tem como reconhecer quando usar a skill.
❌c) O name está correto: minúsculo, com hífen, sem acento.
3.--- name: revisao-spec-funcional description: Checklist interno. --- ---
  • a)O name está errado

    O name está correto.

  • b)Falta a description

    Ela existe.

  • c)A description não diz quando usar nem contém as palavras que você usa — a skill vai disparar quase nunca

    Correto. "Checklist interno" não casa com "revisa essa FS". A descrição precisa dizer o que faz e quando usar, com as palavras reais: spec, FS, especificação funcional.

Ver resposta e por quê
❌a) O name está correto.
❌b) Ela existe.
✅c) Correto. "Checklist interno" não casa com "revisa essa FS". A descrição precisa dizer o que faz e quando usar, com as palavras reais: spec, FS, especificação funcional.