O problema: onde vive o seu "rito"?
Se você usa o Claude Code por mais de uma semana, rapidamente bate numa fricção: existe um conjunto de instruções que você repete toda vez. "Rode os testes, se passarem faça commit com esse formato, se falharem abra plan mode." "Antes de revisar um PR, leia o CLAUDE.md, depois baixe o diff, depois compare com as convenções do time." "Ao escrever uma migration Supabase, cheque o RLS antes de aplicar."
Esses ritos são conhecimento seu — ou do seu time — que o Claude não sabe por padrão. Você tem duas formas oficiais de ensinar: slash commands e skills. Elas resolvem o mesmo problema por caminhos opostos. Este artigo explica a diferença, quando usar cada um, e como organizar os dois no seu .claude/ sem inchar o contexto do agente.
Se você ainda não tem o panorama geral do Claude Code, comece pelo guia definitivo do CLI da Anthropic e volte — a partir daqui assumo que você conhece os sete pilares do CLI.
Slash commands: invocação explícita
Um slash command é um arquivo markdown que você invoca pelo nome. .claude/commands/deploy.md vira /deploy. Quando você digita, o Claude Code injeta o conteúdo do arquivo no início do prompt, como se você tivesse colado aquele texto manualmente.
Anatomia mínima:
---
description: Deploy do blog para Cloudflare Pages
argument-hint: [branch opcional]
---
Rode os passos de deploy:
1. `cd blog && npm run build`
2. Se der erro, pare e me mostre
3. Se passar, rode `npm run deploy`
4. Cole o resultado do wrangler no final
Três características importantes:
- Explícito sempre. O comando só dispara quando você digita
/deploy. O modelo nunca invoca sozinho. - Aceita argumentos.
/deploy maindeixamaindisponível como variável dentro do prompt. - Versionável. Como é um arquivo no repositório, ele entra no git, vira parte do onboarding do time, e evolui junto com o projeto.
Slash commands são a ferramenta certa quando você quer controle total sobre quando o rito roda. Deploy, abertura de PR, geração de changelog, rotina de fim de sprint — qualquer coisa que tenha um momento claro de invocação.
Para um tutorial passo a passo do seu primeiro comando (incluindo argumentos, escopo pessoal vs projeto e debugging do arquivo), leia Criando Slash Commands customizados no Claude Code.
Skills: invocação implícita pelo modelo
Skills resolvem o outro lado: o modelo decide quando ativar. Uma skill vive em .claude/skills/<nome>/SKILL.md e começa com um bloco YAML descrevendo o gatilho:
---
name: supabase-migration
description: |
Use quando o usuário pedir para criar uma migration Supabase, adicionar
uma tabela, mudar um tipo de coluna ou alterar uma RLS policy. Cobre
naming, rollback plan e RLS-by-default.
---
# Escrevendo migrations Supabase
Ao criar um arquivo novo de migration, siga as regras:
...
A description é o gatilho. O Claude Code lê a descrição de todas as skills carregadas no início da sessão, e quando o seu prompt casa semanticamente com uma delas, o agente carrega o conteúdo do SKILL.md (e os arquivos anexos) no contexto automaticamente.
Por que isso importa: você não precisa lembrar de invocar. Se descrever "preciso adicionar uma coluna status na tabela de posts", a skill supabase-migration ativa sozinha. Se o seu colega novo entrar no repo e pedir a mesma coisa, a skill ativa pra ele também — sem ele saber que ela existe.
A regra de ouro para escrever uma skill: a description precisa ser um gatilho, não um resumo. Ruim: "Migrations do Supabase". Bom: "Use quando o usuário pedir para criar uma migration Supabase, adicionar uma tabela, mudar um tipo de coluna ou alterar uma RLS policy." O modelo precisa saber quando ativar, não o que a skill faz por dentro.
Slash commands vs skills: uma decisão, um critério
Há exatamente um critério para escolher entre os dois: quem decide quando o rito roda?
| Quem invoca | Ferramenta | |---|---| | Você, num momento específico | Slash command | | O modelo, ao detectar contexto | Skill |
Se a resposta for "sempre em um momento específico — depois do commit, antes do deploy, no fim do sprint": slash command. Se for "toda vez que alguém mexer nessa parte do código, ainda que não saiba que existe um padrão": skill.
Alguns casos híbridos cabem os dois — e é legítimo ter uma skill que também expõe um slash command como atalho para quando você quer invocar manualmente. Mas comece pelo critério; ele resolve 80% dos casos sem dor.
Uma confusão comum no começo é misturar skills com subagents. Skills dão instruções + conhecimento ao agente principal. Subagents são processos separados com contexto isolado. Cobri a diferença detalhada, com casos em que cada um é a escolha errada, em Skills vs Subagents: quando usar cada um — vale a leitura antes de inchar o seu .claude/skills/ desnecessariamente.
Escopo: pessoal, projeto, global
Tanto slash commands quanto skills aceitam três escopos:
- Projeto —
.claude/commands/e.claude/skills/no repo. Versionados, compartilhados com o time. - Pessoal —
~/.claude/commands/e~/.claude/skills/. Só seu, disponível em qualquer projeto. - Plugin — instalados via
claude plugin. Públicos, mantidos por terceiros.
A regra prática: o que é conhecimento do projeto vai no projeto (deploy, schema, convenções). O que é do seu jeito de trabalhar vai no pessoal (seu /commit favorito, sua skill de revisar código com olhar crítico). Resista à tentação de misturar — você vai querer compartilhar o primeiro e esconder o segundo.
O custo escondido: contexto e atenção
Skills têm um custo que slash commands não têm: toda skill ativa consome janela de contexto, mesmo quando o agente não vai usá-la. A description de cada skill fica no prompt inicial, e se a skill for ativada, o SKILL.md inteiro entra também.
Na prática, isso significa: não instale 40 skills "por via das dúvidas". Toda skill na pasta compete por atenção. Dez skills bem descritas geram melhor ativação do que cinquenta genéricas. Para um arsenal mínimo viável — as skills que eu instalo no dia um em qualquer projeto novo — veja 10 Skills essenciais para produtividade no Claude Code.
Slash commands não têm esse custo: eles só entram no contexto quando você digita o comando. Em termos de custo-benefício, prefira slash command se puder, use skill quando precisar da ativação automática.
Próximos passos
Comece criando um slash command do seu rito mais chato — o /commit com sua mensagem padrão, ou o /deploy. Depois transforme o seu padrão mais importante em skill e observe a ativação automática funcionar. O guia passo a passo está em Criando Slash Commands customizados, e quando você quiser subir um degrau e delegar exploração em paralelo, siga para Subagents no Claude Code. Se estiver planejando refatorações grandes com vários atalhos encadeados, ative o Plan Mode antes da execução — ele conversa muito bem com skills bem escritas.
