Como montar seu próprio sistema no Claude Code começando pequeno?

Fala aí, beleza? Sistema no Claude Code não nasce de framework instalado

nasce de uma repetição sua virando arquivo

A cena é sempre a mesma: tu abre o Claude Code, escuta falar de skills, subagentes, hooks, rules, MCP, plugins, marketplace, e a sensação é de que tem um sistema inteiro pra montar antes de escrever a primeira linha útil

Aí vem a paralisia, e o atalho fácil é instalar um framework pronto de terceiros pra alguém pensar por você

Este post é o caminho contrário: método conceitual do zero, começando por UMA peça só, com arquivo seu, no seu projeto

A ordem é essa: identificar a repetição, escolher a peça que empacota ela e só depois crescer

O que você precisa antes de criar a primeira peça:

Lista curta, sem enrolação:

• Claude Code instalado e um projeto REAL aberto (sistema de verdade nasce de repetição de verdade, não de exemplo inventado)
• Uma repetição acontecendo: aquela instrução que tu redigita toda semana, no mesmo formato, com as mesmas ressalvas
• Saber onde as peças moram, porque tudo aqui é arquivo em disco

Os endereços que importam:

• Skills: <code>~/.claude/skills</code> (pessoais, valem em todos os projetos) ou <code>.claude/skills</code> (do projeto)
• Subagentes: <code>~/.claude/agents/</code> e <code>.claude/agents/</code>
• Hooks: <code>.claude/settings.json</code> (projeto), <code>~/.claude/settings.json</code> (usuário) e <code>.claude/settings.local.json</code> (local)
• Memória do projeto: <code>./CLAUDE.md</code> ou <code>./.claude/CLAUDE.md</code>, carregado no início de toda sessão

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Duas ajudas antes de começar: o <code>/init</code> gera um <code>CLAUDE.md</code> inicial analisando o seu código, e se já existir um ele sugere melhorias em vez de sobrescrever (então pode rodar sem medo)

E o <code>/context</code> mostra a seção Memory files com o que foi carregado de fato na sessão, que é o jeito de parar de adivinhar

Se você acompanha o ecossistema, sabe que ele muda rápido: só nos últimos tempos apareceu coisa como o que o Ponytail muda no dia a dia, e é justamente por isso que vale entender a mecânica em vez de decorar receita

Qual peça do Claude Code empacota a sua repetição?

Essa tabela é a referência que você vai usar no passo 2, então guarda ela

A lógica oficial é simples: cada extensão resolve um problema diferente do loop agêntico

Detalhe que economiza token e dor de cabeça: uma rule SEM escopo é mecanicamente idêntica a colar o conteúdo no <code>CLAUDE.md</code>

Sempre carregada, sempre custando contexto

Passo a passo: do primeiro arquivo ao sistema

Bora ver na prática? A regra do post é uma só: você não cria peça nenhuma até ter a repetição escrita

1. Identificar a repetição (ainda sem criar arquivo):

Abre o histórico da sua semana e procura a instrução que você redigitou mais vezes

Pode ser "revisa o diff, agrupa por assunto e escreve a mensagem de commit no padrão do time", pode ser "antes de mexer em teste, leia o setup"

Escreve ela num rascunho, com as ressalvas que você sempre adiciona depois que o Claude erra

O erro comum deste passo: criar a pasta antes de saber o que vai dentro dela, e acabar com um arquivo genérico que não muda nada no resultado

2. Escolher a peça pela tabela:

Aqui é decisão, não gosto pessoal

É procedimento que você quer acompanhando na thread principal, passo a passo? Skill

É padrão que precisa valer sempre, em toda conversa? <code>CLAUDE.md</code>

É tarefa lateral que só poluiria a conversa com resultado intermediário? Subagente

O erro comum deste passo: começar por subagente porque parece o mais avançado, e perder de vista o procedimento que você queria justamente ver acontecendo

3. Criar a skill mínima:

Skill é pasta com um <code>SKILL.md</code> dentro, formado por frontmatter YAML entre marcadores <code>—</code> e o corpo em markdown com as instruções

<pre><code>— description: Fluxo de commit do projeto: revisa o diff, agrupa as mudanças por assunto e escreve a mensagem no padrão do time —

# Commit do projeto

