Claude Code: Agents, Skills e MCP com exemplos práticos

Introdução

O Claude Code está evoluindo de um assistente de programação para um ambiente de desenvolvimento capaz de coordenar tarefas, analisar projetos, executar testes e interagir com sistemas externos.

Complete os arquivos antes de executar o fluxo

O agente performance-reviewer citado no roteiro precisa existir. Crie .claude/agents/performance-reviewer.md com o exemplo abaixo. Agentes de leitura não precisam receber Bash ou ferramentas de escrita. Nos exemplos, PHP 8.3 é a referência de revisão, não uma exigência para usar Agents, Skills ou MCP.

---
name: performance-reviewer
description: Analisa consultas e fluxos PHP para identificar gargalos com evidências.
tools: Read, Grep, Glob
model: sonnet
---
Analise consultas N+1, índices, loops, chamadas externas e uso de memória.
Não altere arquivos nem execute carga. Diferencie suspeita de medição.
Informe arquivo, trecho, hipótese, impacto e como medir antes de corrigir.

Use a ajuda da versão instalada para listar os comandos interativos. Não presuma que /skills exista em toda versão; as Skills invocáveis aparecem como comandos pelo próprio nome, como /php-review.

Documentação: Claude Code setup · Skills · Playwright package.json.

Mas existe uma diferença enorme entre simplesmente pedir para uma inteligência artificial escrever uma função e construir um ambiente no qual ela consegue dividir responsabilidades, seguir procedimentos técnicos e utilizar ferramentas especializadas.

É nesse contexto que três recursos ganham importância: Agents, Skills e MCP (Model Context Protocol).

• Agents: agentes especializados que recebem tarefas, trabalham com contexto próprio e devolvem resultados ao agente que os coordenou.
• Skills: procedimentos e conhecimentos reutilizáveis que orientam a execução de determinadas atividades.
• MCP: protocolo que permite conectar o Claude Code a ferramentas, serviços e fontes de dados externas.

Imagine uma equipe de desenvolvimento: os Agents são os profissionais, as Skills são os procedimentos técnicos e o MCP é a infraestrutura que permite acessar sistemas e ferramentas externas.

Este guia ensina a utilizar os três recursos, começando pelas configurações individuais e avançando até uma aplicação prática integrada.

Preparando o ambiente

Você precisará do Claude Code instalado e autenticado e de um terminal. A instalação nativa do Claude Code não depende de Node.js; o método npm e servidores MCP executados por npx possuem requisitos próprios. Para Playwright MCP, prefira uma versão LTS do Node ainda suportada.

Consulte a documentação oficial de instalação.

claude --version
claude doctor
cd meu-projeto
claude

Os exemplos utilizam PHP 8.3 como referência, mas os recursos também podem ser aplicados a projetos em outras linguagens.

Agents: criando especialistas para tarefas específicas

O que são Agents no Claude Code?

O Claude Code possui subagents internos e permite criar subagents personalizados. Um subagent recebe uma tarefa delimitada, possui instruções e contexto próprios e devolve os resultados ao agente principal.

Imagine uma auditoria de uma aplicação PHP. O agente principal pode delegar a investigação de vulnerabilidades, desempenho e arquitetura a especialistas diferentes e depois consolidar os resultados.

Como funciona a delegação?

AGENTE PRINCIPAL
    |
    +-- Security Reviewer
    +-- Performance Reviewer
    +-- Architecture Reviewer
    |
    +-- Consolida os resultados

Os subagents trabalham em contextos separados e não recebem automaticamente toda a conversa principal. O agente principal precisa transmitir as informações necessárias para cada tarefa.

Criando um Agent de segurança

Crie o arquivo .claude/agents/security-reviewer.md:

---
name: security-reviewer
description: Proactively analisa aplicações PHP em busca de vulnerabilidades. Utilize após alterações importantes ou durante auditorias de segurança.
tools: Read, Grep, Glob
model: sonnet
---

# Especialista em segurança PHP

Você é responsável por analisar a segurança
de aplicações desenvolvidas em PHP.

## Objetivos
Investigue:
- SQL Injection
- Cross-Site Scripting (XSS)
- CSRF
- Falhas de autenticação e autorização
- Exposição de credenciais
- Problemas de sessão
- Upload inseguro
- Validação inadequada de entradas

