Skill ou comando personalizado no Claude Code: qual usar em cada caso?

Você montou seu /deploy em .claude/commands/, ele funciona redondo, e aí todo mundo começa a falar de skill

Bate aquela dúvida chata: o que a skill faz que o meu comando já não faz?

A boa notícia é que não é briga de sistema rival

As duas peças resolvem o mesmo problema (empacotar repetição pra você não digitar o mesmo prompt toda semana) e hoje elas moram debaixo do mesmo teto

Aqui eu quero te entregar critério de escolha, não teoria: onde cada uma vive, o que cada uma acrescenta e quando vale mover o que você já tem

O que mudou: os dois viraram um sistema só

Dava pra pensar em slash commands e Agent Skills como dois caminhos separados

Isso acabou: o changelog oficial do Claude Code registra na versão 2.1.3 o merge dos dois em um sistema unificado

Na prática isso significa duas coisas…

Qualquer skill pode ser invocada explicitamente com o prefixo /

E arquivos Markdown de prompt customizado passam a ser tratados como skills, que o Claude pode descobrir quando forem relevantes

Quer o exemplo mais direto? .claude/commands/deploy.md e .claude/skills/deploy/SKILL.md criam ambos o /deploy, e funcionam da mesma forma na invocação

Então a pergunta não é "qual sistema eu uso", é "quanta capacidade eu quero dar pra essa automação"

Se você quiser o mapa mais amplo, eu já destrinchei a diferença entre skills, comandos e subagentes em outro post

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Skill x comando personalizado: comparação lado a lado

Comentando linha por linha, rapidinho:

• Onde mora: a skill tem três escopos (pessoal, projeto e plugin), o que muda bastante a estratégia de quem trabalha em vários repositórios
• Estrutura: skill é pasta, não arquivo solto, e o SKILL.md precisa começar com o frontmatter contendo name e description
• Invocação: aqui mora a diferença que importa, a skill pode entrar em cena sem você chamar
• Arquivos de apoio: dá pra guardar o template e o exemplo do lado do prompt, em vez de colar tudo dentro dele
• Scripts: o Claude executa e só o resultado vira token, o que é MUITO bom pra rotina repetitiva
• Status: a CLI continua suportando os dois, mas .claude/commands/ é descrito como legado e a skill é a sucessora recomendada

Quando usar cada um: escolha pelo tipo de tarefa

Critério na mão, tarefa por tarefa

Tarefa com efeito colateral ou timing controlado:

Commit, deploy, mandar mensagem no Slack

Coisa que você quer disparar na hora que VOCÊ decidir, nunca porque o assunto apareceu na conversa

Pra isso existe o disable-model-invocation: true, que restringe a invocação só ao usuário, indicado justamente pra fluxos como /commit, /deploy ou /send-slack-message

<pre><code>— name: deploy description: Publica a aplicacao e acompanha o resultado do deploy disable-model-invocation: true —</code></pre>

Detalhe que evita dor de cabeça: em skills e comandos de plugin, campos booleanos como esse aceitam yes, no, on, off, 1 e 0 em qualquer caixa, além de true e false

Antes da v2.1.218 só true e false eram reconhecidos, então se você viu um exemplo antigo com yes e ele não pegou, era isso

Tarefa que o Claude deveria puxar sozinho:

Aqui é o oposto: você QUER que ele acione sem pedir

Revisar padrão de código, seguir um checklist de PR, aplicar a convenção da casa

E aí a description vira a peça mais importante do arquivo, porque na inicialização o agente pré carrega apenas name e description de cada skill instalada no system prompt, o suficiente pra saber quando cada uma deve ser usada

Descrição genérica é convite pra confusão, inclusive pra ter duas skills em conflito disputando o mesmo tipo de pedido

Tarefa com muita referência, template ou script:

Se o seu prompt está virando um monstro gigante com exemplo colado dentro, a pasta da skill resolve

A recomendação é manter o SKILL.md abaixo de 500 linhas e mover a referência detalhada pra arquivos separados

E os scripts do diretório podem ser executados sem carregar o conteúdo deles no contexto: o Claude roda e só a saída consome tokens

Tarefa que recebe entrada do usuário:

Nos comandos de barra os argumentos ficam disponíveis pelo placeholder $ARGUMENTS, e $N funciona como atalho para $ARGUMENTS[N] ($0 pro primeiro argumento, $1 pro segundo)

Tem também o encadeamento: a partir da v2.1.199, quando uma invocação de skill é seguida de outras (tipo /skill-a /skill-b faça XYZ), todas as skills nomeadas no início são carregadas e o texto final é passado como argumento pra cada uma

Ferramentas sem aprovação a cada uso:

O allowed-tools limita quais ferramentas o Claude pode usar enquanto a skill está ativa, e concede acesso a essas ferramentas sem aprovação a cada uso

<pre><code>allowed-tools: Bash(git add ) Bash(git commit ) Bash(git status *)</code></pre>

É o campo que transforma um fluxo cheio de "permitir? permitir? permitir?" em algo que roda liso, com guardrails (limites) no lugar

O que eu aprendi montando skills na prática

No vídeo abaixo eu instalo uma skill num projeto meu de gestão de produtos, um CRUD bem simples com tabela e cadastro de itens, só pra ver a coisa funcionando de verdade

Duas decisões que eu tomaria de novo

A primeira: instalei só no escopo do projeto, em vez de deixar aquilo valendo em todo canto

A instalação de plugin segue o formato /plugin install nome-do-plugin@nome-do-marketplace, com escopo de usuário, de projeto ou local

Só pra não embolar com a tabela lá de cima: aqueles três (pessoal, projeto e plugin) dizem onde a SKILL mora, esses aqui dizem onde o PLUGIN é instalado

