O que são Skills?

A origem do conceito

O termo apareceu cedo nos frameworks de agentes. Nas primeiras versões do Microsoft Semantic Kernel, por exemplo, "skill" era o nome dado a um conjunto de funções relacionadas que o agente podia executar.

Nesse modelo, cada função realizava uma tarefa atômica e bem definida, e a skill agrupava essas funções por assunto. Com a versão 1.0, o Semantic Kernel renomeou "skill" para "plugin", para alinhar o vocabulário ao que a comunidade de IA já usava.

O guia de migração oficial lista outras mudanças da mesma época. Por exemplo, "Semantic Function" virou "Prompt Function" e "Native Function" virou "Method Function".

O nome voltou com força em outubro de 2025, quando a Anthropic apresentou as Agent Skills. Dessa vez, a ideia mudou de foco: em vez de agrupar funções executáveis, a skill passou a empacotar instruções, referências e scripts em uma pasta.

Em dezembro de 2025, o formato virou uma especificação aberta, publicada em agentskills.io. Desde então, ferramentas como Claude, OpenAI Codex, GitHub Copilot, Cursor e VS Code adotaram o padrão.

O que são skills como arquivos de instrução

Na prática contemporânea, especialmente em ferramentas como o Claude Code, uma skill costuma ser representada por um arquivo SKILL.md. Esse arquivo contém instruções declarativas sobre como o modelo deve executar determinada tarefa.

Ele funciona como um "manual de estilo" que o agente lê antes de iniciar o trabalho. Assim, a saída mantém consistência e qualidade, mesmo quando pessoas diferentes fazem o pedido.

Uma comparação útil é o guia de integração de um novo funcionário.

A Anthropic usa exatamente essa analogia. Você não muda a pessoa, apenas entrega o conhecimento que ela precisa para trabalhar do jeito da equipe.

Se você usa o Claude Code no dia a dia, o guia completo do Claude Code mostra onde esses arquivos entram no fluxo de trabalho.

Estrutura típica de uma skill

Uma skill bem definida costuma conter os seguintes elementos:

• Nome e descrição: identificam quando o agente deve acionar a instrução
• Regras de escrita ou formatação: definem restrições e padrões de saída
• Exemplos ou templates: orientam o modelo com referências concretas
• Critérios de ativação: descrevem os gatilhos que devem disparar o uso

Essa estrutura permite que o agente selecione automaticamente a instrução mais adequada para cada solicitação do usuário.

expense-report/
├── SKILL.md                          # obrigatório: frontmatter + instruções
├── scripts/
│   └── validate.py                   # código que o agente pode executar
├── references/
│   └── POLICY_FAQ.md                 # documentos carregados sob demanda
└── assets/
    └── expense-report-template.md    # templates e recursos estáticos

# bloco delimitado por três hífens no início e no fim do SKILL.md
name: expense-report
description: File and validate employee expense reports according to company policy. Use when asked about expense submissions, reimbursement rules, or spending limits.
license: Apache-2.0
metadata:
  author: contoso-finance
  version: "2.1"

Divulgação progressiva: como o agente carrega skills

Carregar todas as instruções no contexto desde o início desperdiçaria tokens. Por isso, o padrão usa uma estratégia chamada divulgação progressiva (progressive disclosure), que a documentação oficial do Agent Framework descreve em quatro etapas.

1. Anunciar: o sistema injeta nome e descrição de cada instrução no prompt de sistema, com cerca de 100 tokens por item.
2. Carregar: quando a tarefa combina com o domínio, o agente chama a ferramenta load_skill para obter o corpo completo, idealmente com menos de 5000 tokens.
3. Ler recursos: se precisar de referências ou templates, o agente usa read_skill_resource.
4. Executar scripts: quando há código empacotado, o agente chama run_skill_script.

Dessa forma, a janela de contexto continua enxuta enquanto o agente mantém acesso a conhecimento profundo sob demanda. Em outras palavras, você pode instalar dezenas de pacotes de instruções sem pagar o custo de todos eles em cada requisição.

Vale notar um detalhe da implementação. A ferramenta load_skill sempre aparece para o modelo, mas read_skill_resource e run_skill_script só aparecem quando ao menos um pacote tem recursos ou scripts.

