O que são agent skills de verdade?

O que uma competência de agente realmente é

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 sobre competências decorre dessas duas frases.

A pasta pode conter mais do que um ficheiro. A especificação Agent Skills define três diretórios opcionais: scripts/ para o código que o agente executa, references/ para os documentos que lê 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 tende a 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 realmente escreveria.

Por que uma skill custa quase nada até ser usada

Este é o argumento que torna o formato digno de ser compreendido. O assunto é o contexto, não as funcionalidades. O carregamento ocorre por etapas, o que a especificação chama de divulgação progressiva.

Na inicialização, o agente carrega o name e o description de cada skill instalada, e nada mais. A especificação Agent Skills estima esse conteúdo 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 corpo desse único SKILL.md. A especificação recomenda manter o corpo abaixo de 5.000 tokens e o ficheiro abaixo de 500 linhas. Os ficheiros em references/ e scripts/ continuam sem custo neste momento. 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, portanto o código-fonte do script nunca entra na janela de contexto; apenas a saída entra.

Compare isto com a opção a que as pessoas recorrem primeiro: um prompt enorme. Cada linha de um system prompt ou de um ficheiro de instruções sempre ativo é contabilizada em todos os pedidos e em todas as sessões, quer a tarefa precise dela quer não. Além disso, essa linha compete pela atenção com a pergunta real. 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 delas. Este é todo o argumento a favor das skills e é por isso que uma biblioteca pequena é melhor do que um prompt mais longo.

Há uma ressalva que costuma causar problemas. Depois de uma skill ser carregada, o seu corpo 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 competência do 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 o formato dos argumentos. O modelo emite uma chamada, o seu código executa-a e o resultado regressa como uma mensagem. As ferramentas executam ações.

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

Em resumo: uma ferramenta dá ao agente uma nova capacidade, enquanto uma competência lhe dá critérios para utilizar uma capacidade que já possui. Se um passo tiver de produzir sempre um resultado exato e validado, deverá utilizar uma ferramenta ou um script. Se um passo exigir a aplicação consistente do mesmo raciocínio, deverá utilizar uma competência.

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 nenhum processo, nenhuma porta nem nenhum 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 permanecem no pedido durante toda a sessão, sejam usados ou não. Alguns clientes começaram a obter os esquemas das ferramentas a pedido, mas carregá-los no início continua a ser o comportamento normal. Uma skill armazenada ocupa uma linha de texto.

As duas opções são complementares, e as configurações mais eficazes usam ambas. O servidor MCP fornece o acesso. A skill fornece o procedimento: quais dessas ferramentas chamar no 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 aborda esse lado.

Uma competência de um agente não é um prompt do sistema nem um AGENTS.md

Ambos são instruções em Markdown, por isso é compreensível confundi-los. A diferença está no momento em que são carregados. AGENTS.md, CLAUDE.md e o prompt do sistema estão sempre ativos. Uma competência é ativada conforme necessário.

O teste consiste numa pergunta: ignorar este parágrafo estaria errado numa tarefa sem qualquer relação com ele? O padrão de estilo do projeto, 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 em todas as execuções. A lista de verificação de release que executa duas vezes por mês não se aplica a todas as tarefas. Por isso, pertence a uma competência. Quando uma secção do ficheiro sempre ativo se transforma num procedimento numerado, esse é o sinal de que deve movê-la.

Esses ficheiros também têm convenções próprias que vale a pena seguir corretamente. Consulte o que deve pertencer ao AGENTS.md e o que deve pertencer ao ficheiro para humanos e um design.md que explica a estrutura de uma base de código para conhecer os dois 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, por isso todas as pessoas e todos os agentes que trabalham nesse repositório as têm. O GitHub Copilot e o VS Code leem as skills do workspace a partir de .github/skills/. O ficheiro é 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 escreve, por isso esta é /restore-drill. No Claude Code, o menu /skills apresenta o que está instalado. É 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 conter apenas letras minúsculas, dígitos e hífenes simples. O mesmo procedimento, escrito de forma que o seu agente o possa repetir, é um complemento natural de backups agendados do restic num VPS, porque executar o backup não é o mesmo que restaurá-lo.

