Skills e subagentes no Claude Code
VPS Agêntica
Uma VPS para os seus agentes trabalharem dia e noite
Instale o SetupVibe Desktop numa VPS da StayCloud em São Paulo, com acesso root e disco NVMe. Deixe Claude Code, Codex e OpenCode rodando no tmux ou no Herdr e feche o notebook sem interromper nada.
Link de parceiro da Promovaweb.
Black Friday até 30/11
30%off
nos 2 primeiros meses do plano mensal da VPS
- Backup diário grátis para sempre
- Servidores em São Paulo no datacenter da Ascenty
- Datacenter Tier III manutenção sem parada
- Acesso root com disco SSD NVMe
- Réplica do backup em Ashburn, nos EUA
Uma skill é uma pasta com um arquivo SKILL.md que ensina um procedimento ao Claude Code e só ocupa espaço na janela de contexto quando é usada. Um subagente é um assistente especializado que recebe uma parte da tarefa, trabalha com janela de contexto, ferramentas e permissões próprias e devolve só o resumo do que fez.
Sumário da página
O procedimento que você cola toda semana
Toda sexta você cola no chat o mesmo roteiro para preparar uma release: conferir o CHANGELOG, subir a versão no package.json, rodar os testes e montar a nota. A documentação da Anthropic usa exatamente essa situação para indicar uma skill. Ela também aponta outro sinal: um trecho do CLAUDE.md que virou passo a passo no lugar de um fato sobre o projeto.
A diferença está no custo. O CLAUDE.md entra em toda sessão, ocupando janela de contexto o tempo todo. Uma skill aparece para o modelo só como nome e descrição no começo da sessão. O corpo completo carrega quando a skill é chamada, por você ou pelo próprio agente. Material de referência longo dentro de uma skill quase não pesa até ser necessário.
Como uma skill é chamada
Uma skill é uma pasta com o arquivo SKILL.md, que traz um frontmatter com nome e descrição e as instruções logo abaixo. A pasta pode ter arquivos de apoio, como scripts, modelos e referências. Você chama a skill digitando / seguido do nome, como /release. O agente também chama a skill sozinho quando a descrição combina com a tarefa que você descreveu.
Dois campos do frontmatter controlam a origem da chamada. Com disable-model-invocation: true, só você dispara a skill. A documentação recomenda essa opção para fluxos com efeito colateral, como deploy, commit ou envio de mensagem, porque o agente não deve decidir publicar só porque o código parece pronto. Com user-invocable: false, só o agente usa a skill, o que serve para conhecimento de fundo, como o funcionamento de um sistema legado.
O lugar da pasta define o alcance da skill. Em ~/.claude/skills/<nome>/SKILL.md, ela vale em todos os seus projetos. Em .claude/skills/<nome>/SKILL.md, vale para o repositório e chega aos colegas pelo Git. Plugins e managed settings distribuem skills para a organização inteira. Os antigos comandos personalizados em .claude/commands/ continuam funcionando, mas a documentação recomenda skills para trabalho novo, porque elas aceitam arquivos de apoio.
As skills do Claude Code seguem o padrão aberto Agent Skills, usado por outras ferramentas de IA. Elas acrescentam recursos próprios, como controle de invocação, execução dentro de um subagente e injeção de informação dinâmica. O Claude Code também traz skills embutidas, entre elas /code-review, /debug, /batch e /loop.
Subagentes trabalham numa janela separada
Uma busca grande pelo código devolve dezenas de resultados, trechos de arquivo e logs que você não vai consultar de novo. Se tudo isso entra na conversa principal, a janela de contexto enche e a compactação chega mais cedo. O subagente resolve esse problema: ele faz a busca na própria janela e devolve só o resumo.
Conversa principal
O agente identifica uma parte da tarefa que combina com a descrição de um subagente.
Subagente
Recebe a tarefa com prompt de sistema, ferramentas e permissões próprios.
Trabalho isolado
Lê arquivos, busca e roda comandos na própria janela de contexto.
Resumo
Devolve à conversa principal só o que encontrou ou fez.
A documentação lista os ganhos. A conversa principal fica limpa. Você restringe as ferramentas que cada subagente usa. A mesma configuração serve em vários projetos. Um prompt focado especializa o comportamento. O custo cai quando uma tarefa simples vai para um modelo mais rápido, como o Haiku. As chamadas de um subagente entram no mesmo limite de uso da conversa principal.
O Claude Code traz subagentes embutidos. O Explore é rápido e só lê: busca e analisa o código sem editar nada. O Plan pesquisa o projeto durante o modo de planejamento, para a conversa principal continuar só de leitura. Os dois começam sem o seu CLAUDE.md, para a pesquisa sair rápida e barata.
Como criar um subagente
Um subagente personalizado é um arquivo Markdown com frontmatter e o prompt de sistema no corpo. O frontmatter traz name, description, a lista de ferramentas em tools e o modelo em model. Um revisor de código, por exemplo, pode receber só as ferramentas de leitura e busca. O comando /agents abre um assistente para criar e editar esses arquivos. O próprio agente também escreve um quando você solicita.
O lugar do arquivo define o alcance. Em .claude/agents/, o subagente vale para o projeto e vai para o Git. Em ~/.claude/agents/, vale em todos os seus projetos. Plugins e managed settings também distribuem subagentes. Quando dois têm o mesmo nome, vence o de maior prioridade, com os managed settings no topo.
O Claude Code escolhe o subagente pela descrição. Por isso a descrição precisa ser curta e clara: as descrições de todos os subagentes ocupam janela de contexto. O cliente mostra um aviso quando a soma passa de 15 mil tokens. Detalhe longo vai para o prompt de sistema, que só carrega quando o subagente roda. Um subagente também pode ter a própria auto memory, separada da conversa principal.
Onde termina cada recurso
Skill e subagente resolvem problemas diferentes. A skill ensina um procedimento e roda dentro da conversa atual, salvo quando configurada para rodar num subagente. O subagente separa um trabalho para não poluir a conversa. Os dois funcionam dentro de uma única sessão. Para várias sessões completas em paralelo, a documentação aponta outros recursos, como os agentes em segundo plano e os grupos de agentes coordenados. Para comandos que precisam rodar em todo evento configurado, qualquer que seja a escolha do modelo, o caminho são os hooks, assunto do próximo hub.