MÓDULO 3.2

🎯 Construa sua primeira skill (diagnostico-ia)

Você vai sair desta aula com uma skill de verdade: diagnostico-ia. Dá nome e descrição de uma empresa, recebe maturidade, quick wins e roadmap. Do gatilho ao versionamento.

6
Tópicos
~45
Minutos
Intermediário
Nível
Prática
Tipo
1

🎣 Definir o gatilho (a description que faz a skill disparar)

A description no frontmatter diz ao modelo quando usar a skill. Uma boa tem verbos de ação + gatilhos concretos ("Use ao diagnosticar a maturidade de IA de uma empresa descrita em texto"). Description vaga = a skill nunca dispara. É o detalhe que separa uma skill que funciona de uma que dorme no repositório.

nome + descrição da empresa diagnostico-ia description → corpo → referências maturidade 1-5 quick wins roadmap 30/60/90

✓ Boa description

  • ✓Começa com verbo de ação ("Use ao diagnosticar...")
  • ✓Gatilho concreto: "empresa descrita em texto"
  • ✓Diz o "use quando" — o modelo sabe a hora certa

✗ Description fraca

  • ✗Genérica: "ajuda com estratégia de IA"
  • ✗Sem gatilho — não diz quando aplicar
  • ✗Ambígua — colide com outras skills e nunca dispara

// .claude/skills/diagnostico-ia/SKILL.md

---
name: diagnostico-ia
description: Use ao diagnosticar a maturidade de IA de uma
  empresa descrita em texto — gera maturidade 1-5, quick
  wins (esforço × impacto) e um roadmap 30/60/90.
---

# Diagnóstico de IA

## Passos
1. Ler nome + descrição da empresa.
2. Pontuar a maturidade de IA numa escala 1-5.
3. Listar 3 quick wins (baixo esforço, alto impacto).
4. Propor um roadmap 30/60/90 dias.
5. Devolver em Markdown, pronto para virar entregável.

## Referências
- referencias/maturidade.md
- referencias/quick-wins.md

💡 Dica prática

Escreva a description pensando como o modelo lê: "se eu visse essa frase, saberia que é AGORA que devo usar a skill?". Se a resposta for "talvez", reescreva com um gatilho mais concreto. A description é a porta — sem ela, ninguém entra.

Gatilho

o "use quando"

Verbos

ação concreta

Frontmatter

name + description

Disparo

vaga = nunca firma

2

📝 Escrever o corpo (passos claros, determinísticos)

O corpo em Markdown lista passos numerados para a saída ser repetível: ler a empresa → pontuar a maturidade 1-5 → listar 3 quick wins → propor um roadmap 30/60/90. Determinístico significa que, rodando duas vezes, você recebe a mesma estrutura — não improviso. Cada passo é uma ordem, não uma sugestão.

1

Ler a empresa

Extrai nome, setor, porte e contexto do texto recebido. Sem isso, o diagnóstico é genérico — o passo 1 ancora todos os outros.

2

Pontuar a maturidade (1-5)

Dá uma nota de 1 a 5 com justificativa curta. Uma escala fixa torna o resultado comparável entre empresas — virou métrica, não opinião.

3

Listar 3 quick wins

Exatamente três — baixo esforço, alto impacto. O número fixo evita listas infláveis e força priorização real.

4

Propor roadmap 30/60/90

Três janelas, ações concretas em cada. Devolve em Markdown, pronto para virar entregável — o cliente abre e executa.

Numerado

passos em ordem

Determinístico

mesma estrutura

Escala fixa

1-5 comparável

Entregável

Markdown pronto

3

📎 Anexar referências (os cheat sheets da T2)

A skill aponta para arquivos de apoio — os cheat sheets de maturidade e quick wins que você destilou na Trilha 2 — carregados só quando necessário. É o RAG preguiçoso aplicado: o SKILL.md fica enxuto, mas a skill ganha o rigor de consultoria na hora de produzir.

📄 referencias/maturidade.md

A rubrica da escala 1-5: o que caracteriza cada nível, sinais e exemplos. Carregada quando o passo 2 precisa pontuar.

📄 referencias/quick-wins.md

O catálogo de vitórias rápidas por departamento, mapeadas em esforço × impacto. Entra quando o passo 3 lista os quick wins.

// estrutura da pasta da skill

.claude/skills/diagnostico-ia/
├── SKILL.md
└── referencias/
    ├── maturidade.md
    └── quick-wins.md

💡 Dica prática

