Claude Code lento: como escolher Skills, subagentes, MCP e plugins

Porque é que «Encher o Claude Code» se tornou o maior problema em 2026?#

Nem sequer a documentação oficial tinha uma resposta abrangente já preparada para «quando se deve escolher cada opção?».

A experiência de um mês descrita neste artigo inclui os quatro mecanismos em projetos funcionais: um conjunto de subagentes para uma tarefa complexa, um pequeno grupo de skills para procedimentos recorrentes, alguns servidores MCP para dados em tempo real e uma seleção de alguns entre cerca de duas dezenas de plugins. Este guia reúne o exemplo numa matriz de seleção com uma árvore de decisão pronta a usar, citações da Anthropic e sete antipadrões que tornam o Claude inutilizável.

Em que difere uma skill de um subagente, do MCP e de um plugin? Uma tabela#

Matriz de seleção:

Uma analogia simples para um empresário: imagine-se como CEO de uma empresa com dez pessoas:

• CLAUDE.md — o estatuto da empresa. Está sempre afixado na parede; todos o leem; ninguém discute.
• Skill — um procedimento interno. «Como fazemos revisões», «como escrevemos notas de lançamento», «como aceitamos pagamentos».
• Subagent — um especialista com um gabinete separado e uma lista restrita de permissões. Dê-lhe as chaves de tudo e terá um segundo CEO, não um funcionário.
• Servidor MCP — os sistemas da empresa: CRM, banco, armazém. Isto não é conhecimento; é uma ligação.
• Plugin — uma solução pronta a usar, comprada numa loja. Um pacote de procedimentos, especialistas e integrações, tudo na mesma caixa.

Quando perceber que são quatro camadas de um sistema, em vez de quatro concorrentes, a pergunta «qual é melhor?» desaparece. A pergunta que fica é «o que vai para onde?»

O que é uma skill no Claude Code e quando deve instalar uma?#

Definição oficial da Anthropic:

Uma skill tem três níveis:

1. Metadados. São sempre carregados no arranque da sessão: o nome e a descrição do frontmatter. Uma skill utiliza cerca de 100 tokens no arranque.
2. Instruções. São carregadas apenas quando o Claude deteta um pedido que as aciona. Até 5,000 tokens — o corpo do SKILL.md.
3. Recursos. São carregados apenas quando as instruções o pedem explicitamente. Ficheiros incluídos no pacote, scripts em scripts/, materiais de referência em references/. Os scripts são executados através de bash; o próprio código não entra no contexto.

A Anthropic chama a este princípio divulgação progressiva:

E, no mesmo artigo, uma metáfora que explica a ideia melhor do que qualquer outra:

Quando usar uma skill:

• Um procedimento padrão que repete vezes sem conta: revisões de PR, notas de lançamento, revisão de código de acordo com o seu guia de estilo.
• Quando uma secção de CLAUDE.md deixa de ser um facto e passa a ser um procedimento, começa a crescer e interfere com tudo o resto.
• Quando quer que a mesma instrução seja seguida de forma consistente em projetos diferentes.

Uma fórmula prática: se fizer algo mais do que algumas vezes, passe essa tarefa para o sistema. Da primeira vez, use um prompt manual. Da segunda, é um potencial candidato a skill.

Quando NÃO usar uma skill:

• Se a tarefa exigir dados em tempo real (base de dados, API, pesquisa, dados atuais da bolsa). Isso é MCP, não uma skill. Uma skill que tente «obter o preço atual» vai alucinar.
• Se a tarefa exigir contexto isolado. Isso é um subagente.
• Se precisar de uma verificação imposta («bloquear um commit que contenha .env»), use um hook no percurso de commit abrangido, em vez de depender de uma skill. Reveja e teste a cobertura real: um hook não restringe todas as formas de ler, copiar ou publicar o ficheiro.

Limites a conhecer de antemão:

• Nome da skill: até 64 caracteres, apenas letras minúsculas, algarismos e hífenes. As palavras anthropic e claude estão reservadas.
• Descrição: até 1,024 caracteres. A combinação de description + when_to_use é truncada aos 1,536 caracteres na lista.
• Corpo do SKILL.md: recomenda-se um máximo de 500 linhas. Passe o que exceder para references/ e scripts/.
• Durante a compactação automática do contexto (compactação automática), os primeiros 5,000 tokens de cada skill ativa são anexados novamente. O orçamento total para todas as skills é de 25,000.

O que é um subagente e porque existem 5 níveis de aninhamento?#

