Skill ou agente do awesome-claude-code: qual dos dois resolve a sua tarefa?

Fala aí, beleza? Tu abre o awesome-claude-code atrás de UMA coisa e sai de lá com um monte de categoria na cara: skills, agents, status lines, developer tooling, plugins

Aí bate a dúvida clássica, e ela quase sempre é entre as duas primeiras: skill ou agent, qual resolve o meu problema?

E a resposta não é gosto pessoal, é propósito. Skill e subagente resolvem coisas diferentes, e escolher errado cobra o preço em dois lugares que doem: contexto e tempo

O pior cenário nem é escolher errado, é escolher os dois. Tu cria a skill, cria o subagente pra mesma tarefa, e depois fica quebrando a cabeça pra entender por que a orientação simplesmente não aparece no resultado

Bora separar isso de vez 🙂

O que é o awesome-claude-code e por que ele separa skills de agents

O awesome-claude-code é um repositório mantido pelo usuário do GitHub hesreallyhim

A própria descrição dele diz o que é: uma coleção selecionada de recursos para o Claude Code, citando skills, agents, status lines, developer tooling e plugins

Repara numa coisa importante: a separação entre skill e agent não é uma escolha estética da curadoria

Ela existe porque o produto separa mesmo. São dois mecanismos distintos do Claude Code, com anatomia diferente, forma de acionamento diferente e efeito diferente no seu contexto

Então o repositório só está espelhando uma divisão que já existe na ferramenta. Entendendo a divisão, a coleção para de parecer um monte de link solto e vira um cardápio com categorias bem definidas

Formação Recomendada

Formação Claude Code

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

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

O que é uma skill do Claude Code

Skill é conhecimento empacotado pro Claude usar na conversa que já está rolando

Na prática, uma skill é um diretório que contém um arquivo SKILL.md com instruções, scripts e recursos

Dentro do SKILL.md vai um frontmatter YAML entre marcadores ---, com campos de configuração:

---
name: minha-skill
description: Explica QUANDO o Claude deve usar esta skill
disable-model-invocation: false
allowed-tools: Read, Grep
---

Aqui embaixo vão as instruções que o Claude vai seguir

O campo mais importante aí é a description. É por ela que o Claude decide se aquela skill serve pro pedido que tu fez

Onde a skill fica:

Skills pessoais moram em ~/.claude/skills/

Skills de projeto moram em .claude/skills/, com o mesmo SKILL.md dentro

E tem um detalhe que economiza um puta tempo: o Claude Code detecta adição, edição ou remoção de skill dentro da sessão atual, sem reiniciar nada. Tu salva o arquivo e segue o baile

Como ela é acionada?

Skill é model-invoked. Ou seja: quem escolhe é o modelo, comparando o teu pedido com a description de cada skill

No início da sessão só o nome e a description de cada skill são carregados. O corpo da skill só entra quando ela é usada, num esquema de progressive disclosure

Isso muda o cálculo de custo por completo. Material de referência longo quase não pesa no contexto até o momento em que a tarefa exige ele

Mesmo assim a documentação recomenda manter o SKILL.md abaixo de 500 linhas, e quebrar a referência em arquivos separados quando passar disso

Outra coisa massa: as skills seguem o padrão aberto Agent Skills, que funciona em outras ferramentas de IA. Então o que tu escreve não fica preso num lugar só

O que é um subagente do Claude Code

Subagente não é conhecimento, é delegação

A anatomia é mais simples que a da skill: um arquivo Markdown com frontmatter YAML, e o corpo do arquivo vira o system prompt do subagente

O Claude Code observa dois diretórios pra isso: ~/.claude/agents/ e .claude/agents/

A alteração é detectada em segundos, e a próxima delegação já usa a definição atualizada

Mas ó, isso vale pro caso comum. Existem duas situações em que esses diretórios NÃO são observados, e eu detalho elas mais pra frente no post

Cuidado com o /agents:

Desde a v2.1.198, o comando /agents deixou de abrir o assistente interativo de criação

Hoje ele só imprime um aviso apontando os locais dos arquivos de subagente. Pra criar ou editar, tu pede pro Claude ou edita o arquivo direto

