Skills, MCP ou regras: qual usar no agente de código?

Habilidades de agentes vs. servidores MCP vs. ficheiros de regras: a resposta curta

As habilidades de agentes, os servidores MCP e os ficheiros de regras colocam conhecimento à disposição de um agente de programação. Escolha com base no que esse conhecimento faz. O MCP (model context protocol) destina-se a dados que podem ser diferentes da próxima vez que os consultar. Uma habilidade descreve um procedimento que pode documentar hoje e que continuará correto daqui a seis semanas. Um ficheiro de regras contém os poucos factos que têm de ser válidos em todas as sessões.

Essa escolha tem um custo, e o custo é o contexto. Cada token gasto numa instrução de que o agente não precisava é um token que deixa de estar disponível para o código que está a ler. Também paga esse token novamente em cada interação, porque toda a janela de contexto é reenviada em cada pedido. Por isso, a pergunta útil não é qual mecanismo pode executar a tarefa. Na maioria dos dias, os três podem fazê-lo. A pergunta é qual deles custa menos enquanto permanece inativo.

O custo de cada opção antes de a utilizar

As três carregam em momentos diferentes, e essa temporização é a principal diferença.

Um ficheiro de regras é carregado integralmente no arranque, em todas as sessões, seja relevante ou não. O Claude Code lê CLAUDE.md no início de todas as conversas e carrega-o por completo, independentemente do tamanho. O objetivo documentado é manter cada ficheiro abaixo de 200 linhas, porque um ficheiro maior consome mais contexto e é seguido com menos consistência. Estes dois efeitos acumulam-se. Por isso, um ficheiro de regras com 900 linhas é pior do que não ter regras.

Uma skill é carregada em duas fases. No arranque, apenas a linha description do frontmatter SKILL.md de cada skill entra no contexto. Assim, o modelo sabe que a skill existe e quando é aproximadamente aplicável. O corpo é carregado quando a skill é invocada. Por isso, um documento de referência com 400 linhas quase não tem custo até ser necessário.

Um servidor MCP costumava ser a opção mais dispendiosa. É aqui que a maioria das comparações atuais está desatualizada. A pesquisa de ferramentas está ativada por predefinição nas versões atuais do Claude Code. No início da sessão, são carregados apenas os nomes das ferramentas e o campo de instruções do servidor. Os esquemas JSON completos (JavaScript object notation) são adiados até o Claude os pesquisar. Adicionar um servidor já não custa milhares de tokens logo no início. Ainda existe um custo, e continua a ser cobrado integralmente no início nas configurações em que a pesquisa de ferramentas está desativada.

[
  {
    "label": "Rules file, 200 lines",
    "at_startup": "2,500",
    "after_use": "2,500"
  },
  {
    "label": "Skill, 12 KB body",
    "at_startup": 40,
    "after_use": "3,000"
  },
  {
    "label": "MCP server, tool search on",
    "at_startup": 500,
    "after_use": "3,200"
  },
  {
    "label": "MCP server, tool search off",
    "at_startup": "4,500",
    "after_use": "4,500"
  }
]

São estimativas, não medições feitas na sua máquina. Baseiam-se no tamanho do texto carregado por cada mecanismo, considerando aproximadamente 4 caracteres por token: um ficheiro de regras com 200 linhas tem cerca de 10 KB de markdown, a descrição de uma skill tem cerca de 160 caracteres e um servidor que expõe 12 ferramentas inclui cerca de 18 KB de esquema, além de um bloco de instruções com 2 KB. O Claude Code trunca cada descrição de ferramenta e cada campo de instruções do servidor para 2 KB, pelo que essa parte tem um limite máximo. A próxima secção mostra como consultar os seus próprios valores reais.

Leia as duas primeiras linhas em conjunto. O ficheiro de regras custa 2,500 tokens numa sessão em que ninguém precisou dele. A skill custa 40 tokens nessa mesma sessão e 3,000 na sessão em cada dez em que é acionada. As duas últimas linhas referem-se ao mesmo servidor, duas vezes, com a pesquisa de ferramentas ativada e desativada: 500 tokens contra 4,500. Essa diferença explica por que continua a circular a recomendação antiga sobre o excesso de contexto causado pelo MCP.