1. Rode o status e o diff e leia o que mudou
2. Agrupe as mudanças por assunto (nunca um commit gigante)
3. Escreva a mensagem no padrão do time e mostre pra mim antes de commitar

</code></pre>

O caminho fica assim: <code>.claude/skills/commit/SKILL.md</code>

O erro comum deste passo: colocar qualquer coisa antes do <code>—</code>

O Claude Code só lê o frontmatter quando o <code>—</code> de abertura é a PRIMEIRA linha do arquivo, senão ele trata o arquivo inteiro (incluindo os <code>—</code>) como conteúdo da skill

Um título, uma linha em branco no topo, e já era 😛

4. Escrever a description pensando no acionamento:

No frontmatter de skill os campos são opcionais e só a <code>description</code> é recomendada

E tem um motivo forte: é pela <code>description</code> que o Claude decide se aciona a skill

Então ela não é enfeite de documentação, ela é o gatilho

Descreve o QUE a skill faz e QUANDO ela deve entrar, com as palavras que você usa de verdade quando pede a tarefa

O erro comum deste passo: escrever "utilitários de git" e depois reclamar que a skill nunca acordou sozinha

5. Controlar quem pode invocar:

Tem três chaves aqui, e cada uma resolve um caso diferente

• <code>disable-model-invocation: true</code>: só o usuário invoca, indicado pra fluxo com efeito colateral, tipo commit ou deploy
• <code>user-invocable: false</code>: só o Claude invoca, indicado pra conhecimento de contexto que não é uma ação sua
• <code>allowed-tools</code>: a skill concede acesso a ferramentas específicas, por exemplo comandos git sem aprovação a cada uso

<pre><code>— description: Fluxo de commit do projeto: revisa o diff, agrupa por assunto e escreve a mensagem no padrão do time disable-model-invocation: true allowed-tools: Bash(git add ), Bash(git commit ), Bash(git status *) — </code></pre>

O erro comum deste passo: configurar ao contrário do desejado e depois achar que a peça está quebrada, quando ela só está obedecendo

6. Aceitar entrada com $ARGUMENTS:

Quando a skill precisa receber algo digitado por você, o <code>$ARGUMENTS</code> sempre expande pra string completa de argumentos como foi digitada

<pre><code>Rode o fluxo de deploy para o ambiente informado: $ARGUMENTS </code></pre>

E aqui vale a parada pra tirar uma dúvida que aparece sempre: "e os comandos customizados, morreram?"

Não, foram mesclados no sistema de skills

Um arquivo em <code>.claude/commands/deploy.md</code> e uma skill em <code>.claude/skills/deploy/SKILL.md</code> criam o MESMO <code>/deploy</code> e funcionam igual, e os arquivos que já existem em <code>.claude/commands/</code> continuam funcionando

O erro comum deste passo: achar que precisa migrar tudo de uma vez, quando não precisa migrar nada

7. Usar por alguns dias e ajustar:

Essa é a parte que a galera pula, e é a mais importante

Usa a skill na vida real, vê onde ela erra, corrige o texto do <code>SKILL.md</code>, usa de novo

Quando a repetição virar duas ou três coisas encadeadas, dá pra empilhar skills no início de uma mensagem: o Claude Code expande a primeira skill e também as outras empilhadas depois dela

O erro comum deste passo: criar dez skills no primeiro dia e não usar nenhuma de verdade

8. Só então crescer para um subagente:

Quando aparecer uma tarefa que gera montanha de resultado intermediário, aí sim

Subagentes são arquivos Markdown com frontmatter YAML e o corpo do arquivo vira o system prompt dele

Só <code>name</code> e <code>description</code> são obrigatórios

<pre><code>— name: auditor-de-dependencias description: Audita as dependências do projeto e devolve só o resumo dos achados model: sonnet —

Você audita dependências. Leia os arquivos de manifesto do projeto, liste o que está desatualizado ou duplicado e devolva apenas a conclusão, sem despejar o conteúdo bruto dos arquivos. </code></pre>

O campo <code>model</code> aceita alias (<code>sonnet</code>, <code>opus</code>, <code>haiku</code> ou <code>fable</code>), ID completo do modelo, <code>inherit</code>, ou pode ser omitido (o padrão é <code>inherit</code>)

O ganho é o isolamento: o subagente opera com janela de contexto própria e devolve só o resultado relevante pra conversa principal

