Agent skills, MCP ou regras: qual escolher?

Diferenças entre agent skills, servidores MCP e ficheiros de regras: a resposta curta

Agent skills, servidores MCP e ficheiros de regras disponibilizam conhecimento a 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 na próxima consulta. Uma skill destina-se a um procedimento que pode documentar hoje e que continuará correto daqui a seis semanas. Um ficheiro de regras destina-se aos poucos factos que têm de ser respeitados em todas as sessões.

Essa escolha tem um 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 é um token pelo qual paga 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 mecanismo antes de o utilizar

Os três são carregados em momentos diferentes, e essa temporização é a diferença essencial.

Um ficheiro de regras é carregado integralmente no arranque, em todas as sessões, seja ou não relevante. O Claude Code lê CLAUDE.md no início de cada conversa 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 apontam na mesma direção, e é por isso que um ficheiro de regras com 900 linhas é pior do que inútil.

Uma skill é carregada em duas fases. No arranque, apenas a linha description do frontmatter SKILL.md de cada skill entra no contexto, para que o modelo saiba que a skill existe e tenha uma indicação aproximada de quando se aplica. O corpo é carregado quando a skill é invocada. Por isso, um documento de referência com 400 linhas quase não tem custo até ao momento em que é necessário.

Um servidor MCP costumava ser o mecanismo mais dispendioso, e é neste ponto que a maioria das comparações que encontrará 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 instructions do servidor. Os esquemas JSON (JavaScript object notation) completos são adiados até o Claude os pesquisar. Adicionar um servidor já não custa milhares de tokens antecipadamente. Ainda tem algum custo, e continua a carregar tudo antecipadamente 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"
  }
]

Estas são estimativas, não medições feitas na sua máquina. Baseiam-se no tamanho do texto carregado por cada mecanismo, considerando aproximadamente quatro 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 doze ferramentas transporta cerca de 18 KB de esquema, além de um bloco instructions de 2 KB. O Claude Code trunca cada descrição de ferramenta e cada campo instructions 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 é ativada. As duas últimas linhas mostram o mesmo servidor duas vezes, com a pesquisa de ferramentas ativada e desativada: 500 tokens contra 4,500. Essa diferença é o motivo pelo qual continua a circular o aconselhamento antigo sobre o excesso de contexto causado pelo MCP.

A pesquisa de ferramentas requer um modelo que suporte blocos tool_reference, o que, em agosto de 2026, 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 antecipadamente, true adia todos eles e auto carrega-os antecipadamente 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 uma opção de imediato. Se o agente precisar de ler ou escrever algo que possa estar diferente na 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 ou a sua própria API interna (application programming interface). Registar a informação não resolve, porque o que escreveu fica desatualizado assim que outra pessoa edita o registo. A sua própria base de código também pertence a essa lista, porque a estrutura muda a cada commit. É esse o motivo para fornecer ao agente um mapa analisado do repositório através do MCP, em vez de descrever a estrutura num ficheiro que fica desatualizado.

Se a resposta continuar correta daqui a seis semanas sem manutenção, 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 deve escrever testes. Uma skill é um ficheiro no git. Não tem porta, processo nem modo de falha além de estar errada, o que pode ser detetado numa revisão de código.

Se for um único facto que tenha de se aplicar a trabalho que ainda não considerou, 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 facto. Quando uma entrada cresce e passa a conter passos, deixou de ser um facto e tornou-se um procedimento. Deve ser movida para uma skill.

Quando um ficheiro de regras é suficiente

Os ficheiros de regras são carregados de vários locais, do mais abrangente para o mais específico: um ficheiro de política gerido, 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 ficheiros encontrados são concatenados, em vez de se substituírem uns aos outros, e os ficheiros mais próximos do diretório de trabalho são lidos por último.

O 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

A ligação simbólica não imprime nada quando é criada com sucesso. Inicie uma sessão, execute /context e confirme que CLAUDE.md aparece em Ficheiros de memória. Se não estiver listado, o agente nunca o viu e nenhuma reformulação ajudará. Quando também quiser linhas específicas do Claude, use a forma de importação e coloque essas linhas abaixo da importação.