Não cole o conteúdo dos cheat sheets dentro do SKILL.md. Referencie o caminho (referencias/maturidade.md) e deixe o modelo abrir o arquivo só quando o passo exigir. SKILL.md enxuto = skill que dispara rápido e não desperdiça contexto.

Sob demanda

carrega quando precisa

Enxuto

SKILL.md leve

Rigor

cheat sheets da T2

RAG preguiçoso

contexto sob medida

4

🧪 Testar a skill com um caso real

Rode a skill numa empresa de verdade e verifique três coisas: ela disparou sozinha (a description funcionou)? A saída tem maturidade + quick wins + roadmap? O formato está pronto para entregar? Teste é onde a teoria encontra o atrito real.

// o que você digita ao Claude Code

Use a skill diagnostico-ia para a empresa "Stripe":
B2B payments, fintech, ~8000 funcionários.

🔍 O checklist do teste

  • •Disparou sozinha? Se você teve que forçar, a description está fraca — volte ao tópico 1.
  • •Saída completa? Maturidade 1-5 + 3 quick wins + roadmap 30/60/90 — os três presentes.
  • •Pronta para entregar? Markdown limpo, sem rascunho ou pergunta no meio.
Caso real

empresa de verdade

Disparo

firmou sozinha?

Saída

os 3 blocos

Formato

entregável limpo

5

🔁 Iterar e empacotar

A primeira versão raramente acerta de cara. Ajuste a description e os passos a partir do que o teste mostrou, feche a pasta da skill (SKILL.md + referências) e deixe-a pronta. Iterar é o trabalho de verdade — a primeira versão é só o rascunho que ganha forma.

✓ Skill pronta

  • ✓Dispara sozinha — a description fecha o gatilho sem você forçar
  • ✓Saída consistente — mesma estrutura toda vez que roda
  • ✓Referências carregam — os cheat sheets entram na hora certa

✗ Ainda não

  • ✗Não dispara — você precisa pedir a skill pelo nome toda vez
  • ✗Saída varia — às vezes pula o roadmap, às vezes inventa formato
  • ✗SKILL.md inchado — conteúdo que devia estar nas referências

💡 Dica prática

Itere uma coisa por vez: ajuste só a description, teste; depois só os passos, teste. Mudar tudo de uma vez esconde o que realmente resolveu. Pequenos ciclos curtos chegam mais rápido na versão que dispara.

Ajustar

description + passos

Fechar

pasta completa

Ciclo curto

uma mudança por vez

Pronta

consistente e enxuta

6

🏷️ Versionar e compartilhar

Versione a skill no Git (junto com o projeto) e, opcionalmente, compartilhe com o time ou a comunidade. O histórico te dá uma evolução rastreável; o versionamento protege o ativo; o compartilhamento constrói autoridade. A skill deixa de ser um arquivo solto e vira peça do seu repositório.

📜
Histórico — cada commit conta como a skill evoluiu; dá para voltar a qualquer versão.
🔒
Proteção — versionar é o seguro do ativo: nada se perde, tudo é recuperável.
📣
Autoridade — compartilhar a skill com o time ou a comunidade mostra que você constrói, não só usa.

💡 Dica prática

Commit a skill junto com o projeto que a usa, não num repositório à parte. Assim ela viaja com o contexto — quem clona o projeto recebe a ferramenta pronta. Uma boa mensagem de commit ("ajusta gatilho da diagnostico-ia") já é parte do histórico.

Git

junto do projeto

Histórico

evolução rastreável

Proteção

o ativo seguro

Autoridade

você constrói

✅ Resumo do módulo

✓
A description é o gatilho — verbos + gatilho concreto fazem a skill disparar sozinha.
✓
O corpo determinístico dá saída repetível — passos numerados, mesma estrutura toda vez.
✓
Referências dão rigor sem inchar — cheat sheets da T2 carregados sob demanda.
✓
Testar + iterar + versionar — é o que transforma a skill num ativo de verdade.

🎯 Missão 3.2 — diagnostico-ia no ar

Coloque sua primeira skill pra rodar:

  1. Criar .claude/skills/diagnostico-ia/SKILL.md com frontmatter + 5 passos.
  2. Anexar os cheat sheets da T2 como referências.
  3. Rodar a skill para 1 empresa de verdade.
  4. Iterar a description até ela disparar sozinha.

Sucesso: a skill diagnostico-ia roda e cospe um mini-diagnóstico (maturidade + quick wins + roadmap). O que você ganhou: a primeira engrenagem da Fábrica — reutilizável e versionada.

Próximo módulo:

3.3 — A skill de documentos (DocX/PPTX/Excel/PDF)

← Voltar para Trilha Próximo Módulo →