Skills, comandos e subagentes no Claude Code: qual é a diferença e quando usar cada um

Skill, comando, subagente e plugin no Claude Code parecem a mesma coisa, mas não são, e misturar os quatro é o jeito mais fácil de perder tempo

Cada um resolve um problema diferente

A skill é acionada sozinha pela IA, o comando você dispara na mão, o subagente isola a tarefa num contexto separado e o plugin junta tudo num pacote só

Neste post eu explico os quatro pra você decidir qual usar em cada situação sem confundir os conceitos, beleza? Skill, comando e subagente são as peças que dá pra comparar lado a lado, e o plugin é o pacote que junta elas. Bora separar isso 🙂

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

Antes de destrinchar um por um, se liga na visão geral

Essa tabela cruza os critérios que de fato decidem a escolha: como cada recurso é acionado, onde o arquivo mora, o formato e o que acontece com o contexto

Guarda essa tabela no canto do olho, porque cada linha vira uma seção agora

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

Skills no Claude Code: o que são e quando usar

Uma skill no Claude Code é uma pasta contendo um arquivo SKILL.md

Esse arquivo tem um frontmatter YAML com dois campos, name e description, e no corpo as instruções em markdown do que fazer quando a skill entra em cena

O pulo do gato está na description: é ela que Claude compara com o seu pedido pra decidir se aciona a skill ou não

E por que isso economiza contexto? Porque o carregamento é progressivo

Na inicialização, Claude lê só o name e a description de cada skill, o que custa pouquíssimos tokens

Quando a tarefa casa com a descrição, aí sim ele lê o SKILL.md inteiro via bash, e se esse arquivo referenciar outros arquivos, ele lê esses também

É como um índice de livro: você não decora o livro todo, só olha o índice e vai no capítulo certo quando precisa

Outra coisa massa: dá pra adicionar, editar ou remover uma skill em ~/.claude/skills/, no .claude/skills/ do projeto ou num diretório passado com --add-dir e isso passa a valer dentro da própria sessão, sem reiniciar

Sobre onde guardar, a regra é simples

• ~/.claude/skills/ é a skill pessoal, vale em qualquer projeto seu
• .claude/skills/ dentro do repositório é a skill do projeto, versionada junto com o código

São baseadas em arquivo, sem upload por API

Quando escolher skill? Quando você quer um comportamento que Claude deve acionar sozinho toda vez que a tarefa combinar, sem você ter que lembrar de pedir

Se você quer ir a fundo em como criar, usar e migrar skills, tem post dedicado pra isso aqui no blog

Comandos de barra personalizados: quando você quer acionar na mão

O comando de barra é o oposto da skill no acionamento

Aqui você dispara, digitando /nomedocomando na sessão

O mecanismo é direto: um slash command é um arquivo markdown, o nome do arquivo vira o nome do comando e o corpo do arquivo vira o prompt injetado na sessão

Claude Code lê de dois lugares:

• .claude/commands/ é o comando do projeto, versionado no repo
• ~/.claude/commands/ é o pessoal, global na sua máquina

E não é só texto fixo, dá pra parametrizar

$ARGUMENTS captura tudo que você digitou depois do comando como uma string única

Já $1, $2, $3 dividem a entrada em posições, então você monta comandos que recebem argumentos separados

O frontmatter YAML do arquivo aceita campos opcionais pra ajustar o comportamento: description, argument-hint, allowed-tools, model e disable-model-invocation

Quando escolher comando? Quando você tem um atalho repetível que VOCÊ quer disparar na hora que decidir, e não deixar a IA adivinhar sozinha

Pensa naquele prompt gigante que você cola toda semana: vira um /comando e acabou o copia e cola

Subagentes: quando isolar a tarefa em contexto próprio

O subagente é outra pegada: ele é um assistente especializado que trabalha por fora do seu contexto principal

Cada subagente tem system prompt próprio, acesso a ferramentas próprio e uma janela de contexto separada

Quando ele termina, devolve só o resultado ao agente principal, sem despejar todo o trabalho intermediário no seu contexto

É como contratar um especialista pra uma tarefa: ele faz a bagunça na mesa dele, e te entrega só a resposta limpa

A definição também vive em arquivo markdown com frontmatter YAML, em ~/.claude/agents/ (pessoal) ou .claude/agents/ (do projeto)