@AGENTS.md

## Claude Code

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

Existe uma armadilha neste ponto. As importações @path não guardam contexto. O ficheiro importado é expandido e carregado no arranque, juntamente com o ficheiro que o referenciou, até uma profundidade de quatro níveis. Dividir um ficheiro de regras com 600 linhas em seis importações organiza-o para os utilizadores, mas altera o custo de tokens exatamente em zero. Vale a pena ler as convenções por trás de AGENTS.md e do seu equivalente voltado para utilizadores antes de escolher uma estrutura.

O que reduz o custo é .claude/rules/ com um campo paths. Um ficheiro de regras que contenha paths no frontmatter só é carregado quando o agente acede a um ficheiro 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 um campo paths é carregada no arranque com a mesma prioridade que .claude/CLAUDE.md. Assim, o padrão de trabalho consiste em regras incondicionais curtas, complementadas por uma lista paths em tudo o que só seja relevante dentro de um diretório.

Quando você precisa de 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 numa 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 cumpre duas funções. Indica o que a competência faz e quando deve ser utilizada. Uma descrição como "Ajuda nas implementações" não dá ao modelo nada que possa associar a um pedido, por isso a competência nunca é ativada e você conclui que as competências não funcionam.

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

Depois de uma skill ser invocada, o conteúdo renderizado entra na conversa como uma única mensagem e permanece lá durante o resto da sessão. Claude Code não volta a ler o ficheiro em turnos posteriores. Escreva instruções permanentes, não passos para uma única execução, e mantenha o corpo conciso, porque, a partir desse momento, cada linha tem um custo recorrente em cada pedido. Depois da compactação automática, Claude Code volta a anexar a invocação mais recente de cada skill, mantendo os primeiros 5,000 tokens de cada uma dentro de um orçamento combinado de 25,000 tokens. Se invocar várias skills grandes na mesma sessão, as mais antigas são removidas por completo. Por isso, uma skill pode parecer deixar de ter efeito depois de uma conversa longa. Invoque-a novamente para a recuperar. Uma skill com muitos procedimentos torna esse compromisso concreto: a skill unlazy e o respetivo método Depth Tree consome contexto real com gates e um ficheiro de plano, em troca de um agente que deixa de declarar prematuramente que o trabalho terminou. Quando o mesmo procedimento se aplica a mais de uma base de código, partilhe uma skill entre vários repositórios em vez de copiar o ficheiro.

Quando precisa de um servidor MCP

Adicionar um é feito com um único comando, e o transporte determina a sua forma.

# 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 seu servidor. Se o omitir, um --port 8080 destinado ao servidor é interpretado como uma opção do claude mcp add, que o rejeita.

claude mcp list
claude mcp get notion

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

Cada chamada a um servidor MCP é independente e transporta tudo aquilo de que precisa, e é por isso que um servidor MCP não se lembra do seu pedido anterior. Esta é uma opção de conceção com uma consequência que passa a ser da sua responsabilidade: qualquer estado que precise de ser mantido tem de ficar no servidor, numa base de dados ou num ficheiro, e isso passa a ser algo que terá de administrar.

Um servidor MCP é um processo que tem de executar

Este é o custo que as comparações dos fornecedores omitem. Uma skill é um ficheiro. Um servidor MCP é software que é executado em algum lugar. Quando esse lugar é o seu VPS (virtual private server), é você quem garante a disponibilidade.

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

