O que é uma skill de agente e como ela funciona

O que uma skill de agente realmente é

Uma skill de agente é uma pasta no disco que contém 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 skills resulta destas 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 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 explicar o que a skill 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 justifica compreender o formato. O tema é o contexto, não as funcionalidades. O carregamento ocorre por etapas. A especificação chama a isso 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 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 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, pelo que 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 prompt de sistema 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 ou não. Também compete pela atenção com a pergunta real. Dez mil tokens de instruções permanentes são um custo pago 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. Esse é todo o argumento a favor das skills. É 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 skill 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 a estrutura 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 interação pertencem a o harness, o programa que executa o ciclo em torno do modelo, que também é o componente que lê as descrições das suas skills no arranque e decide quando abrir uma.

Uma skill não executa nada por si só. O agente lê-a e age 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. O que uma skill pode fazer é indicar ao modelo quais ferramentas deve utilizar, em que ordem e o que deve verificar depois. Delegar uma tarefa a um segundo agente é o exemplo mais claro: uma sessão do Claude Code já pode enviar mensagens a outra, e é na skill que se regista quando isso vale a pena e o que deve ser enviado.

Em resumo: uma ferramenta dá ao agente uma nova capacidade, enquanto uma skill lhe dá critérios para utilizar uma capacidade que já possui. Se uma etapa tiver de produzir sempre um resultado exato e validado, deve usar uma ferramenta ou um script. Se uma etapa exigir a aplicação consistente do mesmo raciocínio, deve usar uma skill. Uma skill pode consistir apenas em critérios e, ainda assim, ser a opção a que mais recorre, como mostra Ponytail, que leva um agente de programação a fazer a alteração mínima que funciona: não adiciona nenhuma capacidade e apenas muda a forma como o agente utiliza as capacidades que já tem. Esses critérios também podem apontar noutra direção, e a skill unlazy, que percorre uma Depth Tree para impedir que um agente declare uma tarefa concluída demasiado cedo aplica o mesmo princípio à exaustividade, 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 com um ficheiro Markdown. Não existe processo, porta ou 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 é 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 para o fluxo de trabalho real da sua equipa, em que ordem e qual deve ser o resultado esperado. 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 versionadas no git, para que todas as pessoas e todos os agentes que trabalham nesse repositório tenham acesso a elas. O GitHub Copilot e o VS Code leem as skills do workspace a partir de .github/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, portanto, neste caso, é /restore-drill. No Claude Code, o menu /skills mostra 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 chamar-se SKILL.md, e o nome do diretório tem de usar letras minúsculas, dígitos e hífenes simples. O mesmo processo, escrito como um procedimento que o seu agente pode executar novamente, é um complemento natural para backups agendados do restic num VPS, onde 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 é o formato 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 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, 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 sinal mais relevante. A mesma pasta é lida, entre outros, pelo 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 monitoriza 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 indício 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 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, sem 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 usar 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 muda é o local onde cada cliente procura as competências e os campos adicionais de frontmatter que entende. Claude Code lê ~/.claude/skills/ e .claude/skills/, enquanto GitHub Copilot e VS Code leem .github/skills/ no repositório. O próprio ficheiro SKILL.md pode ser transferido entre esses clientes sem alterações.

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 na especificação. Assim, trinta competências custam cerca de 3,000 tokens antes de qualquer uma ser usada. O que se degrada primeiro é 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.

Devo colocar esta instrução numa competência 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, porque o objetivo é carregá-lo em todas as execuções. Um procedimento usado ocasionalmente, como uma checklist de 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 cresceu até conter passos numerados é normalmente uma competência que deve ser movida.