O que são skills de agentes, na prática?

O que é, de facto, uma competência de agente

Uma competência de agente é uma pasta no disco com um ficheiro chamado SKILL.md. Esse ficheiro contém um nome, uma breve descrição e instruções escritas em Markdown simples. O agente carrega a descrição no arranque e lê as instruções apenas quando o seu pedido corresponde a essa descrição. Quase tudo o resto relacionado com competências decorre dessas duas frases.

A pasta pode conter mais do que esse ficheiro. A especificação Agent Skills define três diretórios opcionais: scripts/ para código executado pelo agente, references/ para documentos lidos pelo agente quando necessário e assets/ para modelos e dados. Nenhum deles é obrigatório. Uma pasta que contenha apenas um SKILL.md já constitui uma competência completa.

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

A descrição é a parte que costuma ser subestimada. É o único texto que o agente vê antes de decidir se deve abrir a competência, por isso tem de indicar o que a competência faz e quando deve ser usada, com as palavras que uma pessoa escreveria realmente.

Por que uma skill custa quase nada até ser usada

Este é o argumento que torna o formato útil, e está relacionado com o contexto, não com funcionalidades. O carregamento ocorre por etapas, num processo que a especificação chama de divulgação progressiva.

No arranque, o agente carrega o name e o description de cada skill instalada, e nada mais. A especificação Agent Skills estima esse custo em cerca de 100 tokens por skill (orientação publicada em agosto de 2026). Instalar uma dúzia de skills consome aproximadamente o contexto de um parágrafo longo.

Quando um pedido corresponde a uma descrição, o agente lê o conteúdo dessa SKILL.md. A especificação recomenda manter o conteúdo abaixo de 5.000 tokens e o ficheiro abaixo de 500 linhas. Os ficheiros em references/ e scripts/ continuam a não ter custo nesta fase. Um ficheiro de referência só é carregado se as instruções encaminharem o agente para ele. Um script incluído funciona de outra forma: o agente executa-o através da shell, pelo que o código-fonte do script nunca entra na janela de contexto; apenas entra a respetiva saída.

Compare isto com aquilo que as pessoas costumam usar primeiro: um prompt enorme. Cada linha de um prompt de sistema ou de um ficheiro de instruções sempre ativo é contabilizada em todos os pedidos, em todas as sessões, quer a tarefa precise dela quer não, e compete pela atenção com a pergunta efetiva. Dez mil tokens de instruções permanentes são um custo que se paga até para perguntar que horas são. Uma dúzia de skills custa cerca de 1.200 tokens quando está inativa e só aumenta para a tarefa que precisa dela. Este é o fundamento das skills e é por isso que uma biblioteca pequena é melhor do que um prompt mais longo.

Há uma ressalva que causa problemas. Depois de uma skill ser carregada, o seu conteúdo permanece no contexto durante o resto da sessão. Por isso, um SKILL.md longo é um custo recorrente, não um custo único. Mover os detalhes para references/ não é apenas uma questão de organização. É o mecanismo a funcionar conforme foi concebido.

Uma skill de agente não é uma chamada de ferramenta

Uma ferramenta, também chamada de chamada de função, é algo que o modelo pode invocar. O harness envia ao modelo um esquema: um nome, uma descrição e a estrutura dos argumentos. O modelo emite uma chamada, o seu código executa-a e o resultado volta como uma mensagem. As ferramentas executam ações.

Uma skill não executa nada por si só. O agente lê-a e atua usando as ferramentas que já tem. O modelo não pode passar argumentos a uma skill da mesma forma que os passa a uma ferramenta. Uma skill pode indicar ao modelo quais ferramentas usar, em que ordem e o que verificar depois.

Em resumo: uma ferramenta dá ao agente uma nova capacidade, enquanto uma skill fornece orientação sobre uma capacidade que ele já tem. Se um passo tiver de produzir sempre um resultado exato e validado, deve usar uma ferramenta ou um script. Se um passo exigir aplicar o mesmo raciocínio de forma consistente, deve usar uma skill. Uma skill pode consistir apenas em orientação e, ainda assim, ser aquela que utiliza com mais frequência, como mostra Ponytail, que leva um agente de programação a fazer a menor alteração que funciona: não adiciona nenhuma capacidade nova e apenas altera a forma como o agente utiliza as capacidades que já tem.

Uma skill de agente não é um servidor MCP

MCP (model context protocol) é um protocolo para ligar um agente a um sistema externo. Um servidor MCP é um processo que é executado, comunica através desse protocolo e expõe ferramentas ao agente. Normalmente, precisa de configuração, credenciais e de um comando local ou de um endpoint de rede. Uma skill é uma pasta que contém um ficheiro Markdown. Não existe processo, porta nem protocolo.

O custo de contexto difere da mesma forma. Cada ferramenta exposta por um servidor MCP inclui um nome, uma descrição e um esquema de argumentos. Por predefinição, esses dados ficam no pedido durante toda a sessão, sejam usados ou não. Alguns clientes começaram a obter os esquemas das ferramentas quando necessário, mas carregá-los antecipadamente continua a ser o comportamento normal. Uma skill armazenada resume-se a uma linha de texto.

