O que são agent skills e como elas funcionam

O que uma skill de agente realmente é

Uma skill de agente é uma pasta no disco com um ficheiro chamado SKILL.md. Esse ficheiro contém um nome, uma descrição curta e instruções escritas em Markdown simples. O agente carrega a descrição no arranque e lê as instruções apenas quando o pedido corresponde a essa descrição ou quando a skill é invocada pelo nome. Quase tudo o resto relacionado com skills resulta 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 o código que o agente executa, references/ para os documentos que lê quando precisa deles e assets/ para modelos e dados. Nenhum deles é obrigatório. Uma pasta que contenha apenas um SKILL.md já é uma skill completa.

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

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

Por que uma skill quase não custa nada até ser usada

Este é o argumento que torna este formato útil, e está relacionado com o contexto, não com funcionalidades. O carregamento ocorre por etapas, num processo que a especificação chama 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 outubro 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 esse conteúdo abaixo de 5.000 tokens e o ficheiro abaixo de 500 linhas. Os ficheiros em references/ e scripts/ continuam sem qualquer 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 forma diferente: o agente executa-o através da shell, por isso o código-fonte do script nunca entra na janela de contexto; apenas o resultado da execução é carregado.

Compare isto com a opção que as pessoas costumam escolher 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, mesmo quando a tarefa não precisa dela, e 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 as horas. Uma dúzia de skills custa cerca de 1.200 tokens em repouso e só aumenta para a tarefa que precisa delas. Este é todo o argumento a favor das skills e explica por 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 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 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. As duas partes dessa troca pertencem ao harness, o programa que executa o ciclo em torno do modelo, que também é o componente que lê as descrições das skills no arranque e decide quando abrir uma.

Uma skill não executa nada por si própria. O agente lê-a e depois atua usando as ferramentas que já tinha. 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. Entregar uma tarefa a um segundo agente é o exemplo mais claro: uma sessão do Claude Code já pode enviar mensagens a outra, e a skill é o local onde se regista quando vale a pena fazer isso e o que enviar.

Em resumo: uma ferramenta dá ao agente uma nova capacidade, enquanto uma skill lhe dá sobretudo critérios para usar capacidades que já possui. Quando uma skill adiciona uma capacidade, fá-lo através de um script incluído que o agente executa com a shell que já tinha. Se uma etapa tiver de produzir sempre um resultado exato e validado, deve usar uma ferramenta ou um script. Se uma etapa exigir aplicar o mesmo raciocínio de forma consistente, deve usar uma skill. Uma skill pode consistir apenas em critérios e, ainda assim, ser aquela a que mais recorre, como mostra a Ponytail, que orienta 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 usa as capacidades que já possui. Esses critérios também podem apontar na direção oposta, e a skill unlazy, que percorre uma Depth Tree para impedir que um agente declare uma tarefa concluída demasiado cedo aplica a mesma técnica para promover o rigor em vez da contenção.

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 endpoint de rede. Uma skill é uma pasta que contém um ficheiro Markdown. Não existe processo, porta nem protocolo.

O custo de contexto é diferente da mesma forma. Cada ferramenta exposta por um servidor MCP inclui um nome, uma descrição e um esquema de argumentos. Num cliente que as carregue antecipadamente, esses dados permanecem no pedido durante toda a sessão, sejam usados ou não. O Claude Code já não funciona assim por predefinição: desde October 2026, a pesquisa de ferramentas está ativa por defeito, pelo que apenas os nomes das ferramentas e as instruções do servidor são carregados no início da sessão. As definições completas são carregadas quando o Claude as pesquisa. Uma skill em repouso ocupa 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, por 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 aptidão de agente não é um prompt do sistema nem um AGENTS.md

Ambas são instruções em Markdown, por isso esta confusão é compreensível. A diferença está no momento em que são carregadas. AGENTS.md, CLAUDE.md e o prompt do sistema estão sempre ativos. Uma skill é carregada sob demanda. Os estilos de saída do Claude Code ficam no extremo do que está sempre ativo, porque escolher um altera o próprio prompt do sistema. Por isso, influencia todas as respostas da sessão, incluindo as que nenhuma skill chega a processar.

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, em que o objetivo é ser carregado sempre. 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 aptidão. 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 convém seguir corretamente. Consulte o que deve ficar no AGENTS.md e o que deve ficar no ficheiro humano 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 submetidas ao git, por isso todas as pessoas e todos os agentes que trabalham nesse repositório têm acesso a elas. O GitHub Copilot e o VS Code leem as skills do projeto a partir de .github/skills/ e .agents/skills/, bem como de .claude/skills/. O ficheiro no interior é 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, comece por verificar os nomes: o ficheiro tem de se chamar SKILL.md, e a especificação Agent Skills exige que o nome use letras minúsculas, dígitos e hífenes simples, correspondendo ao diretório. O mesmo procedimento, escrito para que o agente o possa executar novamente, é um complemento natural para 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. A competência deve limitar-se a algumas linhas que indiquem quando o executar e como interpretar o resultado. 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 o seu resultado, enquanto a mesma lógica escrita como instruções Markdown custa todo o seu tamanho sempre que a competência é carregada.