Quando uma skill deve ser um script

Qualquer passo que tenha sempre uma única resposta correta deve ser um script, reduzindo a skill 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 custa apenas a saída, enquanto a mesma lógica escrita como instruções em Markdown custa todo o seu comprimento sempre que a skill é carregada.

Segundo, um script fornece a mesma resposta duas vezes. Um modelo solicitado a deduzir novamente a mesma regra de análise de logs em cada execução pode produzir uma versão ligeiramente diferente num dia menos previsível, e isso só será percebido quando dois números não coincidirem.

Por isso, separe o trabalho por tipo. "Analisar o CSV e imprimir cada linha em que o total não corresponde aos itens da linha" é uma tarefa para um script. "Observar as linhas impressas pelo script e explicar quais parecem resultar de um erro de introdução de dados" é uma instrução de skill. Manter o julgamento em Markdown e o comportamento determinístico no código é a mesma disciplina de criar um loop que um agente possa executar sem a sua supervisão.

Por que minha skill nunca é acionada?

Porque o description diz o que a skill faz, mas nunca diz quando ela deve ser usada. Essa única linha é tudo o que o agente tem para comparar com o seu pedido. "Ajuda com tarefas de banco de dados" não corresponde a nada específico. "Executa uma migração de esquema no banco de dados de staging. Use quando o usuário pedir para migrar uma tabela, adicionar uma coluna ou alterar um esquema" contém as palavras que uma pessoa realmente digita, por isso é acionada.

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

O terceiro problema ocorre quando a skill duplica uma ferramenta. Instruções para o agente curl uma API que o servidor MCP já expõe, ou para pesquisar arquivos com grep quando o harness tem uma ferramenta de pesquisa, criam um caminho mais lento e dois conjuntos de instruções que podem entrar em conflito. Remova a duplicação e descreva a intenção.

Não tente adivinhar qual dos três problemas está ocorrendo. Execute o mesmo prompt duas vezes em uma sessão nova: uma vez com a skill disponível e outra com ela desativada. Depois, compare as respostas. A sessão nova é importante porque a sessão em que você escreveu a skill já contém tudo o que ela diz. Isso oculta lacunas na versão escrita. O plugin skill-creator da Anthropic automatiza essa comparação dentro do Claude Code. Ele também gera prompts que devem e não devem acionar a skill e mede a frequência de cada caso.

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 inclui um validador de referência, por isso skills-ref validate ./my-skill verifica uma pasta de acordo com a especificação antes de a partilhar.

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

O que escrever primeiro

Não planeie uma biblioteca. Espere até se dar conta de que está a colar as mesmas instruções numa conversa pela terceira vez. Depois, mova esse texto para um SKILL.md e elimine a cópia colada. 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 do SearXNG mostra o formato.

Duas práticas 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 guardar esses valores, 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 skill 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. As definições das ferramentas normalmente ocupam contexto durante toda a sessão, sejam utilizadas ou não. Uma skill de agente é uma pasta que contém um ficheiro SKILL.md. Não envolve processos nem protocolos 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 skill para indicar ao agente o procedimento correto para utilizar esse acesso. Muitas configurações usam ambos.

As skills de agente funcionam apenas com Claude Code?

Não. A Anthropic desenvolveu o formato e depois publicou-o como um 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 é o local que cada cliente consulta e os campos adicionais de frontmatter que compreende. Claude Code lê ~/.claude/skills/ e .claude/skills/, enquanto GitHub Copilot e VS Code leem .github/skills/ no repositório. O ficheiro SKILL.md permanece inalterado entre esses clientes.

Quantas skills posso instalar antes de o desempenho diminuir?

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

Devo colocar esta instrução numa skill 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 ativo, cujo objetivo é ser carregado 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 skill. Assim, não tem custo nas tarefas que nunca precisam dele. Uma secção de AGENTS.md que cresceu até conter passos numerados é normalmente uma skill que deve ser movida.