Os dois componentes complementam-se, e as configurações mais robustas usam ambos. O servidor MCP fornece o acesso. A skill fornece o procedimento: quais dessas ferramentas chamar para o fluxo de trabalho real da sua equipa, em que ordem e como deve ser um bom resultado. Se alojar o seu próprio servidor, executar servidores MCP num VPS explica essa parte.

Uma skill de agente não é um prompt do sistema nem um AGENTS.md

Ambos são instruções em Markdown, por isso a confusão é compreensível. AGENTS.md, CLAUDE.md e o prompt do sistema estão sempre ativos. Uma skill é ativada conforme a necessidade.

O teste consiste numa pergunta: ignorar este parágrafo estaria errado numa tarefa sem relação com ele? O padrão de estilo, o comando de compilação e a regra de nomenclatura de branches aplicam-se a todas as tarefas. Por isso, pertencem ao ficheiro sempre ativo, que é carregado sempre. A lista de verificação de releases, executada duas vezes por mês, não se aplica a todas as tarefas. Por isso, pertence a uma skill. Quando uma secção do ficheiro sempre ativo se transforma num procedimento numerado, esse é o sinal para a mover.

Esses ficheiros têm convenções próprias que também devem ser respeitadas. Consulte o que deve ficar no AGENTS.md e o que deve ficar no ficheiro destinado às pessoas e um design.md que explica a estrutura de uma base de código para conhecer os dois ficheiros que utilizamos.

Como é uma skill mínima

No Claude Code, as skills pessoais ficam em ~/.claude/skills/<name>/SKILL.md e aplicam-se a todos os seus projetos. As skills do projeto ficam em .claude/skills/<name>/SKILL.md e são versionadas no git, para que todas as pessoas e todos os agentes que trabalham nesse repositório as tenham. O GitHub Copilot e o VS Code leem as skills do workspace a partir de .github/skills/. O ficheiro interno é o mesmo.

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

Isto é uma skill completa. O nome do diretório torna-se o comando que introduz, portanto esta é /restore-drill. No Claude Code, o menu /skills apresenta o que está instalado e é a forma mais rápida de confirmar que o ficheiro foi detetado. Se não aparecer nesse menu, há um nome incorreto: o ficheiro tem de se chamar SKILL.md, e o nome do diretório tem de usar letras minúsculas, dígitos e hífenes simples. O mesmo procedimento, escrito de forma que o seu agente possa voltar a executá-lo, complementa naturalmente os backups agendados do restic num VPS, porque executar o backup não é o mesmo que restaurá-lo.

Quando uma competência deve ser um script

Qualquer passo que tenha sempre uma única resposta correta deve ser um script, e a competência deve limitar-se a algumas linhas que indiquem quando o executar e como interpretar a saída. Há duas razões, e ambas são práticas.

Primeiro, o código-fonte de um script nunca entra na janela de contexto. Um parser com 300 linhas consome apenas a saída, enquanto a mesma lógica escrita como instruções Markdown consome todo o seu tamanho sempre que a competência é carregada.

Segundo, um script fornece a mesma resposta em duas execuções. Um modelo ao qual se pede que deduza novamente a mesma regra de análise de logs em cada execução pode produzir resultados ligeiramente diferentes num dia menos fiável, e isso só será percebido quando dois números não coincidirem.

Por isso, divida o trabalho por tipo. "Analisar o CSV e imprimir todas as linhas em que o total não corresponde aos itens da linha" é um script. "Observar as linhas impressas pelo script e explicar quais parecem resultar de um erro de introdução de dados" é uma instrução da competência. Manter o julgamento em Markdown e o comportamento determinístico no código segue o mesmo princípio de criar um loop que um agente possa executar sem a sua supervisão.

Por que a minha skill nunca é acionada?

Porque o seu description explica o que a skill faz, mas nunca indica quando deve ser usada. Essa única linha é tudo o que o agente pode comparar com o seu pedido. "Ajuda com tarefas de base de dados" não corresponde a nada específico. "Executa uma migração de esquema na base de dados de staging. Use quando o utilizador pedir para migrar uma tabela, adicionar uma coluna ou alterar um esquema" contém as palavras que uma pessoa realmente escreve, por isso a skill é acionada.

O problema oposto ocorre quando a skill é acionada constantemente. Uma descrição como "Use para quaisquer alterações de código neste repositório" corresponde a tudo, por isso o conteúdo é carregado em todas as tarefas e permanece no contexto durante o resto da sessão. Restrinja a descrição ao caso pretendido. No Claude Code, também pode definir disable-model-invocation: true no frontmatter, o que impede o carregamento automático e mantém a skill disponível quando escrever o seu nome.

O terceiro problema ocorre quando a skill duplica uma ferramenta. Instruções que dizem ao agente para curl uma API já exposta pelo servidor MCP, ou para procurar em ficheiros quando o harness tem uma ferramenta de pesquisa, criam um caminho mais lento e dois conjuntos de instruções que podem entrar em conflito. Elimine a duplicação e descreva a intenção.