Segundo, um script produz a mesma resposta duas vezes. Um modelo ao qual seja pedido que deduza novamente a mesma regra de análise de logs em cada execução pode obter resultados ligeiramente diferentes num dia menos favorável. O problema só será detetado quando dois números não coincidirem.

Por isso, divida o trabalho por tipo. "Analisar o CSV e imprimir todas as linhas cujo total não corresponde aos itens da linha" é um script. "Analisar 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 que criar um ciclo que um agente possa executar sem a sua supervisão.

Porque é que a minha skill nunca é ativada?

Porque o seu description diz o que a skill faz, mas nunca diz quando deve ser utilizada. Essa linha é tudo o que o agente tem para comparar com o seu pedido. "Ajuda com tarefas de bases 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 é ativada.

O problema oposto é a skill que é ativada 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 cada tarefa 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. Isso impede o carregamento automático e mantém a skill disponível quando escreve o seu nome.

O terceiro problema é a skill que duplica uma ferramenta. As instruções que dizem ao agente para curl uma API que o seu servidor MCP já expõe, 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 tem. Execute o mesmo prompt duas vezes numa sessão nova: uma vez com a skill disponível e outra vez com ela desativada. Depois compare as respostas. A sessão nova é importante, porque a sessão onde escreveu a skill já contém tudo o que a skill diz, ocultando lacunas na versão escrita. O plugin skill-creator da Anthropic automatiza essa comparação no Claude Code. Também gera prompts que devem e não devem ativar a skill e mede a frequência de cada caso. Se a skill for carregada e o agente continuar a não fazer o que ela diz, a descrição não é o problema. Nesse caso, consulte as razões pelas quais um agente ignora instruções que já leu.

Este formato é proprietário de 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 outubro 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, pelo que skills-ref validate ./my-skill verifica uma pasta de acordo com a especificação antes de a partilhar.

A lista de clientes é o indicador 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 de ambiente de trabalho chamada Skill Recorder, que observa a execução de uma tarefa, reconstrói-a como uma intenção com 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 apanhar a colar as mesmas instruções numa conversa pela terceira vez. Depois, mova esse texto para um SKILL.md e elimine a colagem. A repetição que já sentiu é o único sinal fiável de que uma competência merece ser mantida. Um procedimento de pesquisa é uma boa primeira opção. Uma competência de pesquisa baseada na sua própria instância do SearXNG mostra a estrutura.

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. Uma competência contém instruções que o agente seguirá e código que poderá executar. Trate-a como trataria a instalação de software de uma pessoa desconhecida. Mantenha também as credenciais fora da pasta. 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 colocar esses valores. O roteiro para aprender sobre agentes este ano organiza as competências juntamente com o resto da 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 completas das ferramentas ocupam contexto durante toda a sessão, a menos que o cliente adie o seu carregamento, como o Claude Code faz agora por predefinição. Uma skill de agente é uma pasta que contém um ficheiro SKILL.md. Não tem processo nem protocolo. 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 usar esse acesso. Muitas configurações usam ambos.

As skills de agente funcionam apenas com o Claude Code?

Não. A Anthropic desenvolveu o formato e depois publicou-o como padrão aberto em agentskills.io. A mesma pasta é lida pelo 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. O Claude Code lê ~/.claude/skills/ e .claude/skills/. O GitHub Copilot e o VS Code leem .github/skills/, .claude/skills/ ou .agents/skills/ no repositório. O próprio ficheiro SKILL.md pode ser transferido entre esses clientes sem alterações.

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 usada. 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 usar.

Esta instrução deve ficar numa skill ou em AGENTS.md?

Pergunte 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, que existe precisamente para ser carregado em todas as execuções. Um procedimento usado ocasionalmente, como uma checklist de release ou um teste de restauração, deve ser uma skill. Assim, custa apenas a sua descrição de uma linha nas tarefas que não precisam dele. Uma secção de AGENTS.md que cresceu até conter passos numerados é normalmente uma skill que deve ser movida.