## Procedimento
1. Analise a estrutura do projeto.
2. Identifique os pontos de entrada.
3. Examine os arquivos envolvidos.
4. Procure evidências técnicas.
5. Avalie o impacto de cada problema.

## Restrições
- Não modifique arquivos.
- Não execute comandos destrutivos.
- Não invente vulnerabilidades.
- Não apresente suspeitas como falhas confirmadas.

## Relatório
Para cada problema, informe:
- Arquivo e localização.
- Evidência técnica.
- Descrição da vulnerabilidade.
- Impacto potencial.
- Prioridade.
- Recomendação de correção.

O campo name identifica o agente; description ajuda o Claude a decidir quando utilizá-lo; tools limita as ferramentas disponíveis; e model seleciona o modelo, conforme disponibilidade e configuração da conta.

Neste exemplo, o agente possui ferramentas de leitura e pesquisa, mas não ferramentas de edição. A palavra Proactively incentiva a delegação quando pertinente, mas não garante execução automática.

Como testar?

Utilize o agente security-reviewer.

Analise o projeto PHP e faça uma auditoria
de segurança.

Investigue autenticação, autorização,
consultas SQL, formulários e uploads.

Não altere nenhum arquivo.

Apresente as vulnerabilidades encontradas
com evidências e classificação de risco.

O resultado esperado é que o Claude identifique a definição do agente, delegue a investigação e apresente os resultados. Se o agente não aparecer, verifique o nome do arquivo, o frontmatter e o diretório. Se o diretório foi criado durante uma sessão já aberta, reinicie o Claude Code.

Outros agentes especializados

Um Performance Reviewer pode investigar consultas SQL ineficientes, problemas de N+1, processamento desnecessário e consumo excessivo de memória. Um Architecture Reviewer pode examinar responsabilidades das classes, dependências, acoplamento e organização do projeto.

Contexto e execução paralela

Tarefas independentes podem ser executadas em paralelo. Isso não garante maior velocidade: cada subagent consome recursos e tarefas que alteram os mesmos arquivos podem gerar conflitos. Uma estratégia segura é delegar investigações separadas e centralizar as modificações.

O Claude Code também possui recursos como execução em segundo plano e Agent Teams. Eles não devem ser confundidos com o funcionamento básico dos subagents.

Documentação: Subagents do Claude Code.

Skills: transformando conhecimento em procedimentos reutilizáveis

O que são Skills?

Skills são conjuntos de instruções e materiais auxiliares que ensinam o Claude a realizar atividades. Elas permitem transformar regras de trabalho, checklists e conhecimentos técnicos em procedimentos reutilizáveis.

Uma Skill pode conter um arquivo principal SKILL.md, documentação auxiliar, exemplos, modelos e scripts. O Claude utiliza carregamento progressivo: identifica a Skill por seus metadados, carrega suas instruções quando necessário e consulta arquivos auxiliares conforme a tarefa.

Criando uma Skill de revisão PHP

Crie o diretório e o arquivo:

mkdir -p .claude/skills/php-review
nano .claude/skills/php-review/SKILL.md

Conteúdo de SKILL.md:

---
name: php-review
description: Revisa aplicações PHP considerando segurança, arquitetura, desempenho e compatibilidade com PHP 8.3. Use durante auditorias ou antes de modificar código.
---

# Revisão técnica de aplicações PHP

## Análise inicial
Antes de recomendar alterações:
1. Analise a estrutura do projeto.
2. Identifique dependências.
3. Examine as classes envolvidas.
4. Verifique relacionamentos.
5. Procure duplicações e conflitos.

## Compatibilidade
Utilize PHP 8.3 como referência.
Evite funções obsoletas e práticas incompatíveis.

## Segurança
Verifique SQL Injection, XSS, CSRF,
autenticação, autorização, sessões,
upload e exposição de informações.

## Qualidade
Avalie organização, responsabilidades,
legibilidade, reutilização, erros e desempenho.

## Restrições
- Não modifique arquivos durante auditorias.
- Não crie funcionalidades sem verificar se já existem.
- Não altere componentes protegidos.
- Não invente problemas.

## Resultado
Apresente problema, evidência, impacto,
recomendação e prioridade.

Executando a Skill

Dentro do Claude Code, invoque a Skill pelo nome:

/php-review

Também é possível associá-la a uma solicitação específica. O Claude pode ainda identificar Skills automaticamente quando a descrição corresponde à tarefa, conforme a configuração.