Se tu viu um tutorial antigo mandando abrir o wizard, era isso que existia antes. Tome cuidado pra não ficar procurando uma tela que não abre mais

O que realmente muda num subagente

Cada subagente começa com uma janela de contexto própria e isolada

Ele não vê o histórico da conversa, não vê as skills já invocadas e não vê os arquivos que já foram lidos

Duas coisas furam esse isolamento: o fork, que herda a conversa do pai, e o campo skills no frontmatter do subagente, que injeta as skills nomeadas no contexto dele já na inicialização (volto nisso no erro clássico lá embaixo)

E tem um detalhe que pega muita gente: a janela de contexto do subagente é dimensionada pelo modelo DELE, não pelo modelo do agente principal. Delegar pra um modelo com janela menor entrega ao subagente a janela menor

Do lado bom, o isolamento abre duas portas ótimas:

• conjunto próprio de ferramentas permitidas, o que reduz o risco de ação indesejada
• controle de custo, roteando tarefas pra modelos mais rápidos e baratos, tipo o Haiku

É como contratar alguém pra ler o relatório inteiro e te trazer só o resumo: tu não precisa carregar as 300 páginas na tua mesa

Skill x subagente: comparação linha a linha

Se tu quiser um mapa rápido da diferença entre skills, comandos e subagentes, a tabela abaixo já resolve o essencial dos dois recursos que mais geram dúvida na hora de garimpar a coleção:

Qual escolher conforme o tipo de tarefa

A orientação oficial é curta e resolve quase todo caso: skills acrescentam conhecimento e fluxos à conversa atual, subagentes rodam em contexto separado com ferramentas próprias

Use skill pra orientação e padrões. Use subagente quando precisar de isolamento ou de acesso diferente a ferramentas

Traduzindo pro teu dia a dia:

Vai de skill quando a tarefa é curta e repetitiva:

• padrão de código que a equipe segue
• convenção de mensagem de commit
• formato de resposta que tu quer sempre igual
• checklist que tu repete toda semana

Tudo isso é conhecimento que precisa estar disponível na conversa atual, e que custa quase nada até ser chamado. Vale pra código e vale fora dele também: dá pra pensar em skills para tarefas de marketing exatamente com a mesma lógica

Vai de subagente quando o trabalho suja o contexto:

• auditoria que varre o repositório inteiro
• busca extensa em dezenas de arquivos
• qualquer tarefa que enche a janela e da qual tu só quer o resumo final

O critério oficial pro subagente compensar é justamente esse: quando é preciso isolar contexto ou a janela está enchendo. O subagente lê dezenas de arquivos ou faz buscas extensas, e a conversa principal recebe só um resumo

Tem mais dois casos que empurram pro subagente na hora: quando a tarefa precisa de permissão de ferramenta REDUZIDA, e quando tu quer rodar aquilo num modelo mais barato

O gatilho final, pra guardar: se o problema é conhecimento, é skill. Se o problema é contexto ou acesso a ferramenta, é subagente

O erro de empilhar skill e subagente no mesmo problema

Agora o erro que aparece quando a pessoa resolve fazer os dois 😀

Sintoma: tu cria uma skill com o padrão que quer, cria um subagente pra mesma tarefa, dispara a delegação e a orientação da skill simplesmente não aparece no trabalho do subagente

Causa: o subagente começa com contexto isolado. Ele não herda o histórico e não herda as skills já invocadas na conversa. Não é bug, é o desenho do recurso

Solução: existe um campo próprio pra isso. O campo skills no frontmatter do subagente recebe uma lista de nomes de skills, que são injetadas no contexto dele na inicialização

---
name: auditor
skills:
  - padrao-de-codigo
  - convencao-de-commit
---

Você audita o repositório e devolve só um resumo dos problemas encontrados

Como prevenir: escolha um dono pra tarefa ANTES de criar o segundo recurso

Se a resposta é "eu quero que ele siga um padrão", para na skill. Se a resposta é "eu quero que ele leia meio repositório sem entupir minha conversa", vai de subagente e só carrega skill nomeada se for realmente necessário

E lembra do detalhe da janela: delegar pra um modelo com janela menor entrega ao subagente a janela menor. Não adianta empurrar um trabalho gigante pra um modelo apertado e esperar milagre