E editar é gostoso: quando você edita ou adiciona um arquivo de subagente no disco, o Claude Code detecta a mudança em poucos segundos e a próxima delegação já usa a definição nova, sem reiniciar

O erro comum deste passo: rodar <code>/agents</code> esperando o assistente interativo

A partir da versão 2.1.198 ele não abre mais o wizard de criação: imprime um lembrete pra você pedir ao Claude ou editar <code>.claude/agents/</code> direto

9. Automatizar com hook quando a ação for determinística:

Se a coisa TEM que acontecer sempre, sem depender do modelo lembrar, isso não é skill, é hook

Configura com o comando <code>/hooks</code> ou direto no <code>settings.json</code>

<code>PreToolUse</code> dispara antes da execução de uma chamada de ferramenta e pode bloquear ela; <code>PostToolUse</code> dispara depois que a chamada foi bem-sucedida, que é o caso clássico de formatação automática e log

Dois detalhes que salvam tempo: matchers filtram quais ferramentas disparam o hook e só se aplicam aos eventos <code>PreToolUse</code>, <code>PostToolUse</code> e <code>PermissionRequest</code>

E quando um subagente chama uma ferramenta, esses eventos disparam os MESMOS hooks configurados pra conversa principal (ou seja, sua regra não vaza pelo lado)

Além de script, existem hooks do tipo <code>prompt</code> (manda um prompt pra um modelo Claude avaliar o turno e decidir em JSON) e do tipo <code>agent</code> (dispara um subagente que pode usar ferramentas como Read, Grep e Glob antes de decidir)

O erro comum deste passo: usar matcher em evento que não aceita matcher, e ficar caçando bug que não existe

10. Empacotar em plugin quando o conjunto se repetir entre projetos:

Plugin é a camada de empacotamento: junta skills, hooks, subagentes e servidores MCP numa única unidade instalável

Então ele é o FIM da história, não o começo

Empacota quando você já copiou os mesmos arquivos pro terceiro projeto na mão

O erro comum deste passo: empacotar antes de usar, e virar mantenedor de um sistema que nem você usa 😀

Três repetições comuns e a peça certa para cada uma:

Convenção de código e padrão de commit do time:

Isso é contexto sempre ativo, não é procedimento

Então o lugar natural é o <code>CLAUDE.md</code>, que é carregado no início de toda sessão

Se a convenção só vale pra uma fatia do repo (tipo os testes, ou uma pasta específica), aí melhor virar rule em <code>.claude/rules/</code> escopada com <code>paths</code> no frontmatter, aplicando só quando o Claude mexe em arquivo que casa com o padrão

Por que não skill? Porque skill é sob demanda, e regra de estilo que só entra quando alguém lembra de chamar não é regra, é sugestão

Rotina de commit ou deploy que você quer acompanhar passo a passo:

Aqui é skill, e skill na thread principal, porque a orientação oficial é clara: skill serve quando você quer o procedimento acontecendo na conversa, pra ver e guiar cada passo

Como tem efeito colateral, <code>disable-model-invocation: true</code> pra só você invocar

E <code>allowed-tools</code> com as entradas de git que o fluxo precisa, pra não aprovar comando um por um

Por que não subagente? Porque subagente devolve só o resultado, e num deploy você quer ver o caminho, não o relatório depois que já foi

Investigação que gera muito resultado intermediário:

Análise de log, busca profunda, auditoria de dependências

Esse tipo de tarefa é exatamente o caso de subagente: janela de contexto própria e retorno só do que interessa, sem entulhar a conversa principal com resultado intermediário

Por que não skill? Porque se rodar na thread principal, o barulho da investigação come o contexto da tarefa que você estava fazendo

E a formatação automática depois de cada edição, entra onde? Nem skill, nem subagente: hook <code>PostToolUse</code>, que roda depois que a chamada de ferramenta deu certo

Montar o seu ou instalar um framework pronto?

Veredito honesto, sem tom de venda

Começar pequeno com arquivos seus ensina o modelo mental: você entende por que aquela <code>description</code> acionou, por que aquele hook bloqueou, por que aquele contexto pesou

Framework pronto acelera quem JÁ sabe o que quer, e atrapalha quem não sabe, porque você passa a carregar um sistema inteiro que não consegue depurar