Adicionando documentação auxiliar

Em vez de colocar dezenas de critérios no arquivo principal, crie references/security-checklist.md:

# Checklist de segurança PHP

## Banco de dados
- Utilizar consultas preparadas.
- Evitar concatenação de entradas SQL.
- Restringir permissões do usuário do banco.

## Autenticação
- Utilizar hashing adequado de senhas.
- Regenerar identificadores de sessão.
- Implementar controles de autorização.

## Formulários
- Validar entradas no servidor.
- Implementar proteção CSRF.
- Escapar dados na saída HTML.

## Upload
- Validar extensão e conteúdo.
- Gerar nomes aleatórios.
- Impedir execução de arquivos enviados.
- Restringir diretórios de armazenamento.

No SKILL.md, instrua o Claude a consultar esse arquivo antes de concluir uma auditoria de segurança.

Executando scripts auxiliares

Uma Skill também pode incluir scripts para verificações determinísticas. Exemplo de script para validar a sintaxe PHP, ignorando dependências e arquivos do Git:

#!/usr/bin/env bash
set -euo pipefail

while IFS= read -r -d '' file; do
    echo "Verificando: $file"
    php -l "$file"
done < <(
    find . -type f -name "*.php"         -not -path "./vendor/*"         -not -path "./.git/*"         -print0
)

Salve em .claude/skills/php-review/scripts/check-syntax.sh e execute:

mkdir -p .claude/skills/php-review/scripts .claude/skills/php-review/references
# Salve o script antes de executar os próximos comandos.
chmod +x .claude/skills/php-review/scripts/check-syntax.sh
./.claude/skills/php-review/scripts/check-syntax.sh

O comando php -l verifica sintaxe, mas não garante que o sistema funcione corretamente. Testes automatizados e validações funcionais continuam necessários.

Carregando Skills em um Agent

Um subagent pode receber uma Skill no contexto inicial. Acrescente o campo skills ao frontmatter:

---
name: security-reviewer
description: Proactively realiza auditorias de segurança em aplicações PHP.
tools: Read, Grep, Glob
model: sonnet
skills:
  - php-review
---

Assim, o agente recebe as instruções da Skill antes de executar a atividade.

Escopo das Skills

• .claude/skills/: Skill específica do projeto.
• ~/.claude/skills/: Skill pessoal, reutilizável em projetos do usuário.

Documentação: Skills do Claude Code.

MCP: conectando o Claude Code a ferramentas externas

O que é Model Context Protocol?

O Model Context Protocol é um protocolo aberto que padroniza a comunicação entre aplicações de inteligência artificial e sistemas externos. Um servidor compatível pode disponibilizar ferramentas e informações para clientes como o Claude Code.

MCP não é um modelo de IA nem um agente. É uma camada de comunicação e integração.

Arquitetura MCP

• Host: aplicação que coordena a interação, como Claude Code.
• Client: componente que mantém a conexão com um servidor MCP.
• Server: programa que disponibiliza ferramentas e informações.

Tools, Resources e Prompts

Tools são operações que o modelo pode solicitar ao servidor, como consultar um usuário, criar uma tarefa ou atualizar um registro. Podem produzir efeitos reais e exigem controles adequados.

Resources são informações disponibilizadas para consulta, como documentação, arquivos e dados de configuração.

Prompts são modelos de instruções reutilizáveis oferecidos pelo servidor para padronizar tarefas.

Comunicação e transportes

O MCP utiliza mensagens estruturadas baseadas em JSON-RPC 2.0 na camada de dados. A comunicação envolve estabelecimento da conexão, negociação de capacidades, descoberta de ferramentas, solicitação e retorno dos resultados.

Os transportes mais importantes para começar são:

• STDIO: executa o servidor como processo local e utiliza entrada e saída padrão.
• Streamable HTTP: permite comunicação com servidores acessíveis por HTTP, inclusive remotos.

Transporte define como ocorre a comunicação; Tools, Resources e Prompts definem as capacidades disponibilizadas.

Instalando o Playwright MCP

O Playwright MCP permite que o Claude Code interaja com navegadores por meio de ferramentas de automação. Pode abrir páginas, navegar, clicar, preencher formulários e consultar o conteúdo de aplicações web.

Verifique os pré-requisitos:

node --version
npm --version