Não tente adivinhar qual dos três problemas está a ocorrer. Execute o mesmo prompt duas vezes numa sessão nova: uma vez com a skill disponível e outra com a skill desativada. Depois, compare as respostas. A sessão nova é importante porque a sessão onde escreveu a skill já contém tudo o que ela diz, ocultando lacunas na versão escrita. O plugin skill-creator da Anthropic automatiza essa comparação no Claude Code, incluindo a geração de prompts que devem e não devem acionar a skill e a medição da frequência com que cada um o faz.

Este formato pertence a um fornecedor ou é um padrão?

A Anthropic publicou o formato no final de 2025 e, depois, lançou-o como um padrão aberto alojado em agentskills.io. Em agosto de 2026, essa especificação define os campos obrigatórios name e description, os campos opcionais license, compatibility, metadata e allowed-tools, os três diretórios opcionais e o comportamento de carregamento faseado. Também disponibiliza um validador de referência. Assim, skills-ref validate ./my-skill verifica uma pasta em relação à especificação antes de a partilhar.

A lista de clientes é o indicador mais relevante. A mesma pasta é lida por Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands e opencode, entre outros. A Microsoft publica as suas próprias skills neste formato em github.com/microsoft/skills e disponibiliza uma ferramenta para desktop chamada Skill Recorder. Essa ferramenta observa a execução de uma tarefa uma vez, reconstrói-a como uma intenção com passos ordenados e grava o resultado como uma skill. Quando um fornecedor cria um gravador cujo formato de saída pertence à especificação de outra entidade, isso indica que o formato deixou de ser uma funcionalidade exclusiva de um produto.

O que escrever primeiro

Não planeie uma biblioteca. Espere até se aperceber de que colou as mesmas instruções num chat pela terceira vez. Depois, mova esse texto para um SKILL.md e elimine a cópia. A repetição que já sentiu é o único indicador fiável de uma competência que vale a pena manter. Um procedimento de pesquisa é uma boa primeira opção, e uma competência de pesquisa baseada na sua própria instância SearXNG mostra como deve ser.

Dois hábitos mantêm a biblioteca saudável. Leia todas as competências que não escreveu antes de as instalar, incluindo os scripts, porque uma competência contém instruções que o seu agente seguirá e código que poderá executar. Trate-a como trataria a instalação de software de um desconhecido. Mantenha também as credenciais fora da pasta, porque uma competência é um ficheiro de texto que pode ser submetido a um repositório e partilhado. Manter os segredos afastados dos seus agentes explica onde esses valores devem ficar, e o roteiro para aprender sobre agentes este ano organiza as competências juntamente com o restante processo de configuração.

FAQ

Qual é a diferença entre uma competência de agente e um servidor MCP?

Um servidor MCP (model context protocol) é um processo em execução que expõe ferramentas a um agente através de um protocolo. Por isso, precisa de configuração e credenciais, e as definições das ferramentas normalmente ocupam contexto durante toda a sessão, sejam usadas ou não. Uma competência de agente é uma pasta que contém um ficheiro SKILL.md. Não tem processo nem protocolo e custa cerca de 100 tokens até o agente decidir lê-la. Use um servidor MCP para dar a um agente acesso a um sistema. Use uma competência para indicar ao agente o procedimento correto para utilizar esse acesso. Muitas configurações usam ambos.

As competências de agente funcionam apenas com Claude Code?

Não. A Anthropic desenvolveu o formato e depois publicou-o como padrão aberto em agentskills.io. A mesma pasta é lida por Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands e outros clientes. O que varia é a localização que cada cliente consulta e os campos adicionais de frontmatter que entende. O Claude Code lê ~/.claude/skills/ e .claude/skills/, enquanto o GitHub Copilot e o VS Code leem .github/skills/ no repositório. O ficheiro SKILL.md permanece inalterado entre eles.

Quantas competências posso instalar antes de o sistema ficar mais lento?

A limitação está no orçamento de arranque, não numa quantidade específica. Cada competência instalada contribui com o seu nome e descrição, aproximadamente 100 tokens segundo as orientações publicadas da especificação. Assim, trinta competências custam cerca de 3,000 tokens antes de qualquer uma ser usada. O primeiro problema é a correspondência, não a velocidade: muitas competências com descrições sobrepostas dificultam a escolha da competência correta pelo modelo. Escreva descrições que não se sobreponham e elimine as competências que deixou de usar.

Esta instrução deve ficar numa competência ou em AGENTS.md?

Verifique se ela se aplica a todas as tarefas do repositório. Os comandos de compilação, o estilo adotado pela equipa e as regras de nomenclatura aplicam-se a todas as tarefas. Por isso, devem ficar no ficheiro sempre carregado, pois o objetivo é carregá-lo em todas as execuções. Um procedimento executado ocasionalmente, como uma lista de verificação de uma release ou um teste de restauração, deve ser uma competência. Assim, não tem custo nas tarefas que nunca precisam dele. Uma secção de AGENTS.md que tenha crescido até conter passos numerados é normalmente uma competência que deve ser movida.