Com isso, o agente não recebe ferramentas inúteis, e o prompt de sistema fica ainda menor.

Esse mecanismo também explica por que a descrição importa tanto. Afinal, na primeira etapa ela é a única informação que o modelo vê para decidir se vale carregar o restante.

Exemplo de corpo de uma skill

Depois do frontmatter, vem o conteúdo que o agente realmente segue. Um corpo simples para a skill de relatórios de despesas poderia ser assim:

# Expense report

## When to use
Use this skill when the user asks to file, review or validate an expense report.

## Steps
1. Ask for the receipt date, amount, currency and category.
2. Read references/POLICY_FAQ.md to check the spending limits.
3. Run scripts/validate.py with the collected values.
4. Fill assets/expense-report-template.md with the validated data.

## Rules
- Never approve an expense above the category limit.
- Always answer with the filled template, never with free text.

Repare que o corpo aponta para os arquivos de apoio. Assim, o agente só lê a política ou executa o script quando chega ao passo correspondente.

Note também que as regras ficam explícitas e curtas. Dessa forma, o modelo encontra rapidamente o que pode e o que não pode fazer.

Boas práticas para escrever skills

Escrever uma boa instrução se parece mais com escrever documentação do que com escrever código. Ainda assim, alguns cuidados fazem diferença no resultado.

Primeiro, capriche na descrição. Ela deve dizer o que a instrução faz e em quais situações usá-la, com os termos que o usuário provavelmente vai digitar.

Em seguida, mantenha um foco por pacote. Uma instrução que tenta cobrir tudo confunde o modelo e gasta contexto sem necessidade.

Também prefira exemplos concretos a descrições abstratas. Um par de entrada e saída esperada costuma valer mais do que um parágrafo de explicação.

Além disso, mova o material extenso para a pasta references. O corpo principal fica curto, e o agente busca os detalhes apenas quando precisa.

Outro ponto importante é testar com pedidos reais. Faça a mesma solicitação várias vezes e confira se o agente aciona a instrução e respeita as regras.

Por fim, versione tudo no Git. Assim, cada mudança passa por revisão, e você consegue voltar atrás quando um ajuste piora o comportamento.

Skills como mecanismo de especialização

Uma das principais vantagens desse modelo é especializar o comportamento do agente sem alterar o modelo base.

Em vez de retreinar ou ajustar o modelo, o desenvolvedor simplesmente escreve um novo arquivo de instrução e o registra no repositório disponível. Com isso, o sistema fica altamente extensível e de fácil manutenção.

Por exemplo, uma equipe pode ter uma instrução para revisar pull requests segundo o guia de estilo da empresa e outra para gerar notas de versão. O mesmo agente atende às duas demandas, porque carrega apenas o conhecimento relevante para cada pedido.

O artigo sobre a skill do time .NET para agentes de IA mostra um caso real dessa especialização aplicada ao desenvolvimento.

O que são skills no contexto de agentes autônomos

Em arquiteturas de agentes mais avançadas, como as baseadas no Microsoft Agent Framework ou no protocolo MCP (Model Context Protocol), você pode compor e encadear essas instruções.

Assim, um agente orquestrador seleciona e combina vários pacotes de instruções para resolver tarefas complexas. Isso vale especialmente quando a tarefa exige diferentes formas de raciocínio ou diferentes formatos de saída.

O MCP, aliás, também serve como canal de distribuição. No Agent Framework, um servidor MCP pode anunciar skills sob o esquema skill://, e o framework busca o conteúdo sob demanda.

Para entender como agentes funcionam antes de combinar instruções, leia o artigo sobre o que são agents.

Diferença entre skill e tool

É importante distinguir as duas coisas. Uma tool é uma função executável que o agente pode invocar para interagir com sistemas externos, como APIs, bancos de dados ou sistemas de arquivos.

Uma skill, por sua vez, é um conjunto de instruções que orienta o raciocínio e o comportamento do agente. Ou seja, a tool executa ações, enquanto a skill orienta como pensar e como produzir o resultado.

As duas peças se complementam. Uma instrução pode, inclusive, ensinar o agente a usar determinadas ferramentas na ordem certa ou trazer scripts próprios para executar.

