Como criar skills no Claude Code: arquitetura real para agentes de IA

Prompt é instrução de sessão. Skill é conhecimento versionado. A diferença parece pequena até você tentar fazer o mesmo trabalho cinquenta vezes.

Se você usa Claude Code todo dia, chega uma hora em que prompt longo vira dívida técnica.

Você repete contexto. Cola os mesmos arquivos. Explica de novo uma decisão que já tinha explicado ontem. Pede o mesmo tipo de análise pela décima vez e recebe uma resposta quase certa, mas sem a precisão que você precisa pra trabalhar de verdade.

Muita gente tenta resolver isso escrevendo um prompt maior.

Eu acho que é o lugar errado pra mexer.

Quando o trabalho é recorrente, técnico e depende de método, prompt vira gambiarra. O problema não é a frase que você manda pro modelo. O problema é não ter uma estrutura que carregue conhecimento entre sessões.

É aí que entra skill.

Neste artigo eu vou mostrar como estruturo skills no Claude Code usando SKILL.md, arquivos em references/ e um loading map simples. O exemplo real é uma skill baseada no Alex Hormozi que uso para avaliar ofertas, funis, pricing e garantias.

Não é um texto sobre prompt engineering. É sobre arquitetura de contexto para builders técnicos que usam agente de IA como ferramenta de trabalho.

O que é uma skill no Claude Code

Uma skill é um módulo reutilizável que ensina o agente a fazer um tipo específico de trabalho.

Na prática, ela tem três partes:

1. Um SKILL.md, que funciona como entrada e router
2. Uma pasta references/, com método e conhecimento de domínio
3. Um mapa dizendo quando cada referência deve entrar no contexto

A parte importante é essa: uma skill boa não carrega tudo sempre.

Ela carrega o que faz sentido para aquela pergunta. Se o usuário quer discutir pricing, carrega pricing. Se quer discutir retenção, carrega retenção. Se quer avaliar uma oferta inteira, carrega o checklist de decisão.

Tecnicamente, isso é uma camada simples de retrieval condicional. Nada místico. Nada de prompt mágico. Só uma forma melhor de organizar o conhecimento que o agente precisa usar.

Prompt é instrução de sessão. Skill é conhecimento versionado.

A diferença parece pequena até você tentar fazer o mesmo trabalho cinquenta vezes.

O problema que skills resolvem

Um LLM é stateless. Cada sessão nova começa praticamente do zero. O que existe é o contexto que você passa naquele momento.

Para uso casual, ok. Para trabalho técnico ou estratégico recorrente, começa a quebrar rápido.

O primeiro problema é reconstrução de contexto. Toda sessão você precisa explicar quem é o usuário, qual é o domínio, que método aplicar, o que não pode fazer, qual tom usar, qual formato de resposta serve. Isso gasta token, tempo e energia. E pior: nunca sai exatamente igual.

O segundo problema é ativação imprecisa.

Quando você escreve “aja como um especialista em marketing”, o modelo responde como um especialista genérico em marketing. Ou seja, responde com o tipo de coisa que qualquer post de LinkedIn poderia dizer.

Agora escreve “Alex Hormozi avaliando uma oferta”. A ativação muda. O modelo tem muito mais material associado a uma pessoa, seus livros, entrevistas, frases, frameworks e exemplos do que a uma categoria abstrata como “especialista”.

Só que nomear a pessoa ainda não resolve tudo.

O terceiro problema é conhecimento proprietário ausente.

O modelo pode conhecer Alex Hormozi pelos pesos de treinamento. Pode ter visto entrevistas, livros, vídeos e transcrições. Mas ele não conhece a sua versão organizada do método. Não conhece o Delivery Cube que você extraiu e separou. Não conhece suas decision rules. Não conhece os exemplos internos que você usa para avaliar oferta.

Esse conhecimento precisa morar em algum lugar.

Na minha arquitetura, ele mora na skill.

Estrutura de diretório de uma skill

Uma skill boa não é um arquivo gigante.

Ela é uma pasta com um arquivo principal e referências separadas por tipo de decisão.

Exemplo:

.claude/
├── skills/
│   └── alex-hormozi/
│       ├── SKILL.md
│       └── references/
│           ├── 00-canon.md
│           ├── 01-value-equation.md
│           ├── 02-grand-slam-offer.md
│           ├── 03-money-models.md
│           ├── 04-pricing-and-guarantees.md
│           ├── 05-naming-and-positioning.md
│           ├── 06-advertising-and-leads.md
│           ├── 07-closing-and-sales.md
│           ├── 08-retention-and-ltv.md
│           ├── 09-branding-and-proof.md
│           ├── 10-fast-cash-plays.md
│           ├── 11-decision-checklist.md
│           └── 12-canonical-phrases.md
├── steering/
│   ├── product.md
│   ├── tech-stack.md
│   └── conventions.md
├── commands/
├── specs/
└── CLAUDE.md

SKILL.md não deveria virar um prompt infinito. Ele é o router.

As referências também não deveriam virar um lixão de anotações. Elas são módulos de conhecimento. Cada uma entra quando existe uma razão clara para entrar.

Essa separação parece burocrática até você precisar manter a skill por meses. Aí vira a diferença entre sistema e bagunça.

Exemplo real: uma skill Alex Hormozi para avaliar ofertas

Eu uso uma skill baseada no Alex Hormozi para avaliar ofertas, funis, pricing, garantias, lead magnets e retenção.

Ela tem:

• 1 arquivo SKILL.md
• 13 arquivos em references/
• aproximadamente 80KB de método estruturado
• frameworks extraídos de livros, vídeos e playbooks
• um loading map que define quando cada referência entra

A skill não tenta imitar o Hormozi com um prompt bonitinho.

Ela combina nomeação precisa, referências densas e roteamento explícito de contexto.

Esse é o ponto que muita gente perde. Nomear uma persona ajuda na ativação do modelo, mas a densidade vem das referências.

Sem referência, você tem o Hormozi genérico que já existe nos pesos do modelo.

Com referência, você tem um operador de oferta usando método específico, com checklist, critérios e vocabulário de decisão.

É outra categoria de output.

Template mínimo de uma skill

Um SKILL.md precisa ser curto o suficiente para funcionar como router e específico o suficiente para ativar o comportamento certo.

Um exemplo mínimo:

---
name: alex-hormozi
description: >
  Designs, critiques, and refines commercial offers using
  Value Equation, Grand Slam Offer, pricing, guarantees,
  closing and retention frameworks.
---

Depois do frontmatter, vem o corpo:

# Alex Hormozi - Offer Design Operator

## When to invoke this skill

Use this skill when the user asks about:

- offer design
- pricing
- guarantees
- funnel economics
- lead magnets
- retention
- sales conversion

## Reference loading map

| Reference | When to load |
|---|---|
| references/00-canon.md | Core offer principles |
| references/01-value-equation.md | Pricing and perceived value questions |
| references/02-grand-slam-offer.md | Offer construction |
| references/04-pricing-and-guarantees.md | Pricing, guarantees and risk reversal |
| references/07-closing-and-sales.md | Objections and closing |

## Output mode

Return one direct recommendation.
Use the relevant framework.
Avoid generic advice.
Refuse weak offers when the math does not work.

Isso já é muito melhor do que um prompt solto.

O arquivo define quando a skill deve ser usada, qual domínio ela cobre, quais referências consultar e que tipo de resposta entregar.

Não precisa nascer perfeito. A primeira versão de uma skill boa normalmente é pequena. O importante é ela ter fronteira, método e teste.

Como nomear uma skill

Nome de skill não é decoração. É parte do mecanismo de ativação.

O agente usa nome e descrição para decidir se deve invocar aquela skill. Se o nome for genérico, a ativação fica ruim.

Compare:

Nome fraco	Nome melhor
marketing	alex-hormozi-offer-design
writing	arthur-miller-script-review
seo	neil-patel-seo-strategy
teaching	feynman-explanation-review
funnels	russell-brunson-funnel-architecture

O nome melhor aponta para um domínio específico e ativa um corpus reconhecível nos pesos do modelo.

Mas cuidado: persona não substitui método.

A persona ajuda a localizar um espaço de comportamento. As referências fazem o trabalho pesado.

Persona ou função?