A pesquisa de ferramentas requer um modelo compatível com blocos tool_reference. Em agosto de 2026, isso significa Claude Sonnet 4.5, Haiku 4.5, Opus 4.5 e versões posteriores. O Claude Code desativa-a quando ANTHROPIC_BASE_URL aponta para um host que não é first party, porque a maioria dos proxies não encaminha esses blocos. Defina ENABLE_TOOL_SEARCH para a controlar: false carrega todos os esquemas logo no início, true adia todos e auto carrega-os logo no início apenas quando cabem em 10% da janela de contexto.

# Load schemas up front only if they fit in 5% of the window
ENABLE_TOOL_SEARCH=auto:5 claude

A pergunta decisiva: os dados mudam entre invocações?

Faça esta pergunta primeiro, porque ela elimina logo uma opção. Se o agente precisar de ler ou escrever algo que possa estar diferente da próxima vez que o consultar, precisa de um servidor. Um sistema de acompanhamento de problemas, uma base de dados, um painel de monitorização, a sua própria API interna (interface de programação de aplicações). Registar essa informação não ajuda, porque fica desatualizada assim que outra pessoa edita o registo.

Se a resposta continuar correta daqui a seis semanas sem ninguém a mantê-la, precisa de uma skill. Uma checklist de release. Um procedimento de migração. A estrutura das suas respostas de erro. A forma como este repositório exige que os testes sejam escritos. Uma skill é um ficheiro no git. Não tem porta, processo nem modo de falha além de estar errada, algo que uma revisão de código pode detetar.

Se for um único facto que tenha de se aplicar a trabalho em que ainda não pensou, coloque-o no ficheiro de regras. Run make lint before committing. Never push to main. Handlers live in src/api/handlers/. Uma linha para cada um. Quando uma entrada cresce e passa a incluir passos, deixa de ser um facto e torna-se um procedimento. Deve então ser movida para uma skill.

Quando um arquivo de regras é suficiente

Os arquivos de regras são carregados de vários locais, do mais abrangente ao mais específico: um arquivo de política gerenciado, o seu ~/.claude/CLAUDE.md pessoal, o ./CLAUDE.md ou ./.claude/CLAUDE.md do projeto e um ./CLAUDE.local.md ignorado pelo git. Todos os arquivos encontrados são concatenados, em vez de substituírem uns aos outros, e os arquivos mais próximos do diretório de trabalho são lidos por último.

Claude Code lê CLAUDE.md, não AGENTS.md. Se o seu repositório já tiver um AGENTS.md para outras ferramentas, não mantenha duas cópias que possam ficar divergentes.

ln -s AGENTS.md CLAUDE.md

O symlink não exibe nada quando a operação é concluída com sucesso. Inicie uma sessão, execute /context e confirme se CLAUDE.md aparece em Arquivos de memória. Se não estiver listado, o agente nunca o viu, e nenhuma reformulação resolverá o problema. Quando também quiser incluir linhas específicas do Claude, use o formato de importação e coloque essas linhas abaixo da importação.

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Há uma armadilha neste ponto. As importações @path não economizam contexto. O arquivo importado é expandido e carregado na inicialização junto com o arquivo que fez a referência, até uma profundidade de quatro níveis. Dividir um arquivo de regras de 600 linhas em seis importações organiza o conteúdo para as pessoas, mas não altera em nada o custo em tokens. Vale ler as convenções por trás do AGENTS.md e o seu equivalente voltado para as pessoas antes de escolher um layout.

O que reduz o custo é .claude/rules/ com um campo paths. Um arquivo de regras com frontmatter paths só é carregado quando o agente acessa um arquivo que corresponde a um dos padrões.

---
paths:
  - "src/api/**/*.ts"
---

# API rules

- Every endpoint validates its input.
- Use the standard error response shape.

Uma regra sem o campo paths é carregada na inicialização com a mesma prioridade que .claude/CLAUDE.md. Portanto, o padrão de trabalho consiste em regras condicionais curtas, além de uma lista paths em tudo o que só é relevante dentro de um diretório.

Quando você quer uma competência