Duas armadilhas operacionais:

O Claude Code NÃO observa .claude/agents/ dentro de diretórios adicionados com --add-dir ou /add-dir. Nesse caso é preciso reiniciar pra carregar a mudança

E sessões iniciadas com --disable-slash-commands também não observam esses diretórios

Já vi gente jurando que o subagente "não atualiza" quando na verdade o diretório nem estava sendo observado…

O que a prática mostra sobre desperdício de contexto

No vídeo abaixo eu mostro na prática por que essa decisão é, no fundo, uma decisão sobre quanto contexto tu deixa entrar na conversa principal

Lá eu testei o FastContext, uma skill de busca, instalando no Windows via WSL, e funcionou

Antes de plugar no agente, rodei ele direto, fora do fluxo, só pra confirmar que a busca estava respondendo e devolvendo a saída final

E é aí que a ficha cai: a saída devolvida é enxuta. Caminho do arquivo mais o intervalo de linhas que interessa, em vez de todo o histórico de navegação até chegar lá

A divisão de papéis fica escancarada: o agente principal delega uma pergunta em linguagem natural, e o segundo agente explora o repositório em contexto separado, devolvendo só o que importa

Outro ponto que eu destaco: esse agente de busca não executa nada. Ele trabalha com leitura de arquivo, glob pra descobrir caminhos e grep pra buscar por expressão regular. Ferramenta reduzida, exatamente como o subagente permite

Comparei o mesmo pedido com e sem o FastContext e obtive respostas mais rápidas em testes isolados. Pra não sobrar aquela reclamação de comparação injusta, refiz com o prompt IDÊNTICO, mudando só o trecho que pedia pra usar o FastContext na busca

A diferença que eu comentei foi de cerca de 40 e poucos segundos a menos no teste com a skill

E ó, isso é um teste isolado meu, num prompt específico. Não é régua universal pra decidir skill contra subagente, é ilustração de onde o desperdício mora

Mais duas coisas que eu aprendi apanhando ali:

• a ativação implícita da skill não é garantida. Eu prefiro ser explícito, chamando pelo slash command ou citando o nome da skill no prompt
• dá pra criar uma regra no projeto instruindo o agente a usar aquela busca sempre que precisar procurar informação no código

Ah, e um aviso honesto: a skill exige um setup de configuração antes de rodar. Não é instalar e sair usando

Minha recomendação lá continua valendo aqui: aponta o agente de busca pra um modelo mais barato, um modelo menor da assinatura que tu já tem, um gratuito ou um local

Veredito: quando cada um vence

Sem meio-termo covarde, vamos ao veredito 🙂

Skill vence em tarefa repetitiva, curta e de padrão. Ela custa quase nada de contexto até ser usada, porque só nome e description entram no início da sessão, e ainda é acionada sozinha quando o pedido bate com a description. Pra convenção, checklist e formato de saída, não tem discussão

Subagente vence quando o trabalho é longo, delegado e sujo de contexto. Varredura de repositório, busca extensa, análise que lê dezenas de arquivos: tudo isso morre na janela isolada dele e volta pra ti como resumo. E de quebra tu limita as ferramentas e escolhe um modelo mais barato

Os dois juntos só fazem sentido num caso: quando o subagente precisa seguir um padrão específico e tu carrega uma skill nomeada pelo campo skills do frontmatter dele. Aí é composição de verdade

Fora disso é duplicação. Se a skill sozinha já resolve, o subagente só adiciona uma camada que não vê nada do que já aconteceu na conversa

Conclusão

O critério cabe numa frase: skill resolve falta de conhecimento na conversa atual, subagente resolve falta de contexto e de isolamento de ferramenta

Guardando isso, o awesome-claude-code deixa de ser uma pilha de link confuso e vira um cardápio em que tu sabe abrir a categoria certa

Próximo passo bem concreto: abre a coleção, escolhe UM item da categoria certa pra aquela tarefa que tu mais repete e roda por uma semana inteira antes de criar o segundo recurso

Se no fim da semana a orientação estiver aparecendo e a tua janela não estiver enchendo, tu acertou a categoria de primeira 😀

até o próximo post!