Como configurar o Claude Code de verdade: MCP, skills e subagents

Instalar o Claude Code é a parte fácil

O que separa quem usa casual de quem tira proveito de verdade não é a instalação, é o que vem depois: MCP, skills e subagents

Esse trio é o coração da configuração avançada, o assunto que dominou a web em 2026

Esse guia parte de quem já passou da instalação e quer o próximo passo

Nada de repetir o passo a passo básico aqui, bora direto pro setup que vale a pena 🙂

Antes de configurar: o que você já precisa ter

Antes de sair criando skill e subagent, se liga no que precisa estar de pé

• Claude Code instalado e funcionando no terminal, se ainda não passou por isso, esse guia não é o começo
• Noção de pasta pessoal vs pasta de projeto, e essa distinção vai voltar o post inteiro
• Acesso ao terminal, porque o MCP se adiciona por comando

A pasta pessoal é a ~/.claude na sua máquina: o que tu põe ali vale pra todos os seus projetos

A pasta de projeto é a .claude dentro do repositório: o que mora ali vale só naquele projeto e pode ir pro git pro time inteiro herdar

Guarda essa diferença, ela é o fio que costura MCP, skills e subagents

Como criar uma skill no Claude Code

Skill no Claude Code é coisa de sistema de arquivos, sem mágica

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

É uma pasta com um arquivo de entrada obrigatório, e o Claude fica de olho nessas pastas

1. Crie o diretório da skill. Skill pessoal vai em ~/.claude/skills/ e skill de projeto vai em .claude/skills/. Cada skill é uma pasta, então crie ~/.claude/skills/minha-skill/

2. Dentro dela, crie o SKILL.md. Esse é o entrypoint obrigatório, sem ele não existe skill. Ele tem duas partes: o frontmatter YAML entre marcadores --- e, abaixo, o markdown com as instruções que o Claude segue quando a skill roda

---
description: Revisa segurança do projeto e dá uma nota de 0 a 100
---

Quando rodar, verifique secrets expostos, validação de inputs,
autenticação, dependências e headers de segurança.
Rode comandos reais, conte os problemas e devolva uma nota.

3. Saiba que o nome da PASTA vira o /comando. Se a pasta chama minha-skill, o comando é /minha-skill. No frontmatter, só o campo description é recomendado, ele ajuda o Claude a decidir sozinho quando carregar a skill

O erro comum deste passo: achar que o campo name define o comando

Não define! O name só serve de rótulo na listagem, quem manda no /comando é o nome da pasta. Já vi gente quebrar a cabeça com isso

4. Adicione diretórios opcionais se precisar. Além do SKILL.md, a skill pode ter scripts executáveis (Python/Bash), documentação de referência, templates e exemplos de saída, tudo opcional. Só coloca se a skill pedir

Uma coisa MUITO massa: o Claude Code observa essas pastas

Adicionar, editar ou remover uma skill em ~/.claude/skills/, no .claude/skills/ do projeto ou num diretório passado via --add-dir passa a valer dentro da sessão atual, sem reiniciar

Se quiser ir mais fundo em skill e na relação com slash command, tem um post dedicado sobre criar e migrar slash commands

Como adicionar um MCP server no Claude Code

MCP é o que conecta o Claude Code a ferramentas externas

Ele não se adiciona por arquivo, se adiciona por comando de terminal

1. Rode o claude mcp add. É o comando que registra o servidor. A partir daí o escopo é o que decide onde a configuração vai morar

2. Defina o escopo com -s ou --scope. São três: project, local e user. Cada um guarda a config num lugar e isso muda tudo pro time

# escopo de projeto: grava no .mcp.json na raiz, pode ir pro git
claude mcp add meu-server -s project -- comando-do-servidor

3. Entenda onde cada escopo guarda a config. O escopo project grava em .mcp.json na raiz do projeto, que pode ir pro git. Os escopos local e user guardam a config em ~/.claude.json, em cada máquina, e não sincronizam

O erro comum deste passo: usar escopo local esperando que o time herde a configuração

Não herda! local e user são por máquina, ficam só na sua. Se tu quer que quem clonar o repo já receba o servidor, o escopo é project

4. Versione o .mcp.json quando for pro time. Com ele commitado, quem clona o repositório e abre o Claude Code vê um prompt pra aprovar o servidor antes de ele conectar. Ou seja, ninguém sai conectando servidor de fora sem passar o olho, um guardrail bem-vindo 🙂

Como criar um subagent no Claude Code

Subagent é pra delegar uma tarefa isolada, com as ferramentas próprias dela

Aqui volta a mesma lógica de pasta monitorada das skills

1. Crie o arquivo .md do subagent. O Claude Code observa ~/.claude/agents/ (nível usuário) e .claude/agents/ (nível projeto). Cada subagent é um arquivo Markdown

2. Monte o frontmatter YAML seguido do system prompt. O frontmatter carrega name, description, a lista de tools e o model, e abaixo dele vem o system prompt que define o comportamento do agente

---
name: revisor
description: Revisa o diff em busca de bugs
tools: Read, Grep
model: sonnet
---