O pacote Playwright MCP consultado declara Node.js >=18, enquanto o guia introdutório recomenda 20 ou superior. Portanto, 20 não é um mínimo universal do protocolo MCP. A versão efetiva também depende das dependências e do pacote instalado; prefira uma LTS suportada, consulte npm view @playwright/mcp engines e adicione o servidor:

claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

O comando registra um servidor chamado playwright, usando transporte STDIO. O npx executa o pacote e -y aceita a confirmação de instalação do próprio npx. Isso não autoriza automaticamente todas as operações do servidor.

Verificando a conexão

claude mcp list
claude mcp get playwright

Dentro de uma sessão interativa, utilize /mcp para consultar conexões e ferramentas.

Primeiro teste com Playwright

Acesse a aplicação de demonstração TodoMVC e solicite ao Claude:

Utilize o servidor MCP playwright.

Acesse:
https://demo.playwright.dev/todomvc

Adicione três tarefas:
- Estudar Claude Code
- Aprender Agents
- Aprender MCP

Depois, verifique se as três tarefas
aparecem na lista.

O resultado esperado é que a página seja aberta, as tarefas sejam inseridas e o conteúdo da lista seja consultado. O Claude deverá apresentar o resultado da verificação.

Configurando MCP no projeto

Também é possível registrar a integração em .mcp.json, na raiz do repositório:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]
    }
  }
}

Esse arquivo permite compartilhar a definição da integração. Os integrantes precisam confiar na configuração e aprovar a conexão quando solicitado. Não coloque credenciais diretamente em arquivos versionados.

Servidores remotos e autenticação

Um servidor remoto pode ser registrado por HTTP. Exemplo de comando:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Um servidor protegido pode exigir autenticação, por exemplo via OAuth. Nesse fluxo, o usuário autoriza o acesso, o cliente obtém credenciais e o servidor valida o token e as permissões antes de executar operações.

Um token válido não significa autorização irrestrita. Evite inserir segredos em arquivos compartilhados ou no histórico do terminal.

Para remover uma integração:

claude mcp remove playwright

Documentação: MCP no Claude Code.

Agents, Skills e MCP: diferenças técnicas

Para memorizar: Agent é quem executa uma tarefa especializada; Skill define como um procedimento deve ser realizado; MCP permite acessar ferramentas e sistemas externos.

Uma Skill pode ser utilizada pelo agente principal ou carregada em um subagent. Um subagent também pode utilizar ferramentas MCP quando elas estiverem disponíveis para ele.

Projeto prático: construindo um fluxo de revisão automatizada

Imagine uma aplicação PHP que precisa passar por revisão antes de uma nova versão. O objetivo é analisar arquitetura, investigar vulnerabilidades, verificar desempenho, testar a aplicação no navegador e consolidar os resultados.

Estrutura do projeto

meu-projeto/
├── .claude/
│   ├── agents/
│   │   ├── security-reviewer.md
│   │   └── performance-reviewer.md
│   └── skills/
│       └── php-review/
│           ├── SKILL.md
│           └── references/
│               └── security-checklist.md
├── .mcp.json
├── app/
├── config/
├── public/
├── tests/
└── composer.json

Responsabilidades

• Skill: define os critérios de revisão.
• Security Reviewer: investiga vulnerabilidades.
• Performance Reviewer: investiga gargalos.
• MCP Playwright: permite testar a aplicação no navegador.
• Agente principal: coordena e consolida as informações.

Executando o fluxo

Com os componentes configurados, abra o Claude Code na pasta do projeto e solicite:

Realize uma revisão técnica completa
deste projeto PHP.

Utilize a Skill php-review para seguir
os critérios técnicos estabelecidos.

Delegue as atividades independentes:

1. security-reviewer:
   investigar vulnerabilidades.

2. performance-reviewer:
   investigar problemas de desempenho.

3. Agente principal:
   analisar a arquitetura e consolidar
   os resultados.

Depois, utilize o MCP playwright
para acessar a aplicação de teste.

Verifique:
- Carregamento das páginas.
- Navegação.
- Formulários.
- Erros visíveis.
- Comportamento das funcionalidades.

Não modifique arquivos.

Apresente um relatório final com:
- Problemas encontrados.
- Evidências.
- Arquivos envolvidos.
- Prioridade.
- Impacto.
- Recomendações.