Se você quer comparar as abordagens em mais detalhe, o artigo agents ou skills: qual escolher aprofunda essa decisão.

Usando skills no .NET com o Agent Framework

No .NET, o Microsoft Agent Framework oferece suporte nativo ao formato. O componente central é o AgentSkillsProvider, um provedor de contexto que anuncia as instruções disponíveis e registra as ferramentas de carregamento.

O exemplo a seguir descobre pacotes de instruções na pasta skills e os entrega a um agente:

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using OpenAI.Responses;

string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

// Descobre as skills a partir da pasta "skills"
var skillsProvider = new AgentSkillsProvider(
    Path.Combine(AppContext.BaseDirectory, "skills"));

// Cria o agente com o provedor de skills como contexto
AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetResponsesClient()
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "SkillsAgent",
        ChatOptions = new()
        {
            Instructions = "You are a helpful assistant.",
        },
        AIContextProviders = [skillsProvider],
    },
    model: deploymentName);

Além de arquivos, o framework aceita instruções definidas em código com AgentInlineSkill, em classes que herdam de AgentClassSkill<T> e em servidores MCP. O AgentSkillsProviderBuilder combina essas fontes e ainda permite filtrar apenas as instruções aprovadas.

Para ver o mesmo conceito aplicado a ferramentas de desenvolvimento, leia sobre Agent Skills no Visual Studio.

Segurança ao adotar skills

Como as instruções entram direto no contexto do agente e podem trazer scripts, a Microsoft recomenda tratá-las como qualquer código de terceiros.

Primeiro, leia todo o conteúdo antes de usar, incluindo scripts e referências, e procure instruções maliciosas. Em seguida, instale apenas pacotes de autores confiáveis e desconfie de nomes parecidos com os de pacotes populares.

Também execute scripts em ambientes isolados, com acesso mínimo a arquivos e rede.

Além disso, defina limites de CPU, memória e tempo, e mantenha uma lista de scripts permitidos. Na mesma linha, peça confirmação explícita do usuário antes de qualquer operação sensível.

Por fim, registre quais instruções o agente carregou e quais scripts executou, para ter uma trilha de auditoria.

Quando algo der errado, esse registro permite ligar o comportamento do agente a um trecho específico de instrução. Dessa forma, a correção fica muito mais rápida e segura.

Skills e qualidade de saída

A adoção de arquivos de instrução representa uma evolução significativa na engenharia de prompts.

Em vez de prompts longos e difíceis de manter embutidos no código, você pode versionar, testar e melhorar as instruções de forma independente. Assim, práticas de engenharia de software passam a valer também para o desenvolvimento de agentes de IA.

Na prática, isso significa revisar mudanças em pull requests, comparar versões e medir o efeito de cada ajuste. O artigo sobre dez evals para agentes de IA ajuda a montar essa medição.

Considerações finais

Saber o que são skills ajuda a construir agentes de IA confiáveis e especializados, porque elas viraram um dos pilares dessa construção.

Ao encapsular conhecimento de domínio em unidades reutilizáveis e bem documentadas, essas instruções permitem que desenvolvedores construam sistemas com comportamento previsível, rastreável e fácil de evoluir ao longo do tempo.

FAQ

Skill e prompt são a mesma coisa?

Não exatamente. A skill é um pacote versionável de instruções, com metadados e recursos, que o agente carrega apenas quando a tarefa exige.

Preciso programar para criar uma skill?

Não. O mínimo é uma pasta com um arquivo SKILL.md contendo frontmatter e instruções em markdown.

Skills funcionam só com o Claude?

Não. O formato virou especificação aberta, e ferramentas como GitHub Copilot, VS Code, Cursor e OpenAI Codex também o adotaram.

Qual a diferença entre skill e plugin no Semantic Kernel?

No Semantic Kernel, "skill" era o nome antigo do que hoje se chama plugin, um conjunto de funções executáveis. Já as Agent Skills atuais são pacotes de instruções.

Skills substituem o MCP?

Não. O MCP conecta o agente a ferramentas e dados, enquanto a skill ensina como trabalhar, e os dois podem atuar juntos.