Como criar uma skill de spec-driven development para reusar em todos os projetos

Aposto que você já recolou o mesmo prompt de especificação em três projetos diferentes esse mês

Aí muda uma palavra aqui, esquece uma seção ali, e o agente entrega outra coisa completamente diferente do que entregou no projeto passado

Spec-driven development não é um prompt, é um PROCESSO: dizer o que o app faz, como vai ser construído e em que ordem, antes de mandar a IA escrever a primeira linha. E processo que se repete igual em todo projeto é exatamente o tipo de coisa que merece virar instrução reaproveitável

Neste post você monta uma skill de spec-driven development do zero: a pasta, o SKILL.md, a description que faz o Claude achar a skill sozinho, o template de spec com critérios de aceite, e como reusar isso em todos os projetos (e distribuir pro time) 🙂

O que você precisa antes de criar a skill

Pouca coisa, se liga:

• o Claude Code CLI instalado e rodando na sua máquina
• um processo de especificação que você já usa, mesmo que informal e só na sua cabeça: ele vai virar texto
• a decisão de onde a skill mora

Esse último ponto merece parada. No Claude Code as skills são baseadas em sistema de arquivos e não exigem upload por API: elas ficam em ~/.claude/skills/ (pessoal) ou em .claude/skills/ (do projeto)

A diferença é prática: a skill pessoal fica disponível em TODOS os seus projetos, que é justamente o que a gente quer aqui. A de projeto vive dentro daquele repositório e some quando você abre outra pasta

Uma Agent Skill, no fim, é só isso: uma pasta contendo um arquivo SKILL.md com frontmatter YAML (entre os marcadores ---) e o conteúdo em markdown com as instruções que o Claude segue quando a skill roda

Um aviso pra não te pegar de surpresa lá na frente: o campo allowed-tools no SKILL.md só é suportado ao usar o Claude Code CLI diretamente, ele NÃO se aplica quando as skills são usadas via SDK. Se o seu plano é rodar isso dentro de uma automação por SDK, conte com essa diferença desde já

Se skill ainda é assunto novo pra você, dá uma olhada no post sobre criar e usar skills no Claude Code antes de seguir

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

Como criar a skill de spec-driven development passo a passo

Bora ver na prática?

1. Crie a pasta da skill. O comando vem do nome do diretório ou do arquivo, então use minúsculas e hífens no nome da pasta, sem espaço e sem acento

mkdir -p ~/.claude/skills/spec-driven-development

2. Crie o SKILL.md dentro dela com o frontmatter YAML entre os marcadores ---. Esse arquivo é o coração da skill: é ele que o Claude lê quando a skill é acionada

3. Escreva a description em terceira pessoa, dizendo o que a skill faz E quando usá-la. A description é o campo crítico de seleção: é por ela que o Claude escolhe a skill certa entre muitas disponíveis. A boa prática oficial é sempre terceira pessoa, porque a description é injetada no system prompt e ponto de vista inconsistente atrapalha a descoberta

O erro comum deste passo: escrever description: ajuda com specs

Isso não diz o que faz nem quando usar, e a skill simplesmente nunca é escolhida. Compare com o exemplo abaixo

---
name: Spec-Driven Development
description: Conduz a escrita da especificação antes da implementação, produzindo requisitos, design técnico e lista de tarefas com critérios de aceite verificáveis. Use quando o usuário for iniciar um projeto do zero, planejar uma feature nova ou pedir revisão de escopo antes de codar.
---

# Spec-driven development

## Quando aplicar
Aplique quando a tarefa envolver mais de uma tela, autenticação, banco de dados
ou integração externa. Para ajuste pontual, não use este fluxo.

## Fluxo
1. Escrever requisitos (o que o app faz, regras de negócio, jornada do usuário)
2. Escrever o design técnico (stack, banco, rotas, páginas, componentes)
3. Quebrar em tarefas na ordem de execução
4. Só então implementar, uma tarefa por vez

4. Entenda o papel do name. Em skill pessoal ou de projeto, o campo name define apenas o rótulo de exibição nas listagens: o comando continua vindo do nome do diretório ou do arquivo

O erro comum deste passo: trocar o name esperando que o comando mude junto, e depois ficar procurando por que ele não aparece com o nome novo