Da documentação oficial:

O Claude Code tem três subagentes integrados que já utiliza sem saber:

Em 10 de junho de 2026, a Anthropic lançou o Claude Code v2.1.172 e removeu uma restrição que existia desde o lançamento dos subagentes: os agentes filhos podem agora criar os seus próprios subagentes até 5 níveis de profundidade.

O número 5 é um limite máximo de segurança, não um objetivo de otimização.

Uma explicação detalhada das funcionalidades, com modelos YAML para orquestradores, está no guia sobre subagentes aninhados.

Quando usar um subagente:

• Uma passagem exploratória pelo código ou pelos registos, após a qual só precisa de uma conclusão breve.
• Tarefas em paralelo que podem correr lado a lado.
• Delegação por especialização: backend / frontend / testes / revisão — cada um trata de uma funcionalidade.
• Controlo de custos: um subagente Haiku em vez de Sonnet ou Opus. Isto reduz a fatura 5–7 vezes.

Quando NÃO usar um subagente:

• Uma tarefa trivial feita uma única vez ou uma chamada simples a uma ferramenta. Um subagente tem um custo de arranque.
• Quando as tarefas precisam de partilhar estado. Os subagentes não conseguem ver o contexto uns dos outros; o trabalho relacionado deve ficar na conversa principal.

O principal antipadrão:

Dar Opus e todas as ferramentas a um subagente só faz dele outra sessão principal. Se a lista de ferramentas corresponder à do agente principal, o subagente não está devidamente restringido.

Por outras palavras, um subagente com as mesmas permissões do agente principal é apenas um segundo CEO. Sem utilidade e dispendioso.

O que é um servidor MCP e quando deve ligá-lo ao Claude Code?#

A definição oficial:

O que o MCP permite realmente fazer na prática:

• Ligar o Claude ao Google Calendar e ao Notion para obter um assistente pessoal.
• Ligar ao Figma para que o Claude gere um projeto web pronto a usar a partir de um design.
• Ligar um chatbot empresarial a várias bases de dados ao mesmo tempo.
• Ligar ao Blender e a uma impressora 3D para criar modelos e imprimi-los de imediato.

Os servidores MCP mais conhecidos que as pessoas instalam primeiro:

As ligações e os comandos de instalação estão reunidos no catálogo MCP.

Quando usar MCP:

• Qualquer ligação a dados ou ações externas: «obter linhas da base de dados», «ler tickets do Jira», «publicar no Slack».
• Quando o mesmo serviço é necessário em vários projetos ou agentes, é mais fácil manter um único servidor centralizado.

Quando NÃO usar MCP:

• Conhecimento estático ou um procedimento. Isso é uma skill, não MCP. «Instruções sobre como fazer uma revisão de código» é uma skill. «Ler o PR mais recente do GitHub e revê-lo» é MCP.
• Um comando CLI usado uma única vez. É mais simples usar Bash do que configurar um servidor.
• Quando quiser criar MCP «só para ter uma arquitetura correta». Isso é estética, não uma tarefa.

A principal armadilha do MCP é uma das maiores fontes, em 2026, das queixas de que «o Claude Code está estúpido»:

Quando instala todos estes MCP de uma só vez, acaba por sufocar a janela de contexto do LLM: todas as ferramentas disponíveis são carregadas para o contexto.

Uma regra prática: mantenha no máximo 2–3 servidores MCP ativos, orientados para tarefas específicas. Na experiência descrita com muitos servidores, o arranque era mais lento e os erros ocorriam com maior frequência.

A pesquisa de ferramentas MCP foi adicionada no Claude Code v2.1.x: as ferramentas deixaram de ser carregadas de forma gananciosa para o contexto e passaram a ser indexadas e obtidas a pedido. Isto reduz o custo de «muitos MCP num projeto», mas não o elimina por completo.

Em que difere um plugin de uma skill e porque se esbateu a fronteira?#

A formulação oficial:

Os mais instalados em junho de 2026:

A análise completa da seleção está no guia dos 10 melhores plugins entre 101.

Quando usar um plugin:

• Um pacote comunitário pronto a usar que cobre grande parte de um fluxo de trabalho, como design ou revisão.
• Se não quiser montar manualmente uma configuração de «skill + subagente + MCP + hook», pode usar uma já pronta.
• Distribuição empresarial: um administrador cria um marketplace de equipa e os programadores instalam tudo a partir de um prefixo único.

Quando NÃO usar um plugin:

• A tarefa resolve-se com uma skill, mas o pacote traz mais cinco MCP «por precaução». Isso é pura desorganização do contexto.
• Um plugin de código fechado sem auditoria. É executado com as suas permissões — leia o conteúdo antes de o instalar.
• Já tem o seu próprio plugin sobre o mesmo tema. Um duplicado no contexto significa o dobro do incómodo.

Antes da instalação, o Claude Code v2.1.143+ mostra o Context cost, uma estimativa dos tokens que o plugin acrescentará a cada mensagem. Desde o v2.1.145+, mostra o campo Will install com uma lista completa dos comandos, agentes, skills, hooks, MCP e LSP do pacote. Antes de clicar em instalar, é o primeiro ecrã a abrir.

Que matriz de seleção funciona em 2026?#

Seis perguntas, por ordem de prioridade:

1. É um procedimento recorrente, um estilo ou uma lista de verificação? Se sim — skill.
2. Precisa de dados ou ações externos (base de dados, API, Slack, GitHub, Figma)? Se sim — servidor MCP.
3. Quero um contexto separado para não encher o principal? Se sim — subagente.
4. Quero uma verificação ou uma etapa automática num evento definido? Se sim — hook, com cobertura testada; para limites mais amplos de acesso, use permissões ou isolamento do ambiente.
5. Quero um pacote pronto a usar que reúna 1–4 num só clique? Se sim — plugin do marketplace.
6. É uma tarefa complexa que precisa de dados, contexto e estilo? Então use uma combinação: subagente Haiku + skill pré-carregada + um MCP de âmbito restrito.

Fórmula da combinação:

Um subagente Haiku com uma skill pré-carregada para convenções e um servidor MCP de âmbito restrito para dados em tempo real é um padrão que realmente compensa.

E a principal regra sobre a direção da dependência:

Os subagentes podem usar servidores MCP. Os servidores MCP não podem usar subagentes.

Por outras palavras, o MCP serve sempre para dados e ações, não para agentes. Se quiser delegar uma tarefa, será um subagente que chama o MCP, e não o inverso.

Um exemplo concreto aqui descrito: o motor editorial de uma agência digital que escreve um artigo SEO em 60 minutos. Inclui 25 subagentes e 14 etapas de revisão — executadas sequencialmente, cada uma com o seu próprio contexto, permissões e skill para convenções editoriais. Um subagente liga-se a um servidor MCP com uma base de dados de etiquetas prontas a usar e artigos antigos. O agente orquestrador principal funciona com Opus; os agentes filhos funcionam com Haiku, mantendo o orçamento razoável.

Isto não é uma «fábrica de artigos»; é um exemplo de como os quatro mecanismos se combinam num único sistema quando a tarefa exige profundidade e qualidade, em vez de rapidez.

Que 7 erros deve eliminar já do Claude Code?#

1. Instalou os 10 melhores plugins porque «estão na moda». Cada um acrescenta tokens a todas as mensagens. Abra /plugin list e verifique o Context cost de cada um. Remova os que não utilizou nas últimas duas semanas.

2. Copiou 15 servidores MCP do .mcp.json de outra pessoa. A configuração de outra pessoa serve os projetos e as tarefas dessa pessoa. Mantenha no máximo 2–3 MCP ativos para o projeto atual. Mova os restantes para uma configuração separada de outro projeto ou elimine-os agora.

3. A skill e o plugin MCP fazem a mesma coisa. A skill diz «faça uma revisão de código», enquanto o plugin pr-review-toolkit executa o seu próprio fluxo de revisão. Começam a competir pela prioridade. Sintoma: «Claude, porque é que estás sempre a mudar de ideias?» Solução: mantenha uma única fonte de verdade. Na configuração descrita, foi escolhida a skill para manter o controlo sobre as instruções.

4. Usa uma skill para impor uma regra quando precisa de um hook. Uma skill, por si só, não impõe esse limite. Para «bloquear .env num commit», um hook de pre-commit pode verificar esse percurso. Teste separadamente o conteúdo preparado para commit e os percursos alternativos; o hook não impede toda a leitura nem outras formas de publicação.

5. Um subagente com as mesmas permissões do agente principal. Deu-lhe Opus e todas as ferramentas e obteve outra sessão principal. O prompt de sistema da documentação oficial recomenda dar ao subagente uma lista restrita de ferramentas e uma tarefa própria e limitada. Caso contrário, é apenas um clone dispendioso.