E igual às skills, Claude Code observa essas pastas e reconhece um agente novo ou editado em poucos segundos, sem reinício

Quando escolher subagente? Quando a tarefa é especializada ou pesada e você não quer que o vai e volta dela suje o contexto principal

Exemplo clássico: uma varredura grande de código onde só o resumo interessa, não a pilha de arquivos que ele leu no caminho

E os plugins? O pacote que junta skills, comandos e subagentes

Até aqui os três recursos são peças soltas

O plugin é o que amarra tudo

Um plugin é um pacote que combina skills, comandos, subagentes (agentes), hooks e servidores MCP num conjunto só

Ele vem com os metadados que descrevem esse conjunto, empacotado pra você pegar tudo de uma vez em vez de montar peça por peça

Então pensa assim: skill, comando e subagente são as ferramentas, e o plugin é a caixa de ferramentas que alguém montou e distribuiu pra você usar de uma vez

Se você mantém um padrão de trabalho que envolve várias dessas peças, empacotar num plugin é como você compartilha isso com o time ou com a comunidade

Na prática: skills da Vercel rodando no Claude Code

Teoria é teoria, mas eu quis ver a skill acionando de verdade

No vídeo abaixo eu mostro uma skill de frontend/design rodando dentro de um projeto no Claude Code, e dá pra sentir na prática o conceito de skill acionada pela IA

Eu instalei a skill usando um comando npx obtido no próprio site de skills

Durante a instalação deu pra escolher pra quais editores/IDEs a skill ficaria disponível, e eu selecionei as que mais uso, entre elas o Claude Code

Teve também a escolha entre instalar só no projeto atual ou de forma global, e aqui vale pensar no trade-off: global fica acessível em qualquer projeto, no projeto fica restrita àquele

Nem toda skill compensa botar global se você só vai usar num projeto, então dá pra segurar a mão

Optei pela instalação via symlink em vez de baixar o arquivo da skill pra máquina, e mostrei que dava pra manter só a pasta usada pelo Claude Code

Um detalhe que me ensinou algo: quando pedi pra IA usar a skill, ela primeiro procurou de forma global e não encontrou, depois achou no local

Concluí que ajuda mencionar explicitamente no prompt a skill que você quer, pra IA achar mais rápido

Pra testar de verdade eu criei uma landing page de página única usando a skill de design, e gerei também uma versão SEM a skill, pra comparar

E a diferença apareceu: a versão com a skill ficou mais polida, com ícones mais profissionais, paleta de cores bem escolhida e seguindo padrões de design

A versão sem a skill tinha a mesma estrutura, mas ficou menos polida, com ícones genéricos, emojis e cores mais brutas

Mesmo prompt, resultados bem diferentes, só pela skill certa entrar em campo

Segundo a demonstração, ainda deu pra publicar e hospedar o projeto gerado em menos de um minuto

Vi no repositório outras skills também, incluindo uma de best practices de React

Minha conclusão no vídeo é que usar a skill certa gera um resultado bem mais polido com um único prompt, e vale a pena garimpar o repositório atrás das skills que você quer

Se quiser um filtro do que instalar, montei uma lista das skills que valem a pena no Claude Code separada aqui no blog

Qual usar em cada situação

Cortando a conversa fiada, a regra de decisão é curta

• Comportamento que a IA deve acionar sozinha quando a tarefa combina? Skill
• Atalho repetível que VOCÊ dispara na hora? Comando de barra
• Trabalho especializado ou pesado que precisa de contexto isolado? Subagente
• Distribuir o conjunto todo de uma vez? Plugin

Não existe o melhor recurso no vácuo, existe o certo pro que você precisa naquele momento

O erro comum é forçar um comando pra algo que devia ser skill (aí você fica dependendo de lembrar de digitar) ou jogar tudo no contexto principal quando um subagente resolveria sem sujar a sessão

Conclusão

Skill, comando, subagente e plugin não competem entre si, eles se completam

Dá pra ter uma skill que a IA aciona sozinha, um comando que você dispara na mão, um subagente pra tarefa pesada e um plugin empacotando o que faz sentido compartilhar, tudo no mesmo projeto

O próximo passo é simples: começa pequeno, cria uma skill ou um comando básico dentro do .claude/ do seu projeto e sente na prática qual dos dois acionamentos combina mais com o seu jeito de trabalhar

Depois é só ir montando o resto conforme a necessidade aparece

até o próximo post! 🙂