Você é um revisor de código. Analise o diff e aponte só
bugs de correção, sem inventar problema que não existe.

3. Saiba quem ganha quando o nome se repete. Se o mesmo nome existir nos dois níveis, o subagent de projeto (.claude/agents/) tem precedência sobre o de usuário (~/.claude/agents/). Por isso os de projeto devem ir pro controle de versão, pro time todo usar o mesmo

4. Esqueça o assistente interativo do /agents. A partir da v2.1.198, o /agents não abre mais painel de criação, ele só imprime um aviso apontando pros locais dos arquivos. Pra criar, peça ao Claude escrever o arquivo ou edite .claude/agents/ na mão

O erro comum deste passo: ficar procurando o assistente que sumiu e achar que quebrou

5. Reinicie se a pasta agents é novinha. Uma sessão já aberta não detecta o diretório agents criado pela primeira vez. Pode ser preciso reiniciar o Claude Code depois de criar a pasta

Se tu quer ver subagent trabalhando em paralelo de verdade, escrevi um passo a passo sobre programação paralela com múltiplos agentes

As skills que uso em todos os meus projetos

Agora sai da teoria: eu uso um conjunto de skills em praticamente todo projeto que começo com Claude Code

No vídeo abaixo eu montei a demonstração usando elas em sequência, pra mostrar o efeito combinado

Comecei com uma skill de brainstorm pra planejar

Ela faz VÁRIAS perguntas pra entender o projeto antes de gerar qualquer coisa, o que ajuda a tirar as dúvidas da IA logo no início

Com o documento de design aprovado, usei um prompt pra transformar ele num plano de implementação: tarefas em ordem, dependências e critério de aceitação pra cada uma

Deu 14 tarefas no plano, e foram essas 14 concluídas na execução

Depois usei uma terceira skill, de execução do plano, pra gerar o código

Pedi que a execução usasse subagents com TDD (teste primeiro, implementação depois), pra o projeto já sair testado

Se liga que a execução pede MUITO aceite durante a criação de arquivos e o setup, dá pra usar o skip pra pular esses aceites

Uma das tarefas, a de configuração de sessão, levou quase 10 minutos na minha máquina

Ao testar no navegador apareceu um erro de cadastro e login

Minha estratégia foi copiar os erros e devolver pro Claude Code analisar e corrigir, debugando até o app rodar

Com o projeto funcionando, bati o olho na interface e achei genérica, sem identidade, aquele projeto sem alma

Esse problema eu prefiro resolver com skill de front-end a instalar pacote de terceiro

Ativei a skill frontend-design e o resultado mudou bastante o layout: dark mode, tipografia, cor de acento, cards, navbar e animações

Mas atenção: o resultado do redesign varia e depende MUITO da qualidade do prompt

Parte da reclamação de que a IA não entrega o esperado vem de prompt ruim, pensa nisso antes de xingar a ferramenta

Citei o UI UX Pro Max como outra skill de design conhecida, mas fiquei na frontend-design por já resolver muitos casos

Por fim, montei uma custom skill: prefiro criar skill sob medida a baixar skill genérica, pra ficar alinhada ao projeto

Criei uma skill de segurança DENTRO do projeto (skill de projeto, não global) pedindo ao Claude que gerasse

Ela faz verificação mecânica: roda comandos reais, conta os problemas e dá uma nota de 0 a 100 cobrindo secrets, inputs, autenticação, dependências e headers

E já me ferrei aqui: a skill recém-criada não apareceu de cara porque o Claude Code ainda não tinha carregado ela, tive que reiniciar pra ser reconhecida

Usadas em sequência (brainstorm, plano, execução com subagents e TDD, redesign de front-end e a skill de segurança sob medida), elas entregam um projeto com boa arquitetura e já testado

Não é bala de prata, e as custom skills funcionam melhor quando criadas dentro do próprio projeto

Skills, MCP ou subagent: qual usar em cada situação

A maior confusão de quem começa a configurar é misturar os três

Cada peça resolve uma coisa diferente, se liga

Um detalhe que confunde: skill e slash command são unificados no Claude Code

Um arquivo em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam ambos o comando /deploy e funcionam do mesmo jeito

Então não trava pensando qual dos dois formatos, o resultado é o mesmo /comando

A regra prática:

• Fluxo repetido seu vira skill
• Ferramenta de fora vira MCP
• Tarefa isolada com ferramentas próprias vira subagent

Manter esses três separados na cabeça já evita metade da bagunça de setup

Conclusão

Instalar põe o Claude Code na máquina, mas é o setup avançado que faz ele valer a pena

MCP conecta o mundo de fora, skill automatiza o que tu repete, subagent delega o que dá pra isolar

O próximo passo é simples: começa por uma skill de projeto pequena, sente o efeito na sessão sem nem reiniciar

Depois evolui pro MCP e pros subagents versionados com o time, tudo dentro do .claude pro repositório carregar junto

É assim que a configuração deixa de ser enfeite e vira parte do jeito que você programa 🙂

até o próximo post!