5. Escreva o corpo em markdown com o que interessa: o template de spec, os critérios de aceite e a lista de checagens antes de codar. É aqui que o SEU processo entra, e é o que a próxima seção detalha

6. Quebre o material longo em arquivos separados referenciados pelo SKILL.md. Quando uma skill é acionada, o Claude usa bash pra ler o SKILL.md do sistema de arquivos e trazer as instruções pra janela de contexto. Se o SKILL.md referencia outros arquivos, ele lê sob demanda, com chamadas adicionais

Ou seja: o SKILL.md é a porta de entrada enxuta, o material pesado fica em arquivos que só são lidos quando fazem falta

~/.claude/skills/spec-driven-development/
├── SKILL.md
└── references/
    ├── template-requisitos.md
    ├── template-design.md
    └── checagens.md

E dá pra ir além: uma skill pode empacotar scripts (Python, Bash, Node, qualquer runtime disponível no ambiente), arquivos de referência pra leitura sob demanda e até outras skills com as quais ela compõe

7. Decida se usa disable-model-invocation: true. Esse campo de frontmatter restringe a skill pra que só o usuário possa invocá-la, indicado pra fluxos com efeito colateral ou em que você quer controlar o momento da execução

No caso do SDD, faz sentido pensar bem: você quer que ele entre sozinho toda vez que pedir uma feature, ou só quando VOCÊ chamar?

8. Decida se declara allowed-tools. Skills que definem allowed-tools dão ao Claude acesso àquelas ferramentas sem aprovação a cada uso enquanto a skill está ativa, e as configurações de permissão continuam valendo pras demais ferramentas

O erro comum deste passo: declarar isso e testar via SDK, onde o campo não se aplica, e achar que a skill quebrou

O que colocar dentro da skill: template de spec, critérios de aceite e checagens

O frontmatter é o crachá

O corpo é o trabalho de verdade 😀

As seções fixas do template de spec

Três blocos que não podem faltar:

• Problema: que dor esse projeto resolve e pra quem
• Escopo: as funcionalidades que entram, uma a uma
• Fora de escopo: o que o app NÃO faz

Essa terceira seção é a que mais gente pula e a que mais economiza retrabalho. Sem ela, a IA preenche o vazio com o que a base de conhecimento dela achar bonito

Critérios de aceite verificáveis

Critério de aceite bom é aquele que dá pra responder com sim ou não olhando a tela

"a autenticação precisa funcionar bem" não é critério

"usuário deslogado que acessa /dashboard é redirecionado pro login" é critério

Deixe isso escrito no corpo da skill como REGRA de formato, não como sugestão, senão o agente devolve texto vago e você só descobre no teste

Checagens antes de codar

Uma listinha curta que a skill obriga a rodar antes de sair implementando:

• todo item do escopo tem pelo menos um critério de aceite?
• existe alguma decisão técnica ainda em aberto (banco, rota, formato de dado)?
• a lista de tarefas está na ordem de execução, e não na ordem em que a ideia apareceu?
• tem tarefa final de polimento?

Roubando vocabulário do Spec Kit

Não precisa inventar nome pra cada fase. O Spec Kit é um toolkit open source mantido no repositório github/spec-kit pra spec-driven development com agentes de código, e ele cita suporte a ferramentas como GitHub Copilot, Claude Code e Gemini CLI

O fluxo dele é um ciclo de fases em que cada etapa produz um arquivo markdown que a próxima lê: especificar, planejar, quebrar em tarefas e implementar

Sacou o pulo do gato? Cada fase deixa um artefato em disco, e o artefato é o contexto da fase seguinte. Sua skill pode adotar exatamente essa mecânica

Outro conceito que vale copiar é o constitution.md: o Spec Kit introduz esse arquivo pra estabelecer os princípios não negociáveis do projeto dentro do contexto de spec-driven development. Aquelas regras que valem pra tudo ("nunca commitar segredo", "toda rota nova tem teste") vivem ali, e não repetidas em cada spec

E tem a calibragem de cerimônia: existe caminho enxuto e caminho completo. Pra experimentos rápidos, pulam-se as etapas opcionais de validação; pra features de produção com ambiguidade relevante, o caminho completo com clarify, checklist e analyze pega problema antes de escrever código