Testar limpo em um projeto e só depois expandir é bem menos frustrante do que espalhar pra tudo e não saber o que mudou o comportamento

A segunda: instalação de plugin é um cenário diferente de editar texto de skill, e vale saber disso antes de perder tempo

Editar o texto de um SKILL.md que já existe recarrega sozinho, isso eu comento mais pra frente

Agora quando o assunto é plugin recém instalado, se o resumo da instalação pedir, roda /reload-plugins pra ativar

Já me ferrei achando que não tinha funcionado, quando na real o plugin só não tinha sido ativado ainda

Daí eu pedi uma coisa bem específica: adicionar um botão de exportar CSV na tabela, exportando só os produtos visíveis e filtrados

Vi na tela a skill sendo ativada, e esse é o sinal de que o negócio está de pé

Nesse pedido a IA não fez nenhuma pergunta, foi direto pra execução, porque a tarefa era simples e estava bem descrita

Mesmo assim o processo continuou valendo: entrega passo a passo do que foi alterado e relatório final das mudanças

E ela verificou o resultado antes de entregar, conferindo se as colunas exportadas batiam com as colunas visíveis da tabela

Cliquei no botão, abri o CSV no editor, e vieram exatamente os produtos que eu queria 🙂

Depois eu forcei o cenário contrário de propósito, com um prompt vago: "adiciona um sistema de autenticação no projeto"

Aí ela parou antes de implementar e listou as escolhas a alinhar, formas de autenticação, biblioteca, em vez de sair codando por conta própria

É isso que uma boa descrição de comportamento compra: a IA para de assumir coisa sozinha

E quando o pedido já está claro, não perguntar é bom, poupa tempo

Outro conforto do formato de pasta, e aqui é o tal cenário de edição: o Claude Code observa mudanças nos diretórios de skills quando você adiciona, edita ou remove uma skill em ~/.claude/skills/, no .claude/skills/ do projeto ou em um .claude/skills/ dentro de um diretório passado com --add-dir

A detecção ao vivo cobre apenas o texto do SKILL.md, então dá pra ir afinando a descrição e testando na sequência, sem reiniciar nada

No vídeo você vê a skill sendo ativada na tela, a mudança sendo feita de forma cirúrgica no projeto e a diferença entre o pedido claro e o pedido vago

Os problemas que me levaram a testar isso são os de sempre com IA gerando código: suposição silenciosa, over engineering, mexer em arquivo que não precisava e entregar sem testar

Vale acompanhar o repositório, porque ele está sendo atualizado com frequência e pode ganhar coisa nova

Já tenho comandos em .claude/commands/: preciso migrar?

Calma, nada quebra hoje

A CLI continua suportando os dois formatos

Mas .claude/commands/ é descrito como formato legado, e as skills são a sucessora recomendada, então a pergunta certa é "o que eu ganho movendo"

Você ganha a descoberta autônoma, os arquivos de apoio e scripts do lado do prompt, e continua com o mesmo /nome que você já tem no dedo

Migrar um comando é basicamente isso:

1. Crie o diretório com o nome que você quer no comando, por exemplo .claude/skills/deploy/

O erro comum deste passo: achar que o campo name define o comando

Em skill pessoal ou de projeto, name é apenas o rótulo exibido nas listagens, e o comando continua vindo do nome do diretório

2. Crie o SKILL.md dentro dele, começando pelo frontmatter YAML com name e description

3. Cole o conteúdo do seu comando antigo no corpo do arquivo

O erro comum deste passo: trazer o argument-hint junto do comando antigo

Usar argument-hint no SKILL.md gera erro de chave inesperada

No frontmatter você tem allowed-tools, compatibility, description, license, metadata e name, além do disable-model-invocation que a gente viu lá em cima

4. Decida se aquele fluxo pode ser acionado sozinho pelo Claude, e se não puder, adicione disable-model-invocation: true

E se a sua skill vier de um plugin, se liga: as skills do plugin ficam prefixadas pelo nome do plugin, tipo /commit-commands:commit

Nesse caso o name define o último segmento do comando, e o prefixo do plugin permanece

Veredito: qual peça resolve o seu caso

Sem ficar em cima do muro

Coisa nova você faz como skill

É o formato recomendado, aceita a mesma invocação por barra, e ainda te dá a pasta com arquivos de apoio e a chance de o Claude puxar aquilo sozinho

Comando personalizado fica pra inércia

O que já existe e funciona não precisa de mutirão de migração amanhã, mas eu não começaria nada novo por ali

Pra quem a skill NÃO serve? Pra quem quer só um atalho de texto e não pretende mexer em estrutura de pasta, aí o arquivo único ainda é mais rápido de escrever

E o comando não serve pra quem quer automação com script, referência separada e ativação automática, isso o formato legado não entrega

No fim, a decisão de verdade nem é skill contra comando

É você responder uma pergunta só: eu quero que o Claude acione isso sozinho, ou não?

Se a resposta for sim, capriche na description

Se for não, disable-model-invocation: true e dorme tranquilo

Conclusão

Próximo passo, bem concreto: pega o comando que você mais usa hoje

Recria ele como diretório com SKILL.md e frontmatter com name e description

Decide se ele leva disable-model-invocation ou não

Testa no escopo do projeto antes de jogar pro pessoal, que é onde a bagunça costuma nascer

E não pense nisso como conhecimento preso ao terminal: Agent Skills são suportadas hoje no Claude.ai, no Claude Code, no Claude Agent SDK e na Claude Developer Platform, então o que você aprender montando uma skill aqui viaja pros outros lugares 😀

Dá uma olhada no vídeo pra ver o comportamento acontecendo na tela, é bem diferente de ler sobre

E me conta depois qual comando você migrou primeiro, tô curioso…

até o próximo post!