No trimestre passado, tive uma conversa com o tech lead de um cliente que deixou claro por que este artigo precisava existir. O time tinha passado três semanas construindo o que chamava de “nossa frota de agentes”: seis agentes customizados para diferentes partes da base de código, com prompts sob medida, nomes bem pensados, o pacote completo. Sentamos juntos para entender por que eles não conseguiam rodar dois deles em paralelo.
A resposta é que eles não tinham construído agentes. Tinham construído seis skills. Todas vivendo dentro de uma única sessão do Claude Code, todas carregadas na mesma janela de contexto sempre que suas descrições davam match. Quando a terceira entrava em ação, o contexto já passava de 150 mil tokens e a qualidade caía. Rodar duas ao mesmo tempo simplesmente não existia como opção, porque não eram processos separados. Eram parágrafos dentro do mesmo prompt.
A confusão conceitual custou três semanas. A reescrita, depois que demos o nome certo à primitiva, levou dois dias. O sistema ficou bem menor no fim e rodou em paralelo pela primeira vez.
Este artigo trata justamente da camada que a maioria dos times confunde, escrito para que você não perca essas três semanas.
As três camadas: tools, MCPs e skills.
Antes de entrar em skills versus subagents, vale entender a camada que dá contexto às duas. O Claude Code (e qualquer coding agent moderno) opera em três camadas ortogonais, e a maioria dos times só internalizou uma delas de verdade.
Tools são verbos. São o que o agente consegue fazer fisicamente. Alguns exemplos:
- Ler um arquivo.
- Escrever um arquivo.
- Editar um arquivo.
- Rodar um comando bash.
- Buscar com grep.
- Fazer glob em um caminho.
- Buscar uma URL.
- Pesquisar na web.
Elas já vêm embutidas no agente. Você não as configura. Você as libera ou restringe.
MCPs são conexões externas. O Model Context Protocol é um padrão aberto que a Anthropic lançou em novembro de 2024 e que desde então foi adotado por OpenAI, Google, Microsoft, Cursor e pela maior parte das superfícies de agente. Em dezembro de 2025, a Anthropic doou o MCP para a Agentic AI Foundation, sob a Linux Foundation.
Adoção reportada pela Anthropic: mais de 97 milhões de downloads mensais do SDK e mais de 10.000 servidores MCP ativos. O MCP é a camada que conecta seu agente ao banco de dados de produção, ao Datadog, Sentry, GitHub, Slack, Jira e a qualquer outra coisa que tenha uma API.
Skills são receitas: pastas de markdown que ensinam o agente a fazer bem um tipo específico de trabalho dentro do seu contexto. Quando escrever uma migration de Postgres desse jeito e não daquele, como estruturar uma spec nesta empresa, o que significa “code review” quando é este time específico que faz. São o conhecimento institucional do seu time, versionado e independente de ferramenta.
As três camadas são independentes. A maioria dos times que vejo já domina as tools (eles entregam features), já plugou dois ou três MCPs (normalmente GitHub e um banco de dados) e não fez praticamente nada em skills. É em skills que está o investimento de maior alavancagem para a maioria dos times em 2026.
Leia mais: As três eras do software: do autocomplete ao desenvolvimento agêntico
Como uma skill é na prática
Uma skill é uma pasta. No mínimo, ela contém um SKILL.md com dois campos de frontmatter YAML: name e description. Esse é o único conteúdo obrigatório. Opcionalmente, a pasta pode incluir references/ (markdown adicional carregado sob demanda), examples/ (exemplos concretos que o agente lê quando fazem sentido) e scripts/ (código executável que a skill pode chamar).
O mecanismo que torna as skills baratas é o que a Anthropic chama de progressive disclosure, descrito na documentação oficial de skills. São três níveis de carregamento.
O nível um é o frontmatter. Só o name e a description. Isso fica no system prompt do agente o tempo todo, em toda sessão. O Claude lê apenas isso na hora de decidir se invoca a skill. Uma descrição como “quando o usuário quer planejar uma migration de Postgres” é o que diz ao agente “esta skill é relevante para esta tarefa”. Erre a descrição e a skill nunca vai ser usada.
O nível dois é o corpo do SKILL.md, carregado apenas quando a skill é ativada. A Anthropic recomenda manter isso abaixo de 500 linhas. Acima disso, você começa a forçar a memória de trabalho do agente e a skill deixa de ser barata de rodar.
O nível três são os arquivos em references/, carregados apenas quando o corpo da skill aponta para eles. É assim que você carrega material de referência profundo (um documento de convenções de banco de dados com 2.000 linhas, por exemplo) sem pagar o custo de contexto em toda tarefa que encosta no banco. O agente busca só quando precisa.
As skills seguem uma hierarquia de quatro níveis: Enterprise, User, Project e Plugins. A mesma hierarquia do CLAUDE.md, e isso é intencional. Skills também funcionam entre superfícies de agente diferentes. O mesmo SKILL.md roda no Claude Code, Cursor, Codex CLI, OpenCode e Copilot CLI. Essa portabilidade é parte do motivo pelo qual skills são a camada em que vale investir, em vez de prompts amarrados a uma ferramenta específica.
Packs prontos que vale conhecer
Não sou fã de time de engenharia construindo tudo do zero. Skills são justamente uma área em que a comunidade já entregou muita coisa útil, boa parte gratuita, e dar fork costuma ser a decisão certa.
Superpowers é o maior pack de skills construído pela comunidade, criado por Jesse Vincent (obra). Em 15 de janeiro de 2026, ele foi aceito no marketplace oficial de plugins do Claude Code da Anthropic, o que no mundo open source equivale mais ou menos a receber um selo de aprovação.
O pack traz skills para brainstorming, test-driven development, debugging sistemático, desenvolvimento guiado por subagents com code review e para escrever skills (sim, uma skill que escreve skills).
Instale com /plugin install superpowers@claude-plugins-official. Funciona no Claude Code, Cursor, Codex, Copilot CLI, Gemini CLI e OpenCode.
GStack é o pack do Garry Tan, lançado em 12 de março de 2026 sob licença MIT. Garry Tan é President e CEO da Y Combinator, e o GStack tem opiniões fortes que refletem a visão da YC sobre um time de engenharia de startup. São vinte e três especialistas modelados como personas (CEO, Designer, Engineering Manager, Release Manager, Doc Engineer, QA Lead, Chief Security Officer, entre outros) mais oito power tools.
O loop que o pack impõe é Think, Plan, Build, Review, Test, Ship, Reflect. Útil para times pequenos que querem uma opinião forte sobre workflow sem ter que escrever a própria.
Tech Leads Club agent-skills é um pack construído por uma comunidade brasileira de engenharia, com licença MIT, disponível no npm em @tech-leads-club/agent-skills. A skill principal é a tlc-spec-driven, que implementa o workflow Specify, Design, Tasks, Execute com profundidade adaptativa.
O pack também inclui skill-architect, subagent-creator, create-technical-design-doc, handoff e diagnose. Instale de forma interativa com npx @tech-leads-club/agent-skills ou skill a skill com agent-skills install -s tlc-spec-driven.
O padrão nos três é o mesmo. Não construa do zero o que alguém já compartilhou. Dê fork no pack, customize as partes que precisam se encaixar no seu contexto e contribua de volta se puder.
Leia mais: Spec-Driven Development: como capturar a intenção antes de queimar tokens
Subagents são outra coisa
É aqui que a maioria dos times tropeça. No papel, a anatomia de um subagent é idêntica à de uma skill: um arquivo markdown com frontmatter. O comportamento, porém, é estruturalmente diferente.
A documentação oficial da Anthropic é direta. “Cada subagent começa com uma janela de contexto nova e isolada. Ele não vê o histórico da sua conversa, as skills que você já invocou, nem os arquivos que o Claude já leu.” Essa frase resume tudo. Um subagent é um processo separado, com contexto próprio, tools próprias, modelo próprio e permissões próprias.
Quatro diferenças práticas em relação às skills.
- Contexto: uma skill injeta conteúdo na janela do agente pai. Um subagent roda em uma janela nova e isolada, só dele. Essa é a diferença que mais importa. Se duas tarefas precisam rodar sem interferir na memória de trabalho uma da outra, elas têm que ser subagents.
- Modelo: uma skill herda o modelo do pai. Um subagent define o seu. Você pode ter um orchestrator em Opus coordenando implementadores em Sonnet e um formatador em Haiku. Com skills, isso não é possível.
- Tools: uma skill pode declarar allowed-tools para restringir quais tools o agente pai usa enquanto ela está ativa. Um subagent tem o próprio conjunto de tools, concedido explicitamente na definição. Dá para criar um subagent que só tem acesso de leitura e grep, por exemplo, um subagent “pesquisador” seguro, que fisicamente não consegue editar arquivos.
- Paralelismo: skills não são paralelas. São parágrafos dentro do mesmo prompt. Subagents são paralelos por padrão. O agente pai consegue disparar cinco subagents em uma única chamada de tool, e eles rodam ao mesmo tempo.
A regra prática que eu uso é mecânica: se a mesma instrução vai ser reaproveitada em várias tarefas e não precisa de contexto próprio, escreva uma skill; se o trabalho precisa de janela isolada, modelo próprio ou restrição de tools, dispare um subagent. Skills são o “como fazer”. Subagents são o “quem faz”.
O padrão orchestrator e especialistas
Este é o padrão de arquitetura que faz o desenvolvimento da terceira era escalar de verdade, e é por isso que acertar a distinção entre skills e subagents importa tanto.
O desenho é um agente orchestrator, normalmente rodando em um modelo mais forte (Opus 4.7 na linha de maio de 2026), que coordena vários subagents especialistas rodando em paralelo em um modelo mais rápido e barato (Sonnet 4.6).
Uma feature típica pode ter um especialista de backend, um de frontend, um de infra e um de product manager, cada um trabalhando no próprio contexto e produzindo o próprio output. Depois dos especialistas, um subagent revisor lê os diffs combinados. O humano entra como gate no fim, depois do revisor.
Isso funciona pelo mesmo motivo que um time de software de verdade funciona. Cada especialista tem contexto limpo. A memória de trabalho de ninguém é poluída pelo que outro especialista está fazendo. O orchestrator é dono da coordenação e do contrato entre as partes. O revisor é dono da checagem de integração.
Boris Cherny, da Anthropic, descreve em Mastering Claude Code in 30 Minutes como entrega de 20 a 30 pull requests por dia desse jeito. Cinco instâncias do Claude em paralelo, cada uma em uma aba de terminal separada com o próprio checkout, todas iniciadas em plan mode para que o plano possa ser revisado antes de a implementação se espalhar. Essa rotina não é possível se os seus “agentes” são skills dividindo uma única janela de contexto. Ela exige subagents de verdade em worktrees de verdade.
Worktrees: o facilitador sem glamour.
Worktrees merecem um parágrafo próprio porque são o mecanismo que torna seguros os subagents em paralelo.
Git worktrees permitem ter vários diretórios de trabalho em branches diferentes do mesmo repositório, sem precisar copiar o repo. O Claude Code tem suporte nativo a eles pela flag –worktree (ou -w). O comando claude –worktree feature-x cria um novo worktree em .claude/worktrees/feature-x/ em uma nova branch worktree-feature-x e inicia uma sessão dentro dele. A sessão fica isolada do seu checkout principal. Outra sessão rodando com –worktree feature-y não interfere.
Por que isso importa? Porque subagents em paralelo precisam de um lugar seguro para escrever arquivos. Dois subagents editando o mesmo diretório de trabalho ao mesmo tempo é receita para inferno de merge e arquivos sobrescritos. Dois subagents trabalhando cada um no próprio worktree, na própria branch, com os próprios arquivos ignorados (o .worktreeinclude controla o que volta por symlink), é uma separação limpa que permite ao orchestrator coordenar o merge lá na frente.
Se você roda qualquer coisa além de um único agente por vez, worktrees não são opcionais. São o que evita o desastre de escrita paralela que encerra o experimento de muitos times com desenvolvimento multiagente.
Como configurar seus agentes
Quatro movimentos, nesta ordem.
- Audite os “agentes” que você já tem. Para cada um, pergunte: ele precisa de contexto próprio, modelo próprio, restrição de tools própria ou de rodar em paralelo com outro? Se a resposta for não para as quatro, é uma skill. A maior parte do que os times construíram como agentes acaba sendo skill com o nome errado. Renomear e reorganizar costuma ser tarefa de um dia e clareia a arquitetura na hora.
- Instale um pack da comunidade. Escolha um: Superpowers, GStack ou Tech Leads Club agent-skills. Use por uma semana do jeito que veio. A ideia é aprender o formato de uma skill bem construída antes de tentar escrever a sua. Dar fork no que os outros construíram também evita queimar uma sprint reinventando primitivas de brainstorm, debug ou TDD que já existem.
- Monte um orchestrator com dois especialistas em uma feature real. Um especialista de backend, um de frontend, os dois como subagents, cada um no próprio worktree, coordenados por um orchestrator pai. Sonnet 4.6 para os especialistas, Opus 4.7 para o orchestrator. Escolha uma feature pequena o suficiente para entregar em um dia. O objetivo não é a feature. O objetivo é a primeira rodada real do seu time com o padrão.
- Comite suas skills no repositório. Toda skill que o time escrever vai para .claude/skills/ (ou o equivalente na sua ferramenta) e é versionada como código. Pull requests revisam skills do mesmo jeito que revisam testes. Conhecimento que vive em skills é conhecimento que sobrevive à rotatividade do time.
Conclusão
O padrão que vence em 2026 não é comprar uma licença do Claude Code para todo mundo. É construir as primitivas certas para que os engenheiros consigam entregar em paralelo. Skills são as receitas, subagents são os trabalhadores, o orchestrator coordena e as worktrees mantêm o paralelismo seguro. Cada primitiva faz um trabalho. A maioria dos times ainda não separou uma da outra.
É dessa separação que o próximo ano de trabalho de arquitetura vai tratar. Os times que entenderem isso primeiro vão entregar de cinco a dez vezes mais rápido que os times que ainda rodam um agente por vez em uma única janela de contexto. Não porque o modelo deles é melhor. Porque as primitivas são.
É esse o trabalho que fazemos na Cheesecake Labs todos os dias. Ajudamos times de engenharia a sair do “a gente usa Claude Code” para o “a gente tem um sistema agêntico”: skills versionadas, subagents nomeados, orchestrator patterns, worktrees, a stack inteira.
Se o seu time está rodando agentes mas não descobre por que o paralelismo não funciona, fale com a gente. O diagnóstico costuma ser uma das quatro primitivas sendo confundida com outra, e o ajuste é mais rápido do que a conversa sobre se vale a pena fazer.