Uma competência é um diretório que contém um SKILL.md. As competências pessoais ficam em ~/.claude/skills/<name>/SKILL.md e aplicam-se a todos os projetos na sua máquina. As competências do projeto ficam em .claude/skills/<name>/SKILL.md, acompanham o repositório e podem ser revistas num pull request, como qualquer outro ficheiro.

mkdir -p ~/.claude/skills/summarize-changes

---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

Run `git status` and `git diff` against the merge base.
Group the changes by intent, not by file.
Call out anything touching auth, migrations or deletions.

O description é a única parte desse ficheiro presente no contexto antes de a competência ser executada, por isso desempenha duas funções. Indica o que a competência faz e quando deve ser usada. Uma descrição como "Ajuda com deploys" não dá ao modelo informação suficiente para associar um pedido, por isso a competência nunca é acionada e conclui-se que as competências não funcionam.

O nome do diretório torna-se o comando, por isso o exemplo acima produz /summarize-changes. Numa competência pessoal ou do projeto, o frontmatter name define apenas o rótulo apresentado nas listagens.

Depois de uma competência ser invocada, o respetivo conteúdo renderizado entra na conversa como uma única mensagem e permanece nela durante o resto da sessão. O Claude Code não volta a ler o ficheiro nas mensagens seguintes. Escreva instruções permanentes, não passos para uma única execução, e mantenha o corpo conciso, porque, a partir desse momento, cada linha representa um custo recorrente em cada pedido. Depois da compactação automática, o Claude Code volta a anexar a invocação mais recente de cada competência, mantendo os primeiros 5,000 tokens de cada uma dentro de um orçamento combinado de 25,000 tokens. Se invocar várias competências grandes numa sessão, as mais antigas são totalmente removidas. Por isso, uma competência pode parecer deixar de ser relevante depois de uma conversa longa. Invoque-a novamente para a recuperar. Quando o mesmo procedimento se aplica a mais de uma base de código, partilhe uma competência entre vários repositórios em vez de copiar o ficheiro.

Quando precisar de um servidor MCP

Adicionar um servidor requer apenas um comando, e o transporte determina a forma da configuração.

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remote HTTP server behind a bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# Local stdio server: everything after -- is passed through untouched
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

O -- é importante. Num servidor stdio, separa as próprias opções do Claude Code da linha de comandos que inicia o servidor. Se o omitir, um --port 8080 destinado ao servidor é interpretado como uma opção de claude mcp add, que o rejeita.

claude mcp list
claude mcp get notion

claude mcp add confirma a operação com uma linha Added ..., que apenas indica que a configuração foi gravada no disco. claude mcp list é o comando que mostra a situação real, porque apresenta um estado de funcionamento junto de cada servidor: ✔ Connected, ! Needs authentication ou ✘ Failed to connect. Um estado de falha significa que o Claude Code não conseguiu contactar esse servidor, não que o comando de listagem tenha falhado. Numa sessão, /mcp apresenta a mesma informação por servidor, juntamente com o número de ferramentas.

Cada chamada a um servidor MCP é independente e transporta tudo o que precisa, o que explica por que um servidor MCP não se lembra do pedido anterior. Esta é uma escolha de arquitetura com uma consequência que terá de assumir: qualquer estado que precise de ser preservado tem de ficar no servidor, numa base de dados ou num ficheiro, e essa é uma componente que passa a administrar.

Um servidor MCP é um processo que tem de executar

Este é o custo que as comparações dos fornecedores deixam de fora. Uma skill é um ficheiro. Um servidor MCP é software que executa algures e, quando esse local é o seu VPS (virtual private server), é você quem é responsável pela disponibilidade.

Um servidor stdio é o caso simples. O Claude Code inicia-o como um processo filho quando a sessão começa, e ele termina quando a sessão acaba. Não há nada para monitorizar nem para corrigir segundo um calendário próprio. Um servidor HTTP remoto é um serviço de longa duração e precisa do mesmo que qualquer serviço desse tipo.

[Unit]
Description=Notes MCP server
After=network-online.target
Wants=network-online.target

[Service]
User=mcp
WorkingDirectory=/srv/notes-mcp
ExecStart=/usr/bin/node /srv/notes-mcp/dist/server.js
Environment=PORT=8931
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now notes-mcp
systemctl is-active notes-mcp
journalctl -u notes-mcp -n 50 --no-pager

