A skill do time .NET para agentes de IA
O repositório dotnet skills, mantido pelo time oficial do .NET, inclui uma skill chamada csharp-scripts, que ensina agentes de IA como Claude Code e GitHub Copilot a trabalhar com scripts C# usando a abordagem nativa do .NET 10: dotnet run app.cs. Neste artigo, você vai entender o que é esse repositório, como a skill funciona e por que ela muda a forma como os agentes sugerem código C# para tarefas rápidas.
O que é o repositório dotnet skills
O repositório dotnet/skills no GitHub reúne skills para agentes de código publicadas pelo próprio time do .NET. Em março de 2026, Tim Heuer apresentou o projeto no blog oficial do .NET como uma forma de estender os agentes com conhecimento especializado sobre a plataforma.
Segundo o anúncio, uma skill é um pacote leve com conhecimento especializado que o agente consegue descobrir e usar enquanto resolve uma tarefa. Em outras palavras, ela entrega intenção, contexto e artefatos de apoio para que o agente tome decisões melhores.
Na prática, o dotnet skills funciona como um marketplace. Por isso, você instala apenas os pacotes que fazem sentido para o seu trabalho, em vez de carregar tudo de uma vez.
Como uma skill funciona
Cada skill segue a especificação aberta Agent Skills e vive em um arquivo SKILL.md. Esse arquivo tem um frontmatter YAML com nome e descrição, seguido de instruções em markdown com exemplos e alertas sobre armadilhas comuns.
A descrição é a parte mais importante, porque o agente a lê para decidir quando ativar a skill. Assim, uma descrição bem escrita evita que o agente carregue instruções que não têm relação com a tarefa.
Além da descoberta automática, você também pode invocar uma skill de forma explícita com um comando de barra. O anúncio oficial cita como exemplo o comando /dotnet-diag:analyzing-dotnet-performance.
Plugins e organização do dotnet skills
O dotnet skills organiza as skills em plugins por área funcional. Entre eles estão plugins para MSBuild, testes, diagnóstico, Blazor, MAUI, NuGet, upgrade de versões e inteligência artificial.
Dessa forma, um time que trabalha só com APIs não precisa instalar as skills de MAUI. Da mesma maneira, quem cuida de pipelines pode instalar apenas o que envolve MSBuild e diagnóstico de build.
A skill csharp-scripts, foco deste artigo, cobre um tema bem específico: rodar C# sem criar um projeto. Contudo, para entender o valor dela, primeiro precisamos voltar ao problema que ela resolve.
O problema histórico do C# para scripts
Por décadas, executar qualquer código C# exigia a criação de um projeto completo. Ou seja, você precisava de um arquivo .csproj, de uma estrutura de pastas e do boilerplate do método Main.
Isso tornava o C# pouco atrativo para scripts rápidos. Nesse cenário, linguagens como Python, Bash ou JavaScript levavam clara vantagem pela ausência de cerimônia.
Quem já precisou renomear arquivos em lote ou chamar uma API uma única vez conhece bem essa fricção. Muitas vezes, o desenvolvedor .NET acabava escrevendo o script em outra linguagem só para evitar a burocracia do projeto.
Com agentes de IA, o problema ficou ainda mais visível. Afinal, sem orientação, o agente tende a reproduzir o padrão antigo e gerar uma solução completa para algo que caberia em poucas linhas.
É exatamente essa lacuna que o dotnet skills tenta fechar. Antes, porém, vale entender o recurso nativo que a skill ensina.
File-based apps: a solução nativa do .NET 10
Com o .NET 10 Preview 4, a Microsoft introduziu o suporte a file-based apps. Com isso, você executa um arquivo .cs diretamente via dotnet run app.cs, sem projeto, sem scaffolding e sem um método Main explícito.
A documentação oficial de file-based apps explica que o SDK gera automaticamente a configuração do projeto a partir das diretivas do arquivo. Por isso, o programa inteiro fica em um único arquivo de código.
dotnet run hello.cs
O conteúdo do arquivo pode ser apenas isto:
Console.WriteLine("Hello, .NET scripts!");
Esse recurso, base da skill do dotnet skills, é uma evolução natural dos top-level statements, que chegaram no C# 9. Além disso, ele não representa um dialeto separado da linguagem, então o mesmo código pode crescer para um projeto completo sem reescrita.
O suporte entrou oficialmente no .NET SDK 10.0.100, a versão GA do .NET 10, disponível desde novembro de 2025. Também existe a forma abreviada dotnet hello.cs, que produz o mesmo resultado.
Diretivas de arquivo
Os file-based apps suportam diretivas de nível de arquivo, sempre com o prefixo #:. Assim, você declara pacotes NuGet, propriedades do MSBuild e o SDK utilizado sem sair do arquivo .cs.
Para referenciar um pacote NuGet, use a diretiva #:package no topo do arquivo:
#:package Humanizer@2.14.1
using Humanizer;
// calcula há quanto tempo o .NET 9 foi lançado
var dotNet9Released = DateTimeOffset.Parse("2024-12-03");
var since = DateTimeOffset.Now - dotNet9Released;
Console.WriteLine(since.Humanize());
A documentação recomenda informar a versão do pacote de forma explícita. Caso contrário, você pode usar @* para pegar a versão mais recente, ou omitir a versão quando o repositório usa gerenciamento central de pacotes.
Além de #:package, o .NET 10 oferece #:sdk para trocar o SDK, #:property para definir propriedades do MSBuild e #:project para referenciar outro projeto. Por exemplo, #:sdk Microsoft.NET.Sdk.Web transforma o arquivo em uma pequena aplicação web.
Exemplo com acesso a banco de dados
Para scripts mais complexos, como acesso a banco de dados, a abordagem continua direta. Veja um exemplo com Dapper e PostgreSQL:
#:package Dapper@2.1.66
#:package Npgsql@9.0.3
using Dapper;
using Npgsql;
// string de conexão apenas para ambiente local
const string connectionString = "Host=localhost;Port=5432;Username=postgres;Password=postgres";
using var connection = new NpgsqlConnection(connectionString);
await connection.OpenAsync();
var users = await connection.QueryAsync<string>("SELECT name FROM users LIMIT 10");
foreach (var user in users)
Console.WriteLine(user);
Repare que o arquivo já usa await direto no topo. Isso acontece porque os top-level statements aceitam código assíncrono sem nenhuma configuração extra.
Diferença em relação ao dotnet-script
Antes do .NET 10, a alternativa mais popular era o dotnet-script. Essa ferramenta global executava arquivos .csx usando a API de scripting do Roslyn.
O time do .NET reconhece ferramentas como dotnet-script, CS-Script e Cake como contribuições valiosas para o ecossistema. No entanto, o suporte nativo elimina a instalação e a configuração adicionais.
A principal diferença prática está na integração. Enquanto o dotnet-script depende de uma ferramenta externa, o dotnet run app.cs usa o mesmo SDK que já está na sua máquina.
A sintaxe das referências também muda. Com dotnet-script, você referencia pacotes com #r "nuget: PackageName, version", enquanto o modelo nativo usa a diretiva #:package.
Por fim, o arquivo .cs de um file-based app é C# comum. Já o .csx segue as regras do scripting do Roslyn, que diferem um pouco do C# compilado em projetos.
A skill csharp-scripts no dotnet skills
A skill csharp-scripts do dotnet skills encapsula o conhecimento sobre esse modelo de scripting. Dessa forma, os agentes de IA passam a usá-lo de forma correta e consistente.
Quando um agente como Claude Code ou GitHub Copilot detecta que a tarefa envolve executar C# de forma leve, ele carrega a skill. Em seguida, passa a seguir o padrão nativo do .NET 10: arquivo único, diretivas #:package, top-level statements e dotnet run.
Sem a skill, o agente tende a sugerir projetos completos mesmo para tarefas simples. Consequentemente, ele adiciona fricção desnecessária e gera arquivos que você vai apagar logo depois.
A descrição da skill deixa claro o objetivo: rodar file-based apps com a CLI do .NET quando o usuário quer explicitamente código C# sem criar um projeto. Portanto, o gatilho não é "qualquer script", e sim "C# sem projeto".
Quando o agente deve usar a skill
De acordo com a descrição publicada, a skill se aplica a experimentos com a linguagem C# e com APIs do .NET. Por exemplo, testar um recurso novo do C# 14 em poucas linhas é um caso típico.
Ela também serve para prototipar uma lógica antes de levá-la a um projeto maior. Além disso, cobre pequenos utilitários formados por um arquivo de entrada e alguns arquivos auxiliares.
Quando o agente não deve usar a skill
A mesma descrição lista os casos em que a skill não deve entrar em ação. Scripts que não dependem de linguagem, cálculos genéricos e automações no estilo Python ou PowerShell ficam de fora.
Da mesma forma, a skill não se aplica quando você precisa de um projeto completo, de integração com uma solução existente ou de testes e configurações de .csproj. Nesses casos, o certo é adicionar o código à própria solução.
Essa delimitação é importante, porque evita que o agente force C# onde outra ferramenta resolveria melhor. Em outras palavras, a skill orienta o agente, mas não o transforma em um evangelista da linguagem.
Como instalar o dotnet skills nos agentes
No GitHub Copilot CLI, o anúncio oficial mostra três comandos. Primeiro, você adiciona o marketplace; depois, navega pelos plugins; por fim, instala o plugin desejado:
/plugin marketplace add dotnet/skills
/plugin marketplace browse dotnet-agent-skills
/plugin install <plugin>@dotnet-agent-skills
No Claude Code, o fluxo é parecido, porque ele também trabalha com marketplaces de plugins pelo comando /plugin. Assim, você adiciona o repositório dotnet/skills como marketplace e instala o plugin que contém a skill.
No VS Code, o anúncio orienta adicionar a URL https://github.com/dotnet/skills nas configurações da extensão do Copilot. Em seguida, você navega e instala os plugins pelo explorador de extensões.
Também existe a opção de instalar só a skill por meio da CLI skills, como mostra o catálogo skills.sh:
npx skills add https://github.com/dotnet/skills --skill csharp-scripts
Depois da instalação, vale testar com um pedido simples, como "crie um script C# que liste os arquivos maiores que 10 MB nesta pasta". Se o agente responder com um único arquivo .cs e dotnet run, a skill do dotnet skills está ativa.
Casos de uso práticos com dotnet skills
Uma das aplicações mais diretas é trocar scripts PowerShell ou Bash por C# tipado. Assim, você aproveita LINQ, tratamento de exceções e todas as bibliotecas do ecossistema .NET.
Outro caso relevante é a criação de scripts de seed para banco de dados em projetos que já usam .NET. Com isso, você evita poluir o código da aplicação com lógica descartável.
Em pipelines de CI/CD, como GitHub Actions, você também pode chamar arquivos .cs como steps. Por exemplo, um step pode rodar dotnet run PrintBuildInfo.cs dentro do workflow YAML.
# step que imprime informações do build
- name: Print build info
run: dotnet run PrintBuildInfo.cs
No Linux e no macOS, o arquivo ainda pode ganhar um shebang e virar um executável. Basta adicionar #!/usr/bin/env -S dotnet -- na primeira linha e dar permissão de execução com chmod +x.
Para quem trabalha com agentes, esse cenário fica ainda mais interessante. Afinal, o agente consegue gerar, executar e ajustar o script no mesmo fluxo, sem criar uma pasta de projeto a cada tentativa.
Se você ainda está dando os primeiros passos com agentes, o artigo Criando seu primeiro Agente de IA mostra os conceitos básicos antes de partir para skills.
Evolução de script para projeto
Uma vantagem importante do modelo nativo é a transição natural. Quando um script cresce além do arquivo único, ele pode virar um projeto completo com a mesma linguagem, a mesma sintaxe e o mesmo tooling.
O comando dotnet project convert faz essa conversão. Ele cria um .csproj com os itens, propriedades e referências de pacote equivalentes às diretivas #: do arquivo original.
dotnet project convert app.cs
A documentação explica que o comando copia o .cs e gera o .csproj em uma pasta com o nome da aplicação. Enquanto isso, o arquivo original fica intacto ao lado.
Esse caminho é justamente o que a skill do dotnet skills recomenda quando o pedido extrapola o escopo de um script. Assim, o agente sabe quando parar de insistir no arquivo único.
Limitações e cuidados
No lançamento do .NET 10, o suporte ficou limitado a um único arquivo .cs. Mais tarde, a diretiva #:include chegou no .NET SDK 10.0.300 e no .NET 11 Preview 3, permitindo incluir arquivos auxiliares.
Além disso, o suporte de IDE no Visual Studio e no VS Code ainda está amadurecendo. Por isso, a experiência não é a mesma de um projeto completo.
Outro ponto de atenção são os arquivos implícitos de build. Um Directory.Build.props em uma pasta acima afeta o file-based app, então a documentação recomenda manter os scripts fora da árvore de um .csproj.
O SDK também mantém um cache de build para acelerar execuções seguidas. Caso algo pareça desatualizado, o comando dotnet clean file-based-apps limpa esse cache.
Por fim, lembre que o recurso exige o .NET 10. Como o .NET 8 e o .NET 9 chegam ao fim do suporte em novembro de 2026, conforme o artigo sobre o fim do suporte dessas versões, migrar para o .NET 10 já faz sentido de qualquer forma.
Conclusão sobre o dotnet skills
A skill csharp-scripts do repositório dotnet skills formaliza uma mudança significativa no C#. A linguagem deixa de ser "pesada demais para scripts" e passa a competir de igual para igual com Python e Bash em automação e prototipação.
Para agentes de IA, ter essa skill instalada garante que as sugestões de scripting em C# sigam o padrão nativo do .NET 10. Assim, o agente não introduz dependências externas desnecessárias nem projetos que você não pediu.
Em resumo, o dotnet skills aproxima o conhecimento do time oficial do .NET das ferramentas que você já usa no dia a dia. Portanto, vale instalar, testar com um pedido simples e observar como o agente muda de comportamento.
FAQ
O que é o dotnet skills?
É um repositório mantido pelo time do .NET com skills para agentes de código. Ele organiza as skills em plugins por área, como MSBuild, testes, diagnóstico e scripting.
O que a skill csharp-scripts faz?
Ela ensina o agente a criar e executar file-based apps com dotnet run app.cs. Assim, o agente gera um único arquivo C# em vez de um projeto completo.
Preciso do .NET 10 para usar file-based apps?
Sim, o suporte chegou no .NET SDK 10.0.100. Versões anteriores do SDK não reconhecem as diretivas #:.
Qual a diferença entre file-based apps e dotnet-script?
O dotnet-script é uma ferramenta externa que roda arquivos .csx. Os file-based apps usam o SDK oficial e arquivos .cs comuns, sem instalação extra.
Um script pode virar um projeto depois?
Sim, o comando dotnet project convert gera um .csproj com base nas diretivas do arquivo. O arquivo original continua intacto.
A skill funciona em quais agentes?
O anúncio oficial cita o GitHub Copilot CLI, o VS Code e o Visual Studio 2026. Além disso, o Claude Code também consome skills no mesmo formato.