Deixe isso explícito no corpo da skill, com o critério de quando cada caminho vale. Skill que impõe cerimônia máxima em tudo vira burocracia e você para de usar

O que aprendi aplicando spec-driven development na prática

Agora a parte que justifica cada escolha do template acima

No vídeo eu mostro por que projeto feito no vibe coding puro trava quando tenta escalar: o consumo de tokens sobe e a regra de negócio precisa ser reescrita INTEIRA quando entra uma funcionalidade nova

A imagem que eu uso é essa: vibe coding sem SDD é construir um corpo sem cabeça. A ideia é boa, mas não tem condução. O SDD funciona como baliza, um guarda-corpo pra não sair da curva

Sem planejamento, a IA escolhe sozinha a stack, planeja as features pela própria base de conhecimento e entrega o visual do jeito dela. Você pede algo sóbrio e premium e recebe um design chamativo, fora do que você imaginava

E olha, vibe coding solto funciona sim pra aplicação simples e projeto pessoal, sem drama. O problema aparece quando a intenção é comercializar e crescer

O padrão de travamento é sempre o mesmo: no começo o avanço é rápido, e depois o projeto empaca em coisas bobas por causa das decisões ruins tomadas lá no início

Por que três documentos

Eu uso a abordagem tradicional de três documentos:

• requirements: o que o app faz
• design doc: como ele será construído
• lista de tarefas: a ordem de execução

E isso não é invenção de agora: é o que a gente já fazia na área técnica com reuniões de planejamento, com o cliente e com os setores que iam usar o sistema, entendendo o problema antes de sair codando

O design doc, importante, não é sobre cores. Entram stack, esquema de banco de dados, rotas, páginas, componentes e decisões técnicas

No esquema de banco, basta listar os dados que você quer salvar. Não trave no tipo exato de cada campo, isso a implementação resolve

Quebrar em tarefas melhora MUITO a entrega, porque a IA para de tentar fazer tudo de uma vez e passa a avançar por continuidade. A regra que eu sigo: cada prompt executa uma tarefa concreta, tipo uma página ou um recurso mais complexo, e não um ajuste pequeno de cor

Na ordem, eu monto assim: setup inicial (pastas e bibliotecas), depois autenticação por ser complexa e vital, depois o recurso principal, salvar, e a dashboard de quem fez login. E sempre, sempre uma tarefa final de polimento pra aparar arestas

O exemplo que eu uso

No vídeo eu especifico um gerador de QR code: sem login, gera e baixa o código (URL, texto, wi-fi, contato); com login, salva e gerencia os códigos criados

Pra stack eu escolhi algo padrão e bem dominado pelas IAs: Next, TypeScript, Prisma e banco em arquivo pra evitar setup, avisando que em produção eu trocaria por Postgres

O requirements começa com uma visão geral curta do projeto e só depois detalha cada funcionalidade

E aí vem a seção que eu mais insisto: o que o app NÃO faz. Sem analytics, sem QR code dinâmico, sem logo no código, sem API pública, sem plano pago. Isso está lá justamente pra IA não inventar recurso

Detalhe importante pra quem não é técnico: o grosso do requirements não exige conhecimento técnico nenhum. É o dono da ideia dizendo o que quer que o app faça, as regras de negócio e a jornada do usuário

"Mas eu não sei programar, como escolho a stack?"

Dá pra se apoiar na IA pra isso. O resultado fica abaixo do que um arquiteto experiente faria, sem romantizar, mas é melhor do que deixar a IA solta escolhendo tecnologia sozinha

Onde vira burocracia

SDD gasta MAIS tokens no planejamento

Então em projeto pessoal que ninguém vai usar, pode ser queima de token à toa

A régua prática que eu dou: se o projeto passa de três prompts, ou tem autenticação, pagamento, perfis de usuário e dashboard, o planejamento compensa

Outra coisa que vale saber antes: eu recomendo cocriar os três documentos com a IA, mas o texto fica mais rígido e menos natural do que se você escrevesse. Contribua na parte que você domina, não delegue tudo

E cuidado com o tamanho. O doc de planejamento pode ser longo sem problema, ao contrário dos arquivos de memória e instrução do agente, que devem ficar sucintos. Por isso o SKILL.md enxuto com referências, lembra?