[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. Na primeira execução, quase sempre falta uma variável de ambiente ou há outra aplicação a utilizar a porta. Restart=on-failure não é opcional neste caso, porque um servidor MCP que terminou inesperadamente não se anuncia. Você só descobre o problema quando o agente informa que não consegue ler o seu sistema de gestão de issues.

Ligue o processo a 127.0.0.1 e coloque um reverse proxy com TLS (transport layer security) à sua frente. 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 na Internet. Executar um servidor MCP num VPS explica corretamente o proxy, o certificado e a configuração 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 dos mesmos cuidados que qualquer outro segredo. Este é um tema completo por si só: manter os segredos fora do alcance de um agente de IA. Nada desse trabalho existe para uma skill.

Compare esta opção com a alternativa antes de a implementar. Se os dados por trás do servidor proposto mudam aproximadamente uma vez por trimestre, uma skill que indique ao agente onde procurar e o significado dos campos é 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 apresenta a divisão do arranque: prompt do sistema, ficheiros de memória, ferramentas e servidores MCP, com o peso em tokens de cada componente.

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, essa é a primeira hipótese a excluir quando as instruções são ignoradas. Se o ficheiro estiver listado e a regra continuar a ser ignorada, a causa está noutro ponto. Nesse caso, vale a pena analisar as razões pelas quais um agente ignora uma instrução que consegue ver antes de reescrever a linha. Depois, verifique o custo dos seus servidores. Se um servidor que utiliza duas vezes por mês for uma das maiores parcelas da lista, desative-o em /mcp e volte a ativá-lo nas sessões que precisarem dele. A configuração permanece guardada.

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 o arranque. A ligação será estabelecida na primeira vez que uma ferramenta for chamada. As ferramentas estão disponíveis desde a primeira mensagem. Não há nada para corrigir. Defina MCP_DISCOVERY_CACHE=0 se preferir que todos os servidores estabeleçam ligação durante o arranque. Para obter uma visão mais abrangente, 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 ele não descrever a situação, nada corresponderá. Inclua o gatilho na frase: "Use quando o utilizador perguntar o que mudou, quiser uma mensagem de commit ou pedir uma revisão do diff." Descrições vagas falham silenciosamente, o que torna o problema difícil de detetar.

A segunda causa é um erro de digitação no frontmatter. Neste caso, o erro é explícito. 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 a partir de .claude/skills/ no diretório de trabalho e em todos os diretórios superiores 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 aparecem 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. O Claude Code trata 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 algumas linhas que são válidas em qualquer situação. As skills contêm os procedimentos e só são carregadas quando se aplicam. Um servidor MCP, ocasionalmente dois, liga os sistemas cujo conteúdo não é possível prever antecipadamente. Se ainda estiver a formar o seu modelo mental sobre o primeiro destes mecanismos, o que é realmente uma skill de agente explica o formato em detalhe.

Um teste resolve a maioria das dúvidas sobre onde colocar algo. Remova-o, inicie uma sessão nova e atribua a tarefa ao agente. Se o agente ficar apenas mais lento, o conteúdo pertencia a uma skill. Se o agente der uma resposta errada com confiança, o conteúdo pertencia ao ficheiro de regras. Se o agente não conseguir obter a informação, precisava do servidor e agora também precisa de um plano para manter esse servidor em funcionamento.

FAQ

Devo escrever uma skill ou configurar 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 gestão de tarefas, uma base de dados ou um dashboard, precisa de um servidor MCP, porque tudo o que escrever fica desatualizado 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, sem porta para expor e sem calendário de patches, por isso é a opção mais económica sempre que for possível.

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

Muito menos do que ocupavam. A pesquisa de ferramentas está ativada por predefinição no Claude Code atual. Assim, 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 acontecer 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 ver em que situação se encontra, porque os números das comparações antigas 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. Depois, inicie uma sessão e execute /context para confirmar que CLAUDE.md aparece em Ficheiros de memória.

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, mantendo os primeiros 5,000 tokens de cada uma, dentro de um orçamento combinado de 25,000 tokens para todas. O orçamento é preenchido a partir da skill invocada mais recentemente. Assim, se tiver invocado várias skills grandes, as mais antigas são completamente descartadas. Invoque novamente a skill para restaurar todo o seu conteúdo.

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

Mova as partes que só são necessárias ocasionalmente para ficheiros .claude/rules/ com um campo paths no frontmatter, para que cada um seja carregado apenas quando o agente aceder a um 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. Tudo o que for um procedimento com várias etapas, em vez de um facto permanente, deve tornar-se uma skill, porque o corpo de uma skill não tem custo até ser invocado.