6. Não verificou o Will install antes de instalar um plugin. No Claude Code v2.1.145+, este campo mostra todo o conteúdo do pacote. Muitas vezes, um plugin «para uma coisinha» contém três servidores MCP, dois subagentes e cinco hooks. Passam todos a viver no seu contexto.

7. A antiga pasta .claude/commands/ duplica skills novas. A Anthropic afirma na documentação:

A antiga pasta commands/ continua a funcionar, mas as skills são agora o padrão. No exemplo descrito, ambas as pastas estavam a ser usadas; a pasta commands/ foi removida e ficaram as skills com ficheiros e acionadores incluídos.

Sinais de que o Claude Code ficou «desorganizado»:

• Cada mensagem começa por mencionar as ferramentas disponíveis em mais de 200 linhas.
• As tarefas simples demoram mais do que há um mês.
• O Claude confunde duas skills ou dois plugins semelhantes.
• Surgem avisos de colisão de nomes quando começa uma sessão.
• O Claude chama a ferramenta errada — uma skill A em vez do MCP B de que precisava.

Se reconhecer pelo menos dois destes sintomas, abra já /plugin list e /skill list. Primeiro, remova o que não usou nas últimas duas semanas. Depois, verifique o Context cost de cada item. Por fim, resolva os antipadrões acima.

Quantas skills e MCP pode manter sem esgotar o contexto?#

O que o Claude Code mostra diretamente:

• /skill list — todas as skills ativas e o respetivo tamanho em tokens.
• /plugin list — todos os plugins e o respetivo Context cost.
• /mcp list — servidores MCP e o número de ferramentas.

Orçamento de tokens em valores concretos:

Uma janela de contexto é o espaço de trabalho máximo, não a quantidade de tokens consumida em cada tarefa. Compare a entrada, a entrada em cache, a saída e os turnos repetidos medidos para o mesmo resultado. O isolamento pode reduzir o contexto principal, mas o subagente continua a gerar utilização própria.

No seu blogue técnico, a Anthropic indica os valores da compactação automática para as skills: os primeiros 5,000 tokens de cada skill ativa são anexados novamente, com um orçamento total de 25,000. Isto significa que, com mais de 5 skills «pesadas» ativas ao mesmo tempo, o Claude começa a perder algumas instruções.

Uma regra prática simples:

• Skills: no máximo 5–7 ativas no projeto atual. Coloque as restantes em ~/.claude/skills/disabled/; se precisar delas, pode voltar a movê-las.
• MCP: no máximo 2–3 por projeto. O Context7 para documentação quase sempre compensa; mantenha os restantes específicos para cada tarefa.
• Plugins: instale rigorosamente um de cada vez e, ao fim de duas semanas, verifique se o utilizou. Se não, remova-o.

Uma análise detalhada do Agentic Coding Trends Report de 2026 da Anthropic e das razões por que 80% dos programadores não conseguem delegar uma tarefa inteiramente ao Claude está num guia separado. O principal valor desse relatório: as pessoas usam IA em 60% do seu trabalho, mas só delegam por completo 0–20% das tarefas. A principal razão é a sobrecarga do contexto e a perda de controlo sobre as ferramentas.

Por onde deve começar um principiante: a configuração mínima funcional?#

Configuração mínima após duas semanas de trabalho:

1. CLAUDE.md na raiz, com as regras do projeto.
2. AGENTS.md para compatibilidade com outras ferramentas, se tenciona trabalhar também fora do Claude Code. Mais detalhes em «Como criar um único ficheiro de instruções para Claude Code, Codex e Cursor».
3. 1 skill para a principal tarefa recorrente. Por exemplo, comece por code-review, de acordo com o seu guia de estilo.
4. 1 servidor MCP: Context7 para documentação atualizada. Sem ele, o Claude continua a alucinar APIs inexistentes.
5. 0 plugins e 0 subagentes no primeiro mês. A questão não é poupar dinheiro; é ter controlo. Até compreender o básico, os pacotes vão confundi-lo.

A partir daí, siga as tarefas. Surgiu um procedimento recorrente? Transforme-o numa skill. Precisa de dados em tempo real de um serviço específico? Adicione MCP. Uma tarefa grande começa a encher o contexto principal? Delegue-a a um subagente.

Esse é o mapa em três níveis: primeiro o contexto, depois passe para o sistema aquilo que faz mais do que algumas vezes e, por fim, verificações automáticas para que o sistema não cometa erros por si próprio. Acrescente cada nível apenas quando o anterior já estiver a funcionar.