A descrição de uma ferramenta MCP é uma frase associada a uma única função que
pode ser chamada: o que faz, o que recebe, se altera alguma coisa. Viaja com
cada pedido que o cliente envia ao modelo, ao lado da descrição de todas as
outras ferramentas. Um skill é uma pasta com um arquivo SKILL.md lá dentro,
que contém um procedimento — faz isto, depois verifica aquilo, pergunta antes
desta outra coisa — e o corpo dele só é carregado quando o modelo decide que o
seu pedido corresponde.
É esta a distinção toda, e é uma distinção sobre quando o texto está em contexto, não sobre o que o texto diz. As descrições são o bilhete de entrada: paga por todas, em cada turno, para sempre. As instruções de um skill são gratuitas até serem relevantes. É por isso que um parágrafo indefensável numa descrição de ferramenta — trezentas palavras sobre como triar uma pilha de gravações de reuniões — é perfeitamente razoável num skill.
Este artigo é sobre decidir para onde vai cada uma das suas instruções. Se o protocolo em si for novidade para si, o que é um servidor MCP trata primeiro do vocabulário, e MCP face a plugins e integrações mostra onde fica o MCP em relação às formas mais antigas de ligar as coisas.
Na especificação do MCP, a definição de uma ferramenta tem uma forma pequena e
fixa. Transporta um name, um title opcional legível por pessoas, uma
description, um inputSchema que descreve os argumentos, um outputSchema
opcional e annotations — propriedades opcionais que descrevem o comportamento
da ferramenta, por exemplo se apenas lê. O cliente vai buscar a lista inteira com
uma chamada tools/list e coloca-a à frente do modelo, que é o que torna as
ferramentas MCP controladas pelo modelo: é o modelo que escolhe uma com base na
conversa.
Esta forma é boa em exatamente uma coisa: dizer a um modelo o que faz uma chamada isolada, para que ele escolha a certa. É estruturalmente má noutras três.
Não consegue descrever ordem. Nada na definição de uma ferramenta pode dizer
«chama list_channels antes de share_to_channel, porque o canal tem de existir
e o usuário tem de o escolher». Cada descrição é uma ilha.
Não consegue conter muito. Todas as descrições estão em contexto em cada pedido de cada conversa, incluindo todas as conversas que nunca vão tocar nessa ferramenta. Um servidor com quinze ferramentas e um parágrafo em cada uma já gastou uma parte apreciável da janela de contexto antes de o usuário escrever fosse o que fosse.
Não consegue codificar o seu critério. «Marca a gravação com uma etiqueta em vez de a partilhar quando não tens a certeza de quem a deve ver» é uma política, não a descrição de uma função. Duas equipes diferentes quereriam duas políticas diferentes para a mesma ferramenta.
Há uma válvula de escape no protocolo: o servidor pode devolver uma string
instructions quando o cliente se liga, e o cliente pode acrescentá-la ao
system prompt — antes da lista de ferramentas. É o sítio certo para uma
orientação curta: o que é este servidor, a que está ligado, com o que ter
cuidado. Duas ressalvas. Continua a ser texto por sessão, por isso mantém-se
curto. E a especificação diz que os clientes a podem usar, não que têm de o
fazer, por isso o suporte para a mostrar realmente ao modelo varia de cliente
para cliente.
Um skill é uma pasta que contém um arquivo SKILL.md: frontmatter YAML com um
name e uma description, seguido de instruções em markdown. Pode trazer outras
coisas ao lado — scripts/ para código executável, references/ para
documentação detalhada, assets/ para modelos — e o agente só as puxa quando as
instruções o mandam lá.
O modelo de carregamento chama-se progressive disclosure, divulgação progressiva, e a especificação apresenta-o em três fases:
name e a
description de cada skill disponível — com um orçamento de cerca de 100
tokens por skill. O suficiente para saber quando pode ser relevante, e nada
mais.SKILL.md para o contexto. A recomendação é manter isto abaixo de
cerca de 5000 tokens, e o arquivo principal abaixo de 500 linhas.Ter vinte skills instalados custa, portanto, vinte descrições curtas. Ter vinte descrições de ferramentas longas custa vinte descrições de ferramentas longas, em cada turno. É esta assimetria a razão de existir da camada.
O formato não é específico de um cliente. Agent Skills foi desenvolvido pela
Anthropic e lançado como norma aberta, publicada em agentskills.io; a montra de
clientes que lá está lista dezenas de produtos que leem a mesma pasta, entre eles
Claude Code, Claude, ChatGPT e Codex, Cursor, VS Code, GitHub Copilot, Gemini
CLI, Goose, Roo Code, Kiro, Junie, Amp, Factory, Tabnine, Snowflake Cortex Code e
Databricks Genie Code. Verificado em 14 de agosto de 2026.
O frontmatter obrigatório é deliberadamente magro. name tem até 64 caracteres,
letras minúsculas, dígitos e hífenes, e tem de coincidir com o nome da pasta que
o contém. description tem até 1024 caracteres e deve dizer tanto o que o skill
faz como quando o usar — porque essa string é toda a base sobre a qual um
agente decide se abre o arquivo. Os campos opcionais são license,
compatibility, metadata e o experimental allowed-tools.
Esse campo de descrição merece mais cuidado do que costuma receber. «Ajuda com notas de reunião» nunca vai corresponder a nada de forma fiável; «revê e arruma as gravações recentes — atribui etiquetas, dá nome aos oradores, partilha as que pertencem a um canal de equipe; usar quando o usuário pedir para arrumar, triar ou pôr a leitura em dia» vai.
Entre as descrições por chamada e os skills carregados a pedido fica uma camada que não é nem uma coisa nem outra: arquivos que o agente lê no início de uma sessão, independentemente do que pediu.
AGENTS.md é a versão mais simples — markdown normal, sem campos obrigatórios, lido a partir do arquivo mais próximo subindo a árvore de pastas. O site do próprio formato indica utilização em mais de 60 000 projetos de código aberto e lista suporte em OpenAI Codex, Google Jules e Gemini CLI, agentes Claude, o agente de programação do GitHub Copilot, Aider, VS Code, Cursor, Zed, Warp, Factory, goose, Roo Code, Devin e Junie. Verificado em 14 de agosto de 2026.
As regras do Cursor são a mesma ideia com um interruptor. Vivem em
.cursor/rules como arquivos .mdc, e três campos do frontmatter decidem
quando cada uma entra: alwaysApply: true coloca-a em todas as sessões de
conversa; uma description deixa o agente avaliar a relevância; globs prendem-a
a um arquivo correspondente que esteja aberto; e sem nenhum deles definido, a
regra só chega quando a mencionar com @. O Cursor também suporta AGENTS.md e
agora suporta Agent Skills diretamente — os skills ficam em .cursor/skills/ ou
.agents/skills/ — com uma ferramenta de migração que converte em skills as
regras dinâmicas e os comandos de barra elegíveis. Verificado em 14 de agosto de
2026.
Releia estes dois parágrafos e o padrão fica claro: os formatos convergiram,
os modelos de carregamento não. Toda a gente lê SKILL.md agora. Mas uma regra
alwaysApply e um bloco de AGENTS.md têm o âmbito da sessão, um skill tem o
âmbito da tarefa, e nenhuma compatibilidade de formatos altera isso.
A consequência prática é uma regra de bolso que vale mais do que os detalhes dos formatos:
| Para onde vai | O que pertence ali | Quanto custa |
|---|---|---|
description da ferramenta |
Uma frase: o que faz esta chamada, o que altera | Em cada pedido, para sempre |
instructions do servidor |
Uma orientação curta a todo o servidor | Em cada sessão neste servidor |
AGENTS.md, regras de aplicação permanente |
Factos verdadeiros para todas as tarefas deste repositório | Em cada sessão deste projeto |
SKILL.md |
Procedimentos, políticas, exemplos resolvidos, critério | Só quando a tarefa corresponde |
Tudo o que for longo, tudo o que for condicional, tudo o que só é verdade parte
do tempo: skill. A falha em que as pessoas caem é pôr cento e cinquenta linhas de
procedimento específico de um produto num AGENTS.md global, onde ficam em
contexto enquanto passam a tarde a trabalhar num backend que nada tem a ver.
O Speak-Y traz um servidor MCP, e serve de boa ilustração porque as duas camadas estão visivelmente a fazer trabalhos diferentes.
As descrições das ferramentas cobrem as chamadas: procurar gravações, ler uma
transcrição, um resumo ou os action items, listar canais e etiquetas — e, com a
aplicação a correr, etiquetar uma gravação, mudar o nome de um orador, mudar-lhe
o título, transcrevê-la de novo ou arrumá-la num canal de equipe. Cada uma traz
uma anotação a dizer se lê ou se altera, que é o que permite a um cliente
perguntar antes de executar as que alteram, e o que faz de --read-only um único
interruptor em vez de uma lista de nomes de ferramentas para memorizar. A leitura
acontece localmente, contra a biblioteca na sua máquina; os comandos que alteram
passam pela aplicação em execução e ficam lá registados, como explica com mais
detalhe o que torna o acesso de escrita seguro.
O skill cobre o trabalho. Quando instala a integração em
Configurações → Integrações, o Speak-Y escreve um skill de organização ao
lado da configuração do servidor: por onde começar ao triar uma pilha de
gravações, quando a resposta certa é uma etiqueta e quando é um canal, que ações
confirmar antes de executar. As descrições não conseguiriam conter isso, e a
string instructions do servidor não deve sequer tentar.
Está também escrito da forma que o modelo de carregamento recompensa. Um arquivo
detalhado vive num sítio, e cada cliente recebe um ponteiro curto para ele no
formato que esse cliente lê — um SKILL.md para o Claude Code, uma regra .mdc
para o Cursor, um bloco marcado dentro de AGENTS.md para o Codex, um bloco
marcado em GEMINI.md para o Gemini CLI. Os clientes de âmbito de sessão recebem
um ponteiro precisamente por serem de âmbito de sessão: cento e cinquenta linhas
sobre notas de reunião não devem estar residentes enquanto depura o backend de
outra pessoa. Os blocos ficam entre marcadores, por isso reinstalar substitui
apenas essa seção e deixa o resto do arquivo intacto.
O servidor MCP em si é gratuito em todos os planos, incluindo o Free. A instalação com um clique e a configuração manual para cada cliente estão documentadas em Assistentes de IA (MCP).
Três perguntas, por esta ordem.
A instrução descreve uma única chamada? Então é uma descrição de ferramenta, e deve ter uma ou duas frases. Se der por si a escrever a terceira, encontrou um skill.
É verdade em todas as sessões, independentemente da tarefa? Então pode ir
para AGENTS.md ou para uma regra de aplicação permanente — mas avalie com
honestidade a parte do «independentemente da tarefa». «Este repositório usa pnpm»
qualifica-se. «Este é o nosso processo de triagem de reuniões» não.
Descreve um procedimento com passos, escolhas ou exceções? Skill. Submeta o
nome e a descrição a escrutínio a sério, porque são estas duas strings que fazem
todo o encaminhamento, e ponha tudo o que for longo num arquivo em references/
ao lado do SKILL.md, em vez de dentro dele.
Erre no sentido barato e o seu agente fica com o contexto inchado e com pior taxa de acerto em todas as perguntas que nada têm a ver. Erre no sentido caro — procedimento entalado nas descrições das ferramentas — e o modelo lê a sua política em cada turno e ainda assim pode não a seguir, porque uma descrição é lida como documentação de uma função e não como uma instrução a cumprir.
Se quiser ver a diferença em concreto, o teste mais rápido é escrever um skill para um trabalho que repita mesmo, e compará-lo com os prompts que andava a colar. Prompts para perguntar à IA sobre as suas reuniões é uma boa fonte de candidatos: os que corre mais do que duas vezes são os que pertencem a um arquivo.
A descrição de uma ferramenta é uma frase associada a uma única função que pode ser chamada, escrita pelo autor do servidor e enviada ao modelo em cada pedido como parte da lista de ferramentas. Um skill é uma pasta com um arquivo SKILL.md que contém um procedimento — vários passos, várias ferramentas, decisões de critério — e só o nome e a descrição dele estão em contexto até o modelo decidir que a tarefa corresponde. As descrições respondem a «o que faz esta chamada»; os skills respondem a «como faço este trabalho».
Para tarefas de uma só chamada, não. Precisa de um quando um trabalho exige várias ferramentas por uma ordem determinada, quando a escolha certa entre duas ferramentas depende de contexto que as descrições não conseguem transportar, ou quando quer o mesmo procedimento repetido de forma idêntica em várias sessões. Boas descrições tornam correta cada chamada; um skill torna consistente uma sequência de chamadas.
Não. Agent Skills foi desenvolvido pela Anthropic e lançado como norma aberta publicada em agentskills.io, e a montra de clientes que lá está lista dezenas de adotantes — entre eles Claude Code, ChatGPT e Codex, Cursor, VS Code, GitHub Copilot, Gemini CLI, Goose, Roo Code, Kiro, Junie e Factory. Verificado em 14 de agosto de 2026.
O AGENTS.md é markdown simples, sem campos obrigatórios, que o agente lê a partir da pasta mais próxima na árvore, e é carregado para a sessão independentemente do que pediu. O corpo de um skill só é carregado depois de o agente fazer corresponder o seu pedido à descrição dele. Ambos são úteis, mas tudo o que for longo pertence a um skill, porque o conteúdo do AGENTS.md ocupa contexto em todas as sessões, incluindo as que nada têm a ver com ele.
A especificação do Agent Skills recomenda manter o SKILL.md principal abaixo de 500 linhas e de cerca de 5000 tokens, passando o material de referência detalhado para arquivos separados que o agente carrega apenas quando precisa deles. O nome e a descrição têm um orçamento de cerca de 100 tokens, porque é isso que todas as sessões pagam.