systemctl is-active deve apresentar active. Se apresentar failed, o journal contém o motivo e, na primeira execução, quase sempre se trata de uma variável de ambiente ausente ou de uma porta já ocupada por outro processo. Restart=on-failure não é opcional neste caso, porque um servidor MCP que falhe não se anuncia. Você só descobre o problema quando o agente informa que não consegue ler o seu sistema de acompanhamento de problemas.

Associe o processo a 127.0.0.1 e coloque um reverse proxy com TLS (transport layer security) à frente dele. Um servidor MCP que acede à sua base de dados e responde numa porta pública sem autenticação é uma base de dados que você publicou. Executar um servidor MCP num VPS explica corretamente a configuração do proxy, do certificado e da firewall.

Depois, contabilize honestamente o trabalho recorrente. O serviço recebe atualizações de segurança segundo o seu próprio calendário, independentemente do agente que comunica com ele. O token OAuth expira e claude mcp list começa a apresentar ! Needs authentication num momento inconveniente. As credenciais ficam num ficheiro de configuração ou num cabeçalho Authorization, por isso precisam do mesmo cuidado que qualquer outro segredo. Este é um assunto abrangente: manter os segredos fora do alcance de um agente de IA. Nada desse trabalho existe no caso de uma skill.

Pondere a alternativa antes de criar o servidor. Se os dados por trás do servidor proposto mudarem aproximadamente uma vez por trimestre, uma skill que indique ao agente onde procurar e o significado dos campos será mais barata do que um serviço que tem de manter ativo.

Como medir o custo do seu próprio contexto

Pare de fazer estimativas e execute /context dentro de uma sessão. O comando mostra a decomposição da inicialização: prompt do sistema, ficheiros de memória, ferramentas e servidores MCP, com o peso em tokens de cada item.

Verifique duas coisas. Em Ficheiros de memória, confirme se todos os ficheiros de regras esperados estão listados. Um ficheiro em falta fica invisível para o agente. Por isso, esta é a primeira hipótese a excluir quando as instruções são ignoradas. Em seguida, veja quanto os seus servidores consomem. Se um servidor que utiliza duas vezes por mês for uma das maiores linhas da lista, desative-o em /mcp e volte a ativá-lo nas sessões que precisarem dele. A configuração é preservada de qualquer forma.

Um servidor remoto também pode apresentar um estado como cached 2h ago · connects on first use · 5 tools. Isso significa que o Claude Code leu a lista de ferramentas de uma sessão anterior em vez de estabelecer a ligação durante a inicialização. A ligação será estabelecida na primeira vez que uma ferramenta for chamada. As ferramentas estão disponíveis desde a sua primeira mensagem, portanto não há nada a corrigir. Defina MCP_DISCOVERY_CACHE=0 se preferir que todos os servidores estabeleçam a ligação durante a inicialização. Para uma visão mais ampla, gerir a janela de contexto do Claude Code explica o que permanece depois da compactação, e quanto esses tokens lhe custam realmente converte os números em dinheiro.

Por que minha skill nunca é acionada?

A causa mais comum é o description. Esse é o único texto disponível no contexto antes da execução da skill. Se não descrever a situação, nada corresponde a ela. Escreva o acionador na frase: "Use quando o utilizador perguntar o que mudou, quiser uma mensagem de commit ou pedir a revisão do diff." Descrições vagas falham silenciosamente, o que dificulta identificar o problema.

A segunda causa é um erro de digitação no frontmatter, e esta é evidente. Uma chave desconhecida é rejeitada diretamente:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

A terceira causa é a localização. As skills do projeto são carregadas de .claude/skills/ no diretório de trabalho e em todos os diretórios-pai até à raiz do repositório. As skills em diretórios aninhados abaixo do local onde iniciou não são carregadas no arranque. Elas aparecem na primeira vez que o agente lê ou edita um ficheiro dentro desse subdiretório. Até lá, não são apresentadas no preenchimento automático e não podem ser invocadas pelo nome.

O equivalente no MCP a esta falha silenciosa é uma entrada .mcp.json com um url e sem type. Claude Code lê qualquer entrada sem type como um servidor stdio. Por isso, ignora a entrada e apresenta:

MCP server "notes" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry

Usando os três em conjunto

Estes mecanismos não competem pelo mesmo espaço. Uma configuração eficaz usa cada um onde o custo é menor. O ficheiro de regras contém um conjunto reduzido de linhas que são válidas em todo o lado. As skills contêm os procedimentos e são carregadas apenas quando se aplicam. Um servidor MCP, ocasionalmente dois, liga-se aos sistemas cujo conteúdo não é possível prever antecipadamente. Se ainda está a formar o modelo mental do primeiro mecanismo, o que é realmente uma agent skill explica o formato em detalhe.

Um teste esclarece a maioria das dúvidas sobre onde algo deve ficar. Elimine-o, inicie uma sessão nova e atribua a tarefa ao agente. Se o agente ficar apenas mais lento, o conteúdo devia estar numa skill. Se o agente estiver confiantemente errado, o conteúdo devia estar no ficheiro de regras. Se o agente não conseguir obter a informação, precisava do servidor e também de um plano para manter esse servidor ativo.

FAQ

Devo escrever uma skill ou disponibilizar um servidor MCP?

Decida com base no facto de a informação mudar entre uma invocação e a seguinte. Se o agente tiver de ler o estado atual que outra pessoa pode editar, como um sistema de acompanhamento de problemas, uma base de dados ou um dashboard, precisa de um servidor MCP, porque qualquer informação que escreva fica desatualizada assim que o registo muda. Se pudesse escrever a resposta uma vez e ela continuasse correta daqui a seis semanas, escreva uma skill. A skill é um ficheiro no git sem processo para executar, porta para expor ou calendário de patches, por isso é a opção mais económica sempre que for possível utilizá-la.

Os servidores MCP continuam a ocupar a minha janela de contexto?

Muito menos do que anteriormente. A pesquisa de ferramentas está ativada por predefinição no Claude Code atual. Por isso, apenas os nomes das ferramentas e o campo de instruções do servidor são carregados no início da sessão, e os esquemas completos são obtidos quando o Claude os pesquisa. O carregamento inicial continua a ocorrer quando a pesquisa de ferramentas está desativada: com ENABLE_TOOL_SEARCH=false, com ANTHROPIC_BASE_URL apontado para um proxy que não é first party ou num modelo anterior à geração Claude 4.5. Execute /context para verificar em que situação se encontra, porque os números de artigos de comparação antigos pressupõem o carregamento inicial.

O Claude Code lê AGENTS.md?

Não. O Claude Code lê CLAUDE.md. Se o seu repositório já tiver um AGENTS.md para outros agentes, aponte um para o outro em vez de manter duas cópias. Execute ln -s AGENTS.md CLAUDE.md para criar um symlink simples ou coloque @AGENTS.md na primeira linha de um CLAUDE.md e adicione abaixo as instruções específicas do Claude. Em seguida, inicie uma sessão e execute /context para confirmar que CLAUDE.md aparece em Memory files.

Porque é que a minha skill deixou de ter efeito a meio de uma sessão?

A compactação automática é normalmente a causa. Quando a conversa é resumida, o Claude Code volta a anexar a invocação mais recente de cada skill. Mantém os primeiros 5,000 tokens de cada uma, dentro de um orçamento combinado de 25,000 tokens para todas. Preenche esse orçamento a partir da skill invocada mais recentemente. Por isso, se tiver invocado várias skills grandes, as mais antigas são completamente descartadas. Invoque novamente a skill para restaurar o conteúdo completo.

Como impeço que um ficheiro de regras longo seja carregado em todas as sessões?

Mova as partes que só são relevantes em algumas situações para ficheiros .claude/rules/ com um campo paths no frontmatter, para que cada ficheiro seja carregado apenas quando o agente tocar num ficheiro correspondente. Dividir o ficheiro em imports @path não ajuda, porque os ficheiros importados são expandidos e carregados no arranque, juntamente com o ficheiro que os referenciou. Qualquer conteúdo que seja um procedimento com várias etapas, em vez de um facto permanente, deve tornar-se numa skill, porque o corpo de uma skill não tem custo até ser invocado.