Skills em pacotes NuGet: como entregar skills para agentes
Skills em pacotes NuGet são arquivos SKILL.md distribuídos dentro do próprio pacote, ao lado das bibliotecas, para ensinar agentes de IA a usar aquela dependência na versão exata instalada no projeto. A proposta foi apresentada por Richard Lander no blog oficial do .NET e aproveita o dotnet restore para entregar esse conhecimento no momento em que o agente precisa dele.
Neste conteúdo você vai entender o problema que essa abordagem resolve, como o formato funciona, quais ferramentas já existem para descobrir as skills e o que a equipe do .NET aprendeu nos testes com modelos diferentes.
O que são skills em pacotes NuGet
As agent skills foram introduzidas pela Anthropic em 2025 e rapidamente se tornaram comuns no desenvolvimento assistido por IA. Em resumo, uma skill é um conjunto de instruções em markdown que o agente carrega quando a tarefa pede aquele conhecimento.
Normalmente, essas skills são distribuídas por repositórios Git. Por exemplo, o repositório dotnet/skills e a coleção Impeccable skills seguem esse modelo.
A ideia de skills em pacotes NuGet muda apenas o veículo de distribuição. Em outras palavras, o mesmo arquivo SKILL.md passa a viajar dentro do pacote, junto com as DLLs que ele documenta.
Segundo Lander, o ponto em comum é simples: repositórios e pacotes são unidades de desenvolvimento, e por isso ambos podem servir como meio de entrega de skills.
Um exemplo concreto é o pacote Markout, que já publica um conjunto de skills. A listagem abaixo mostra os arquivos encontrados dentro dele:
$ dotnet-inspect package markout -S Skills
path size
skills/markout-built-in-shapes/SKILL.md 9457
skills/markout-composite-cells-cards/SKILL.md 6764
skills/markout-conditional-composition/SKILL.md 4978
skills/markout-output-formats/SKILL.md 7744
skills/markout/SKILL.md 8551
Repare que cada skill fica em uma pasta própria dentro de skills/, com um único arquivo SKILL.md. Dessa forma, o pacote pode oferecer uma skill geral e outras mais específicas para cada cenário de uso.
Por que entregar skills em pacotes NuGet
As skills resolvem dois problemas principais. Primeiro, elas preenchem lacunas no conhecimento do modelo. Além disso, elas prescrevem o jeito da equipe de executar uma tarefa.
Esse primeiro problema explica o valor das skills em pacotes NuGet. Afinal, uma versão publicada há cinco minutos, com APIs novas, não faz parte do treinamento de nenhum modelo.
Contudo, o desafio não se limita aos pacotes recentes. Os registros de pacotes também têm uma cauda muito longa, e é bem provável que os modelos não saibam nada relevante sobre a maioria deles.
Por outro lado, existe uma oportunidade clara. Como as skills ficam junto dos binários, cada versão do pacote pode trazer instruções feitas sob medida para aquela versão.
Na prática, isso funciona de forma parecida com o README.md que muitos pacotes já incluem. A diferença está no propósito e no consumidor, porque o README foi pensado para pessoas e a skill foi pensada para agentes.
O custo de deixar o agente descobrir sozinho
A equipe do .NET fez muitos experimentos antes de chegar a essa proposta. Nesses testes, os agentes mostraram que conseguem, por conta própria, encontrar conteúdo no cache do NuGet para aprender sobre um pacote.
Isso inclui ler os arquivos README.md e até escrever programas descartáveis que fazem reflexão sobre os metadados dos assemblies. Os agentes com modelos de fronteira se mostraram muito criativos nessa investigação.
No entanto, essa criatividade não sai de graça. A pergunta central, segundo Lander, é se o agente deve gastar esforço fazendo engenharia reversa da documentação ou resolvendo o problema de negócio do desenvolvedor.
Esse dilema pesa ainda mais quando o uso precisa caber em um orçamento mensal de tokens. Portanto, entregar a documentação pronta, no formato que o agente entende, foi o problema que a equipe decidiu atacar.
O formato SKILL.md
Uma skill é um arquivo markdown com um cabeçalho YAML, sempre chamado SKILL.md. A especificação oficial do formato fica no site agentskills.io, e as skills em pacotes NuGet usam exatamente o mesmo formato.
O cabeçalho traz pelo menos o name e a description. Em seguida, o corpo descreve em markdown o que o agente deve fazer.
O exemplo abaixo, publicado no artigo original, orienta o agente a verificar dependências vulneráveis de um projeto:
---
name: vulnerable-nuget-package-check
description: Check a .NET project for vulnerable NuGet packages dependencies.
---
The .NET SDK includes a `dotnet package` command, which can list vulnerable direct or indirect package dependencies for a given .NET project.
Run the following command for a project:
```bash
dotnet package list --vulnerable --include-transitive
```
Update vulnerable package references to patched versions.
A description merece atenção especial. Afinal, é ela que o agente lê para decidir se aquela skill serve para a tarefa atual.
O comando citado na skill existe no SDK do .NET e está descrito na documentação do dotnet package list. Vale notar que o argumento --include-transitive não vem ativado por padrão, por isso a skill o informa explicitamente.
Se você ainda não conhece o formato a fundo, o artigo sobre agent skills no Visual Studio explica o carregamento progressivo e a estrutura de pastas em detalhes.
Como as skills são distribuídas hoje
Antes de entender as skills em pacotes NuGet, vale olhar para os dois caminhos convencionais. Ambos usam repositórios Git, mas com objetivos diferentes.
Skills no repositório de código
A abordagem mais comum é colocar as skills dentro de um repositório de código tradicional. Assim, todas as pessoas que trabalham no projeto recebem a mesma experiência.
Além disso, qualquer mudança nas skills passa por pull request, então o time pode revisar ou até reverter as alterações. O repositório dotnet/runtime usa esse modelo na pasta .github/skills.
A grande vantagem é que as skills sempre estão disponíveis. Por exemplo, um agente que roda na web, como o agente do Copilot no GitHub, enxerga as skills porque elas estão no próprio repositório.
Repositórios de marketplace
O segundo caminho são os repositórios de marketplace, como o dotnet/skills. Eles anunciam suas skills por meio de um arquivo marketplace.json.
O usuário instala o marketplace com um comando como /plugin marketplace add dotnet/skills. Esse add é apenas um invólucro sobre o git clone, por isso um repositório de marketplace deve ser pequeno.
Nesse modelo, as skills ficam instaladas localmente. Consequentemente, elas não existem fora da sua máquina, a menos que você dê o passo extra de commitá-las no repositório.
Segundo Lander, nenhuma das duas opções é melhor ou pior. Elas são apenas alternativas diferentes para cenários diferentes.
Como funcionam as skills em pacotes NuGet
O mecanismo é surpreendentemente simples. O dotnet restore já baixa os pacotes para a máquina do desenvolvedor, e por isso os arquivos SKILL.md que estão dentro deles também chegam junto.
Em outras palavras, as skills em pacotes NuGet não exigem nenhum passo adicional de instalação. Elas ficam disponíveis assim que o projeto restaura as dependências.
Os arquivos ficam na pasta global de pacotes do NuGet, dentro da pasta da versão restaurada. No exemplo de Lander, as skills do Markout aparecem em ~/.nuget/packages/markout/0.40.0/skills/.
Além disso, o arquivo project.assets.json, gerado pelo restore, também lista cada SKILL.md encontrado no grafo de pacotes. Com isso, fica fácil saber se existe alguma skill disponível nas dependências do projeto.
$ dotnet build
$ cat ../../artifacts/obj/dotnet-inspect/project.assets.json | grep SKILL.md
"skills/markout-built-in-shapes/SKILL.md",
"skills/markout-composite-cells-cards/SKILL.md",
"skills/markout-conditional-composition/SKILL.md",
"skills/markout-output-formats/SKILL.md",
"skills/markout/SKILL.md",
O cabeçalho das skills do Markout também traz um campo version, que acompanha a versão do pacote. Dessa forma, o agente sabe exatamente a qual versão aquelas instruções se referem.
Segundo o artigo, esse ponto de partida já é bastante útil para os agentes. Mesmo assim, a equipe quis oferecer uma experiência melhor do que procurar arquivos manualmente.
Incluindo skills em pacotes NuGet no momento do pack
O artigo original não detalha como o mantenedor coloca os arquivos dentro do pacote. Porém, o target de pack do NuGet já permite incluir arquivos arbitrários em qualquer caminho do pacote.
Para isso, basta usar os metadados Pack e PackagePath em um item do MSBuild, como descreve a documentação dos targets de pack. O trecho abaixo mostra uma forma de reproduzir a estrutura usada pelo Markout:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<PackageId>Acme.Billing</PackageId>
<Version>1.4.0</Version>
</PropertyGroup>
<ItemGroup>
<!-- Copia cada skills/<nome>/SKILL.md para a mesma estrutura dentro do pacote -->
<None Include="skills/**/SKILL.md"
Pack="true"
PackagePath="skills/%(RecursiveDir)" />
</ItemGroup>
</Project>
Com essa configuração, o dotnet pack gera um pacote com a pasta skills/ na raiz. Assim, quem consome o pacote recebe as skills no próximo restore.
O próprio pacote fictício Acme.Billing poderia trazer uma skill como esta, escrita para a versão publicada:
---
name: acme-billing
version: 1.4.0
description: >-
Use when creating invoices or charging customers with Acme.Billing.
Covers InvoiceBuilder, retry policies and idempotency keys.
---
Always create invoices with `InvoiceBuilder` and call `BuildAsync()`.
Never instantiate `Invoice` directly.
Pass an idempotency key to `ChargeAsync()` on every retry.
O ponto importante é manter a skill sincronizada com a API. Portanto, sempre que a versão do pacote muda, a skill deve ser revisada no mesmo ciclo de publicação.
Ferramentas para descobrir skills em pacotes NuGet
A equipe do .NET trabalha em algumas ferramentas para localizar os arquivos SKILL.md de forma mais confortável. Cada uma tem um foco diferente.
dotnet-inspect
O dotnet-inspect lista as skills de um pacote NuGet diretamente do registro. Além disso, ele imprime o conteúdo de uma skill específica escolhendo a linha da listagem.
$ dotnet-inspect package markout -S Skills --row 4 --print -12
---
name: markout-output-formats
version: 0.40.1
description: >-
Use when you need output other than default Markdown ...
---
A ferramenta também aceita um arquivo de projeto como entrada. Nesse caso, ela analisa as dependências diretas e devolve uma tabela com pacote, versão, caminho, tamanho, nome e descrição de cada skill válida.
$ dotnet new console
$ dotnet package add Mockly
$ dotnet-inspect project scratch.csproj -S Skills
No exemplo de Lander, o pacote Mockly, uma biblioteca de mock de HTTP, aparece com a skill mockly. A descrição explica quando o agente deve usá-la, por exemplo ao escrever testes que interceptam chamadas do HttpClient.
A experiência pretendida é que o próprio agente descubra o conjunto de skills disponíveis, seja pelo projeto, seja pelo registro. Depois disso, ele pode imprimir as skills no seu contexto ou gravá-las em um arquivo para pesquisar ou armazenar no repositório.
dotnet-package-skills
O dotnet-package-skills tem outro foco: copiar as skills dos pacotes NuGet para dentro do repositório. Com um único comando, ele percorre a solução e grava as skills em .agents/skills.
$ dotnet-package-skills install
Destination: /Users/rich/git/dotnet-inspect/.agents/skills
Scanned 23 packages (direct).
Copied 5 skills:
markout (Markout 0.40.1)
markout-built-in-shapes (Markout 0.40.1)
...
Ignored 22 packages without valid bundled skills
Em seguida, basta commitar a pasta .agents/. A ferramenta também cria um arquivo .dotnet-package-skills.json junto com as skills copiadas.
Essa abordagem combina o melhor dos dois mundos, porque as skills ficam sempre disponíveis no repositório. Contudo, a responsabilidade de mantê-las atualizadas passa a ser sua, sempre que as referências de pacote mudarem de versão.
Lander sugere, inclusive, escrever uma skill que faça as duas coisas ao mesmo tempo: atualizar o pacote e atualizar a skill copiada.
NuGet MCP
O NuGet MCP é um servidor MCP que dá aos agentes uma compreensão ampla do NuGet, tanto do projeto local quanto do registro. Ele já ajuda, por exemplo, a corrigir vulnerabilidades e atualizar pacotes.
No entanto, o servidor ainda não foi atualizado para lidar com skills. Segundo o artigo, esse é um trabalho que a equipe pretende fazer em breve.
O que a Microsoft aprendeu com skills em pacotes NuGet
A primeira conclusão da equipe é que skills em pacotes NuGet não são um tipo especial de skill. Elas são apenas mais uma variação de entrega, usando o mesmo formato.
Consequentemente, as práticas convencionais de avaliação de skills continuam valendo. O mantenedor precisa medir se a skill realmente ajuda antes de publicá-la.
Eficácia e eficiência
Segundo Lander, os benefícios de uma skill se resumem a dois: eficácia, que é a capacidade de entregar a resposta certa, e eficiência, que é entregar essa resposta gastando pouco.
Porém, isso não significa que uma skill sempre traga esses benefícios. Uma skill mal escrita ou mal testada pode, inclusive, produzir o efeito contrário.
O custo é o ponto mais sensível. Se um mantenedor inclui skills no pacote NuGet e o custo do agente de quem consome aumenta, o resultado é ruim para todos.
Por isso, os mantenedores precisam avaliar suas skills. Além disso, devem melhorar ou remover as skills que os usuários apontarem como ineficazes ou caras.
Teste com modelos de fronteira
Nos testes com modelos de fronteira, a equipe encontrou pouco espaço para melhorar a eficácia, justamente por causa da capacidade criativa desses modelos. Já com modelos mais fracos, houve desempenho abaixo do esperado e muita variação, porque eles seguem menos as instruções das skills.
A ideia inicial era usar skills para levar modelos menores ao nível dos modelos de fronteira. Na prática, essa ideia não se mostrou viável na experiência da equipe.
O motivo é que o mesmo conjunto de skills chega a todos os modelos. Dessa forma, uma melhoria para um modelo pode virar piora para outro.
Lander dá um exemplo direto: melhorar a eficiência no Haiku em 50% e piorar no Opus em 10% é uma troca ruim. Afinal, os tokens do Opus custam bem mais, então quem usa esse modelo pagaria a conta.
Para corrigir o rumo, a equipe usou a eficiência de Pareto com uma regra básica: não causar dano. Como resultado, o foco principal passou a ser testar com modelos de fronteira.
Testar apenas com modelos baratos, por mais atraente que pareça, é considerado um antipadrão pela equipe. Portanto, se você publica skills em pacotes NuGet, valide primeiro com os modelos mais caros que seus usuários provavelmente usam.
Segurança ao consumir skills em pacotes NuGet
Os mantenedores distribuem markdown junto com pacotes há muito tempo. Até agora, esse conteúdo era um recurso inerte, que ninguém executava.
Os agentes mudam esse cenário, porque passam a ler esse markdown e a agir com base nele. Por isso, a equipe do .NET afirma que é preciso atualizar as orientações de segurança para quem consome pacotes.
A regra de sempre continua válida: use apenas pacotes de mantenedores em quem você confia. Contudo, o consumo de markdown por agentes acrescenta um novo vetor de ameaça, que precisa ser considerado no seu processo.
Na prática, isso significa revisar as skills que chegam pelos pacotes NuGet antes de liberá-las para o agente. Nesse sentido, o modelo do dotnet-package-skills ajuda, porque as skills copiadas passam pela revisão normal de pull request.
Se você está decidindo como organizar o uso de agentes e skills no seu time, o artigo Agents ou Skills: qual escolher? ajuda a separar as responsabilidades de cada um.
Próximos passos da proposta
A equipe do .NET está preparando orientações para os mantenedores de pacotes. Quem já tem experiência com avaliação de skills sai na frente, porque pouca coisa muda quando a entrega acontece por pacote.
O foco agora é descobrir como entregar skills de qualidade em pacotes NuGet com orçamento limitado. Isso inclui, sobretudo, determinar se uma skill realmente entrega valor antes de ela chegar ao pacote.
Conclusão
As skills em pacotes NuGet aproveitam um mecanismo que todo projeto .NET já usa, o restore, para entregar ao agente instruções feitas para a versão exata de cada dependência. Com isso, o agente deixa de gastar tokens descobrindo a API e passa a focar no problema de negócio.
Ao mesmo tempo, a abordagem traz responsabilidades novas para os dois lados. Os mantenedores precisam avaliar suas skills com modelos de fronteira, e quem consome precisa tratar esse markdown como parte da superfície de segurança.
Segundo Lander, a entrega de skills é uma opção nova e importante para o NuGet. Em síntese, ela abre caminho para pacotes autodocumentados e mais eficientes de integrar em uma aplicação.
FAQ
O que são skills em pacotes NuGet?
São arquivos SKILL.md incluídos dentro de um pacote NuGet, na pasta skills/. Eles chegam à máquina pelo dotnet restore e orientam agentes de IA sobre como usar aquela versão do pacote.
Preciso instalar algo para receber as skills de um pacote?
Não, o restore já baixa os arquivos para a pasta global de pacotes. Ferramentas como dotnet-inspect e dotnet-package-skills apenas facilitam encontrar e copiar essas skills.
O formato das skills em pacotes é diferente?
Não, o formato é o mesmo SKILL.md definido em agentskills.io. Muda apenas o veículo de distribuição.
Como manter as skills copiadas para o repositório atualizadas?
A atualização é sua responsabilidade sempre que a versão do pacote mudar. Uma opção sugerida no artigo é criar uma skill que atualize o pacote e a skill juntos.
Skills em pacotes trazem algum risco de segurança?
Sim, porque o agente passa a agir com base no markdown do pacote. Use apenas pacotes de mantenedores confiáveis e revise as skills antes de liberá-las.
Com quais modelos devo testar uma skill antes de publicar?
A equipe do .NET recomenda priorizar modelos de fronteira. Testar apenas com modelos baratos é considerado um antipadrão.