Se quiser comparar as duas abordagens com calma, tem um post aqui sobre framework pronto x fluxo próprio de prompts

Agora, as opções reais que existem hoje, sem promessa de resultado:

• skill-creator: plugin que ajuda a criar skills estruturadas, instalado com <code>/plugin install skill-creator@claude-plugins-official</code> e invocado com <code>/skill-creator</code>, guiando por levantamento de requisitos, criação de casos de teste e refinamento
• Superpowers: framework de skills de terceiros pra Claude Code, criado por Jesse Vincent, com código em obra/superpowers e instalável com <code>/plugin install superpowers@claude-plugins-official</code>

E onde essas coisas vivem: o marketplace oficial <code>claude-plugins-official</code> é adicionado automaticamente na primeira vez que você inicia o Claude Code em modo interativo, e é curado pela Anthropic

O da comunidade fica em <code>anthropics/claude-plugins-community</code> e hospeda plugins de terceiros

Pra adicionar qualquer outro, roda <code>/plugin marketplace add usuario-ou-org/nome-do-repo</code> e depois navega e instala pelo menu <code>/plugin</code>

Minha leitura: instalar framework é ótimo DEPOIS que você montou uma skill sua e entendeu a mecânica, porque aí você lê o arquivo dos outros e sabe o que está lendo

Erros que travam o primeiro sistema (e como prevenir):

A skill nunca aciona sozinha:

Causa: <code>description</code> fraca ou ausente, já que é justamente ela que controla o acionamento automático

Ou então <code>disable-model-invocation</code> / <code>user-invocable</code> configurados ao contrário do que você queria

Solução: reescrever a <code>description</code> dizendo o que a skill faz e quando deve entrar, e conferir se você não pediu pro modelo ficar de fora sem querer

Como prevenir: trata a <code>description</code> como a parte mais importante do arquivo, não como resumo burocrático

O frontmatter é ignorado e os <code>—</code> aparecem como texto:

Causa: o <code>—</code> de abertura não é a primeira linha do <code>SKILL.md</code>

Quando isso acontece, o Claude Code trata o arquivo inteiro (com os <code>—</code> juntos) como conteúdo da skill

Solução: apagar tudo que estiver acima e deixar o <code>—</code> na linha 1, sem espaço, sem título, sem linha em branco

Como prevenir: sempre criar o arquivo começando pelo frontmatter e escrever o corpo depois

O contexto está pesado e você não sabe por quê:

Causa: rule sem escopo

Uma rule sem <code>paths</code> é mecanicamente idêntica a colocar o conteúdo no <code>CLAUDE.md</code>: sempre carregada, sempre custando tokens

Solução: escopar com <code>paths</code> pra ela valer só nos arquivos que interessam, ou mover aquele conteúdo pra uma skill sob demanda

Como prevenir: antes de escrever a regra, pergunta "isso precisa valer em TODA conversa?"

Se a resposta for não, não é always-on

O hook simplesmente não dispara:

Causa: matcher usado em evento que não aceita matcher

Eles só se aplicam a <code>PreToolUse</code>, <code>PostToolUse</code> e <code>PermissionRequest</code>

Solução: tirar o matcher do evento que não suporta, ou mover a regra pra um dos três eventos que aceitam

Como prevenir: configurar pelo <code>/hooks</code> quando estiver em dúvida, em vez de escrever a configuração no braço

Você não sabe o que foi carregado na sessão:

Causa: achismo puro, o clássico "acho que ele leu o CLAUDE.md"

Solução: rodar <code>/context</code> e olhar a seção Memory files

Como prevenir: conferir isso sempre que mudar arquivo de memória, antes de sair debugando comportamento

Conclusão:

O método cabe em uma linha: uma repetição, uma peça, uso real, e só então crescer

Nada de montar skill, subagente, hook e plugin no mesmo sábado pra depois descobrir que você não usa nenhum

Seu próximo passo pra hoje é bem concreto: abre o projeto, escreve num rascunho a instrução que você mais redigita e cria UM <code>SKILL.md</code> em <code>.claude/skills</code>, com o <code>—</code> na primeira linha e uma <code>description</code> caprichada

Usa essa skill a semana inteira

Se ela sobreviver ao uso real, aí sim a gente conversa sobre subagente, hook e plugin…

até o próximo post! 🙂