No vídeo abaixo eu monto os três documentos na tela, do requirements até a lista de tarefas, e explico decisão por decisão

Ah, e vale dizer: o SDD que eu demonstro ali é feito À MÃO pelo próprio usuário, sem framework nenhum. Que é exatamente o processo que a gente está transformando em skill agora 😀

Como reusar a skill em todos os projetos (e distribuir para o time)

A parte boa: metade do trabalho já está feita

1. Pra você, já está resolvido. Skills pessoais ficam disponíveis em todos os projetos do usuário, então uma skill em ~/.claude/skills/spec-driven-development/ já vale em qualquer pasta que você abrir

2. Pra compartilhar, empacote como plugin. O layout de distribuição usa o diretório skills/. E se o plugin não tem diretório skills/ nem campo skills no manifesto, um SKILL.md na raiz do plugin é carregado como skill única

3. Use kebab-case no nome do plugin. Nomes de plugin devem estar em kebab-case, usando apenas letras minúsculas, dígitos e hífens

4. Saiba como o comando fica. Em uma skill de plugin, o campo name do frontmatter SUBSTITUI o nome do diretório no último segmento do comando: um plugin com skills/review/SKILL.md e name: fancy vira /meu-plugin:fancy

O erro comum deste passo: achar que o comportamento do name é igual ao da skill pessoal. Não é. Em skill pessoal o name é só rótulo de exibição; em skill de plugin ele muda o comando

5. Instale e recarregue. Marketplaces de plugin são adicionados com /plugin marketplace add e plugins são instalados com /plugin install. Depois de instalar, roda /reload-plugins pras skills ficarem disponíveis na sessão atual

O erro comum deste passo: instalar, digitar o comando, não encontrar nada e achar que deu errado. Faltou o /reload-plugins 🙂

Vale a pena usar Spec Kit ou skill própria?

Depende de uma pergunta só: você já tem um processo ou está começando do zero?

Spec Kit tem dois componentes principais: a CLI Specify, que faz o bootstrap do projeto baixando os templates oficiais pro agente e plataforma escolhidos, e um conjunto de templates e scripts auxiliares. O bootstrap sai assim:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Você ganha o ciclo de fases pronto, o constitution.md, os templates e a escolha entre caminho enxuto e caminho completo. Ótimo pra quem quer estrutura na mão sem projetar nada

Skill própria carrega o SEU processo. Ela nasce do que você já faz hoje, com o vocabulário do seu time, as suas checagens, as suas regras de negócio recorrentes. Ninguém precisa aprender uma convenção nova, e você ajusta na hora que perceber que algo faltou

Os dois caminhos não brigam, viu? Nada impede de escrever uma skill própria que adote o vocabulário de fases do Spec Kit, que é exatamente o que a gente fez lá em cima

E se você quer ver como outra galera resolveu isso, tem a skill de comunidade sdd-skill, mantida pela SpillwaveSolutions, que guia o usuário pelo Spec-Kit do GitHub e pela metodologia. Pra referência de ESTRUTURA de skill, a Anthropic mantém um repositório público oficial de Agent Skills em anthropics/skills

Um último ponto que muita gente não sabe: as skills do Claude Code seguem o padrão aberto Agent Skills, que funciona em múltiplas ferramentas de IA, e o Claude Code estende o padrão com recursos adicionais como controle de invocação e execução por subagente

Ou seja, o trabalho que você tem escrevendo esse SKILL.md não fica preso numa ferramenta só. Se quiser ver o mesmo formato em outro agente, tem o passo a passo de criar uma skill no Antigravity por aqui também

Próximo passo

O ganho aqui não é o arquivo

O ganho é parar de reescrever o mesmo processo toda vez que você abre uma pasta vazia

Então o próximo passo é bem concreto: abra ~/.claude/skills/spec-driven-development/SKILL.md e escreva a PRIMEIRA versão com o template que você já usa hoje, mesmo que ele esteja meia boca. Description em terceira pessoa dizendo o que faz e quando usar, corpo com o template de spec, os critérios de aceite e as checagens

Depois roda em um projeto real e ajusta: se o Claude não acionou a skill, o problema quase sempre é a description; se ele acionou e entregou spec vaga, o problema são os critérios de aceite frouxos

A terceira rodada já sai afiada, pode confiar

Até o próximo post! 😀