Nem toda skill precisa ser baseada em uma pessoa pública.

Use persona quando existe um corpus forte por trás: livros, palestras, entrevistas, frameworks publicados, playbooks, estudos de caso.

Alex Hormozi faz sentido para ofertas. Russell Brunson faz sentido para funis. Neil Patel faz sentido para SEO. Richard Feynman faz sentido para clareza didática.

Mas para trabalho técnico interno, muitas vezes uma função é melhor:

• security-reviewer
• database-migration-planner
• api-contract-auditor
• react-performance-reviewer
• technical-seo-auditor

A regra prática é simples.

Se existe uma pessoa com método público forte, persona pode ajudar. Se o trabalho depende mais de checklist técnico do que de estilo cognitivo, use função.

Forçar persona onde não precisa só deixa a skill teatral.

Como estruturar referências em markdown

Referência não é anotação solta. É método operacional.

Cada arquivo em references/ deve resolver um tipo de decisão.

Na skill do Hormozi, por exemplo:

Arquivo	Decisão que resolve
00-canon.md	Princípios centrais de oferta
01-value-equation.md	Valor percebido e pricing
02-grand-slam-offer.md	Construção de oferta irresistível
03-money-models.md	Sequência de produtos e monetização
04-pricing-and-guarantees.md	Preço, garantia e risco
07-closing-and-sales.md	Objeções e fechamento
08-retention-and-ltv.md	Retenção e LTV
11-decision-checklist.md	Veredito sobre uma oferta específica

Isso evita dois erros comuns.

O primeiro é colocar tudo num arquivo único. O agente carrega informação demais e perde precisão.

O segundo é dividir por fonte: “Livro 1”, “Livro 2”, “Vídeo 3”. Isso é bom para arquivamento, mas ruim para execução. A pergunta do usuário não vem por fonte. Ela vem por problema.

Divida por decisão, não por origem.

Loading map: a parte mais importante do SKILL.md

O loading map é onde a skill deixa de ser prompt organizado e vira arquitetura de retrieval.

Exemplo:

| Reference | When to load |
|---|---|
| references/00-canon.md | Any offer decision |
| references/01-value-equation.md | Questions about value, price or conversion |
| references/02-grand-slam-offer.md | Building a new offer |
| references/04-pricing-and-guarantees.md | Pricing, guarantee or risk reversal |
| references/07-closing-and-sales.md | Sales calls, objections, close rate |

Sem esse mapa, o agente precisa adivinhar.

E quando ele adivinha, costuma pegar atalho. Responde com o que já está mais fácil nos pesos, não com o que você colocou nas referências.

Com o mapa, você cria uma ponte explícita entre intenção do usuário e arquivo de método.

Essa ponte é o que torna a skill previsível.

Por que sua skill pode ignorar as referências

Esse é o failure mode mais perigoso porque parece sucesso.

Você ancora bem a persona. O modelo vê “Alex Hormozi”, ativa o cluster dos pesos de treinamento e começa a responder. Frases de efeito, tom, ideias gerais, energia correta.

Só que ele não carregou a referência.

O output pode soar bom. Pode até impressionar alguém que não conhece o método. Mas ele não usou o conhecimento que você construiu.

Esse é o Hormozi de superfície.

Não é o Hormozi dos frameworks organizados. Não é o método extraído, limpo, separado e versionado. Não é a sua skill fazendo o trabalho. É o modelo improvisando com o que já sabia.

Quando isso acontece, a skill falhou silenciosamente.

Como forçar densidade na resposta

Não adianta escrever “por favor consulte as referências”. Isso é sugestão.

Você precisa forçar estruturalmente.

Eu uso quatro camadas.

1. Roteamento explícito

A skill precisa dizer quais referências carregar em cada tipo de pergunta.

Não deixe o agente decidir tudo sozinho. Ele vai tentar economizar caminho.

2. Output dependente de framework

Se a resposta precisa aplicar Value Equation, RAISE ou Grand Slam Offer, o modelo tem menos espaço para responder genericamente.

Exemplo:

Every recommendation must explicitly map to the relevant framework.
If pricing is discussed, use RAISE.
If offer value is discussed, use the Value Equation.