O agente principal poderá distribuir as atividades e aguardar os resultados. As investigações independentes podem ocorrer em paralelo; a validação no navegador depende de a aplicação estar acessível no ambiente em que o Playwright é executado.

Como avaliar o resultado?

Um relatório que afirma ter encontrado problemas sem apresentar arquivos, trechos ou evidências não deve ser considerado uma auditoria confiável. Diferencie problemas confirmados de hipóteses que ainda precisam de investigação.

Boas práticas para projetos profissionais

Organize as responsabilidades

• CLAUDE.md: orientações gerais e contexto permanente do projeto.
• Skills: procedimentos reutilizáveis.
• Agents: tarefas especializadas e delegação.
• MCP: integrações externas.
• Hooks: automações que precisam acontecer de maneira determinística.

Utilize o princípio do menor privilégio

Um agente que apenas analisa código não precisa receber acesso para modificar arquivos. Um servidor MCP que consulta informações não precisa necessariamente ter autorização para excluir registros. Conceda somente as permissões necessárias.

Cuidado com prompt injection

Páginas, documentos e dados externos podem conter instruções maliciosas destinadas a manipular o modelo. Trate resultados externos como dados não confiáveis, não permita que instruções externas substituam as regras do projeto e revise ferramentas e servidores antes de conectá-los.

Evite excesso de agentes

Criar muitos agentes não significa melhorar o resultado. Cada subagent pode gerar solicitações adicionais ao modelo e consumir recursos. Comece com poucos especialistas e amplie a estrutura somente quando houver necessidade real.

Não confunda automação com validação

Um script que executa testes não garante que o software esteja correto. Uma análise por IA não substitui revisão técnica. Uma navegação bem-sucedida não comprova a segurança da aplicação. Utilize os recursos como partes complementares de um processo de engenharia.

Problemas comuns e diagnóstico

Comandos úteis:

claude --version
claude doctor
claude mcp list
claude mcp get playwright

Dentro da sessão, os comandos disponíveis, como /agents, /mcp e /tasks ajudam a consultar recursos e acompanhar atividades, conforme a versão e o ambiente.

Pratique: Organizar uma revisão de formulário com responsabilidades claras.

Use este roteiro para transformar a leitura em uma verificação concreta.

1. Descreva o comportamento esperado do formulário e o escopo autorizado. Separe as instruções reutilizáveis da revisão das ferramentas necessárias para inspecionar a aplicação.
2. Use uma tarefa delimitada para verificar validação e outra para reproduzir o fluxo. Só conecte um servidor MCP quando ele trouxer uma capacidade necessária ao exercício.
3. Compare as conclusões com o código e execute os testes. Revise o diff antes do commit e confirme que não houve mudança de arquivos ou dados fora do escopo.

Como conferir o resultado

Um Agent organiza trabalho, uma Skill orienta um procedimento e MCP conecta ferramentas e recursos. Dar mais ferramentas não corrige requisitos ausentes. Avalie o fluxo pela evidência produzida, pela reprodução do problema e pela manutenção das permissões.

Continue o estudo: Codex: como economizar franquia sem perder qualidade · Segurança web: laboratório de falhas e correções.

Conclusão

Agents, Skills e MCP representam três mecanismos diferentes para ampliar as capacidades do Claude Code.

Os Agents permitem distribuir responsabilidades e criar especialistas para tarefas específicas. As Skills transformam procedimentos e conhecimentos em recursos reutilizáveis. O MCP conecta a inteligência artificial a ferramentas, serviços e fontes de dados externas.

A combinação desses recursos permite construir ambientes de desenvolvimento mais organizados e automatizados. Entretanto, a escolha deve ser baseada na necessidade: para dividir uma atividade complexa, utilize Agents; para repetir um procedimento padronizado, utilize Skills; para acessar outro sistema ou ferramenta, utilize MCP.

O verdadeiro ganho não está em utilizar todos os recursos indiscriminadamente, mas em compreender como cada um resolve um problema específico.

Referências oficiais

Anthropic — Claude Code

• Subagents: criação e configuração
• Skills: criação e utilização
• MCP: integração de ferramentas externas
• Configurações e permissões
• Instalação do Claude Code

Model Context Protocol

• Arquitetura do MCP
• Documentação oficial

Microsoft Playwright

• Playwright MCP: introdução
• Playwright MCP: instalação
• Playwright MCP: configuração