Agent Skills

As competências de agentes são pastas com instruções, scripts e ficheiros de referência que dão a um agente de IA conhecimentos especializados para um determinado tipo de tarefa, num formato que o agente só carrega quando a tarefa o exige. Cada competência centra-se num ficheiro SKILL.md cuja breve descrição indica ao agente quando deve usá-la e cujo conteúdo explica como. A Anthropic introduziu as competências de agentes para o Claude em outubro de 2025 e publicou o formato como norma aberta em agentskills.io em dezembro de 2025. Claude Code, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot, VS Code e dezenas de outros agentes leem agora as mesmas pastas, pelo que uma única competência funciona em todos.

Como funcionam as Agent Skills#

Uma competência é um diretório com o nome da competência, que contém o ficheiro obrigatório SKILL.md e as pastas opcionais scripts/, references/ e assets/. O ficheiro SKILL.md começa com metadados YAML que contêm dois campos obrigatórios: um campo name que corresponde ao nome do diretório e aceita até 64 caracteres compostos por letras minúsculas, algarismos e hífenes, e um campo description com até 1.024 caracteres que descreve o que a competência faz e quando a utilizar. O corpo Markdown que se segue contém o procedimento, exemplos e casos-limite.

Os agentes carregam competências através da divulgação progressiva, o que permite manter uma grande biblioteca de competências a baixo custo. No arranque, o agente lê apenas o nome e a descrição de cada competência, cerca de 100 tokens por competência. Quando um pedido corresponde a uma descrição, o agente lê o SKILL.md completo para a sua janela de contexto; a especificação recomenda manter esse conteúdo abaixo de 500 linhas e 5.000 tokens. Os scripts e ficheiros de referência só são carregados quando as instruções os indicam, e o código de um script nunca entra no contexto se o agente simplesmente o executar e ler os resultados.

Anatomia de um SKILL.md#

Uma equipa de retalho pode dar ao seu agente esta competência para fotografias de prateleiras. A descrição inclui as palavras que ativam a competência e que o agente procura, enquanto o corpo indica um script e uma tabela de referência que só são carregados quando necessário:

---
name: shelf-audit
description: Counts products and finds empty facings in retail shelf photos. Use when the user asks about stock levels, gaps, or planogram compliance in store images.
---

# Shelf audit

1. Run `python scripts/detect_products.py <image>` on each photo. It prints one JSON line per product with its class, confidence, and box.
2. Compare the counts with the expected facings in `references/planogram.csv`.
3. Report each empty facing with its shelf position.
4. Send detections below 0.5 confidence to a person for review instead of counting them.

O agente só vê as duas linhas dos metadados até alguém perguntar sobre prateleiras, e só abre o ficheiro do planograma no passo 2.

Agent Skills versus conceitos relacionados#

• Ferramentas e invocação de funções: Uma ferramenta é uma operação que o agente pode invocar, como uma consulta a uma base de dados ou um modelo de deteção de objetos. Uma competência ensina o agente quando e como combinar ferramentas para uma tarefa, incluindo regras de validação e contexto do domínio que as ferramentas não possuem.
• Model Context Protocol (MCP): Liga um agente a sistemas externos em tempo real através de servidores. As competências fornecem conhecimentos procedimentais, pelo que os agentes costumam usar ambos: uma competência pode indicar ao agente que ferramentas MCP chamar e por que ordem.
• Prompts de sistema e instruções de projeto: Ficheiros como AGENTS.md são carregados em todas as sessões. O corpo de uma competência só é carregado para tarefas correspondentes, pelo que um agente pode ter centenas de competências sem sobrecarregar o seu contexto, que é a ideia central da engenharia de contexto.
• Ajuste fino: Altera os pesos de um modelo para lhe ensinar um comportamento. Uma skill altera apenas o contexto, por isso pode ser editada, versionada e revista como código, e entra em vigor imediatamente.

Skills na prática#

As skills reúnem conhecimentos que um modelo de linguagem de grande escala (LLM) geral não tem ou aplica de forma inconsistente: regras de marca da empresa, a lista de verificação de lançamento de uma equipa ou as particularidades de um formato de ficheiro. O repositório público de skills da Anthropic inclui as skills de Word, PDF, PowerPoint e Excel que alimentam a criação de documentos do próprio Claude. As Agent Skills da Ultralytics abrangem o ciclo de vida da visão computacional: uma skill de encaminhamento yolo direciona cada pedido para uma skill de seleção de modelos, conjuntos de dados, treino, ajuste, inferência ou exportação, e uma skill platform-cli automatiza a Ultralytics Platform com a linha de comandos ul cloud. O assistente Ask AI da própria Platform usa essa skill platform-cli, e as mesmas pastas podem ser instaladas no Claude Code com claude plugin install yolo@ultralytics ou noutros agentes com npx skills add ultralytics/skills, o que permite a uma ferramenta de programação agêntica treinar e exportar um modelo YOLO26 a partir de um pedido em linguagem natural.

Considerações de segurança#

Uma skill é executada com as permissões do agente, por isso instalar uma skill de terceiros é semelhante a instalar software. As instruções da skill podem conter uma injeção de prompt que redireciona o agente, e os respetivos scripts podem ler ficheiros ou enviar dados para qualquer destino permitido pelo ambiente do agente. As equipas analisam as instruções, os scripts e as dependências de uma skill antes de a instalar, fixam as versões e executam os scripts da skill dentro de uma sandbox de agente com acesso limitado à rede. A especificação também define um campo experimental allowed-tools, uma lista separada por espaços, como Bash(git:*) Read, que indica as ferramentas que uma skill pode executar sem pedir autorização, e os agentes que suportam o campo pré-aprovam essas ferramentas no seu ambiente de execução de agentes.