O framework vira uma trava. Para cumprir o output mode, o agente precisa usar a referência certa.

3. Checklist de decisão

Uma referência como decision-checklist.md força o modelo a atravessar critérios antes de dar veredito.

Checklist é melhor que conselho aberto.

Conselho aberto vira palestra. Checklist vira decisão.

4. Frases canônicas como calibração

Frases canônicas ajudam a ancorar comportamento.

Exemplos:

• “Simple scales. Fancy fails.”
• “Volume negates luck.”
• “Revenue is vanity. Profit is sanity. Cash is reality.”

Não é para enfeitar. É para calibrar timbre e detectar quando a resposta ficou genérica demais.

Se a resposta soa como qualquer assistente de IA poderia ter escrito, a skill provavelmente não ancorou.

Skill como componente composável

Eu não uso uma skill. Uso várias.

Skill	Domínio
Alex Hormozi	Ofertas, pricing, garantias, value stack
Russell Brunson	Funis, value ladder, conversão
Gary Vaynerchuk	Conteúdo, distribuição, social
Neil Patel	SEO, keywords, conteúdo orgânico
Arthur Miller	Roteiro e narrativa
Richard Feynman	Clareza didática

Cada skill é um módulo independente. Tem contrato próprio, referência própria e output esperado.

Eu não tento fazer várias skills conversarem dentro da mesma chamada. Se preciso de Hormozi e Brunson olhando a mesma estratégia, rodo uma skill primeiro, pego o output e alimento a outra.

A composição acontece na orquestração, não dentro da skill.

Pense como microservices, mas sem exagerar na analogia. Cada serviço tem fronteira clara, faz uma coisa bem e retorna algo que outro serviço pode consumir.

Skill boa tem essa mesma propriedade. Ela não tenta resolver o mundo.

Quando criar uma skill

Skill é overengineering para tarefa mecânica.

Não crie skill para traduzir um texto simples, formatar JSON, explicar uma função pequena, gerar uma ideia descartável ou fazer uma tarefa que você não vai repetir.

Crie skill quando três condições aparecem juntas.

Primeiro: o trabalho se repete. Você vai precisar daquela expertise de novo. Não uma vez. Toda semana.

Segundo: existe método formalizado. A skill precisa carregar método, não opinião. Pode ser método público, como livros e frameworks. Pode ser método interno, como checklist de review, padrão arquitetural da empresa ou postmortem de produção.

Terceiro: o output precisa de consistência. Se duas sessões diferentes produzem respostas incompatíveis para o mesmo tipo de problema, você precisa tirar variação do processo.

Skill é um jeito de reduzir variação.

Checklist para criar uma skill no Claude Code

Antes de considerar uma skill pronta, eu passo por este checklist:

• O nome é específico?
• A descrição deixa claro quando ativar a skill?
• O domínio é estreito o suficiente?
• O SKILL.md funciona como router, não como dump?
• As referências estão separadas por tipo de decisão?
• Existe loading map explícito?
• O output mode define formato de resposta?
• A skill força uso de framework quando necessário?
• Existe pelo menos um exemplo real de input e output?
• A skill está versionada no git?
• Dá para testar se ela consultou as referências?

Se a resposta for “não” em três ou mais itens, você provavelmente ainda tem um prompt grande, não uma skill.

Eu sei que isso parece rígido. Mas rigidez aqui economiza erro lá na frente.

Erros comuns ao criar skills no Claude Code

O erro mais comum é criar skill genérica demais.

marketing é genérico. alex-hormozi-offer-design é específico. Quanto mais genérico o nome, pior a ativação.

Outro erro é colocar tudo no SKILL.md. O arquivo principal vira um prompt gigante, ruim de manter e cheio de ruído. SKILL.md deve rotear. Referência deve carregar método.

Também vejo muita gente separando referência por fonte: “Livro 1”, “Livro 2”, “Podcast 3”. Isso organiza arquivo, mas não organiza execução. O agente precisa resolver problema, não lembrar de onde veio a anotação.

Tem ainda o erro de não definir output mode. Sem isso, o modelo tende a entregar lista de opções. Builder técnico não precisa de cardápio infinito. Precisa de decisão, tradeoff e critério.

E talvez o erro mais traiçoeiro: confundir persona com densidade.

Persona melhora ativação. Densidade vem de referência.

Sem referência, a skill vira cosplay.

Por fim, teste a skill. Parece óbvio, mas quase ninguém faz.

Dê o mesmo input antes e depois da skill. Compare se usou framework, se carregou a referência certa, se reduziu generalidade, se entregou decisão mais útil e se manteve consistência entre sessões.

Se você não mede, você só está acreditando.

Como eu criaria a primeira versão de uma skill

Meu processo começa com o job.

Uma frase.

Exemplo:

Avaliar ofertas comerciais e recomendar mudanças em pricing, garantia, valor percebido e estrutura de entrega.

Se o job não cabe numa frase, a skill está ampla demais.

Depois vem o corpus. De onde sai o método?

No exemplo do Hormozi:

• $100M Offers
• $100M Leads
• $100M Money Models
• playbooks do Acquisition.com
• vídeos e entrevistas
• frases canônicas

Para uma skill interna, o corpus pode ser ADR, pull request antigo, runbook, postmortem, checklist técnico ou spec aprovada.

A etapa seguinte é extração.

Não cole conteúdo bruto. Extraia princípios, frameworks, critérios de decisão, exemplos, anti-patterns, checklists e frases de calibração.

Depois separe por decisão.

Ruim:

book-notes.md
video-notes.md
random-ideas.md

Melhor:

pricing-and-guarantees.md
closing-and-sales.md
retention-and-ltv.md
decision-checklist.md

Aí você escreve o loading map.

Se a pergunta é sobre preço, carrega pricing. Se é sobre retenção, carrega retention. Se é sobre fechamento, carrega closing.

Óbvio. Mas quase ninguém faz.

Por último, teste com caso real. Não use exemplo brinquedo.

No meu caso: uma oferta real, um funil real, um preço real, uma objeção real de cliente, um competidor real.

Skill que só funciona em exemplo inventado não serve para produção.

FAQ sobre skills no Claude Code

Skill é a mesma coisa que prompt?

Não.

Prompt é uma instrução de sessão. Skill é um módulo persistente com nome, descrição, domínio, referências e regras de carregamento.

Quando devo criar uma skill?

Quando o trabalho se repete, exige método específico e precisa de consistência entre sessões.

Se é tarefa única, use prompt simples.

Uma skill precisa ter persona?

Não.

Persona ajuda quando existe um corpo de trabalho público e reconhecível. Para tarefas técnicas internas, uma skill pode ser baseada em função: reviewer, architect, security auditor, migration planner.

Quantas referências uma skill deve ter?

O suficiente para separar domínios de decisão.

No meu exemplo, a skill de ofertas tem 13 referências e cerca de 80KB. Mas uma skill técnica interna pode começar com 3 a 5 referências bem escritas.

Claude Code carrega todas as referências automaticamente?

Não deveria.

O ideal é criar um loading map no SKILL.md para orientar quais arquivos devem ser carregados em cada tipo de pergunta.

Posso criar skills para agentes de IA fora do Claude Code?

Sim.

O conceito é portátil. SKILL.md é uma forma concreta de implementar isso no Claude Code, mas a arquitetura vale para qualquer agente que suporte contexto persistente, arquivos de referência e roteamento.

Skill substitui RAG?

Não exatamente.

Skill é melhor quando o domínio é pequeno, estruturado e metodológico. RAG com vector database é melhor quando o corpus é grande, muda com frequência e precisa de busca semântica ampla.

Para método operacional, skill costuma ser mais simples e previsível.

Fechamento

A maioria das pessoas tenta fazer IA trabalhar melhor escrevendo prompts maiores.

Builder técnico deveria olhar para outro lugar.

O problema não é o texto que você manda para o modelo. É a arquitetura de contexto em volta dele.

Skill bem construída tem nome específico, domínio estreito, referências densas, loading map explícito e output mode claro.

Nomear a persona certa ajuda. Mas o que muda o jogo é carregar método com densidade e forçar o agente a usar esse método, em vez de responder com o que já tem nos pesos.

Prompt resolve uma sessão.

Skill vira infraestrutura.

Felipe Fontoura base25.so