Agent skills no Visual Studio
Os agent skills chegaram ao Visual Studio para ensinar o GitHub Copilot a trabalhar do jeito do seu time, com padrões de projeto e procedimentos executados de forma consistente. O Copilot já deixou de ser um simples autocompletar e virou um agente capaz de executar tarefas complexas de forma autônoma, e agora ganha um novo capítulo nessa evolução.
O recurso estreou no Visual Studio 2026 versão 18.5 e muda a forma como desenvolvedores e equipes interagem com o Copilot em modo agente. Neste artigo, você vai entender como ele funciona, como criar sua primeira skill e quando usá-la no lugar de outras personalizações.
O que são agent skills
Agent skills são conjuntos reutilizáveis de instruções que ensinam os agentes do Copilot a executar tarefas específicas. Ao definir uma skill, você explica ao agente como rodar um pipeline de build, gerar código boilerplate ou seguir os padrões de codificação da sua equipe.
A diferença fundamental em relação a outras personalizações está na natureza dinâmica do recurso. Enquanto as custom instructions valem para todas as interações, os agent skills são ativados de forma contextual, pois o modelo decide quando cada um é relevante para a tarefa.
Quando uma skill entra em ação, ela aparece na janela de chat do Copilot. Dessa forma, você mantém total transparência sobre o que o agente está aplicando durante a sessão.
O formato não é exclusivo da Microsoft. Os agent skills seguem uma especificação aberta publicada em agentskills.io, e por isso a mesma skill pode funcionar em diferentes ferramentas de IA.
Pré-requisitos
Para usar o recurso, você precisa do Visual Studio 2026 versão 18.5 ou posterior. Além disso, é obrigatório ter uma assinatura ativa do GitHub Copilot, porque o modo agente depende dela.
No lançamento, a criação de skills pela interface do Visual Studio estava disponível apenas no canal Insiders. A documentação oficial no Microsoft Learn também indica que esse fluxo guiado exige o Insiders, então a criação manual continua sendo o caminho mais universal.
Como os agent skills funcionam
No modo agente, o Copilot percorre automaticamente os diretórios configurados em busca de skills, tanto no repositório atual quanto no perfil do usuário. Esse processo de descoberta não exige nenhuma configuração adicional.
Ao receber uma solicitação, o agente avalia as skills disponíveis e escolhe as relevantes para o contexto. Na prática, o desenvolvedor trabalha normalmente enquanto o agente aplica as instruções certas no momento certo.
Carregamento progressivo dos agent skills
A especificação descreve um modelo de carregamento progressivo em três níveis. Esse desenho explica por que você pode ter dezenas de agent skills sem lotar o contexto do modelo.
- Metadados: o
namee adescriptionde cada skill entram no contexto logo no início, com cerca de 100 tokens. - Instruções: o corpo completo do
SKILL.mdsó é lido quando a skill é ativada. - Recursos: scripts, referências e templates só são abertos quando a tarefa realmente precisa deles.
Por isso, a descrição carrega tanto peso. Afinal, ela é a única parte que o agente lê antes de decidir se a skill serve para o pedido.
Estrutura de uma skill
Cada skill é um diretório que contém obrigatoriamente um arquivo SKILL.md. Além dele, o diretório pode reunir scripts, templates, referências e outros recursos de apoio.
A estrutura de um repositório com duas skills fica assim:
.github/
skills/
github-issues/
SKILL.md
templates/
bug-report.md
code-review/
SKILL.md
checklist.md
Além disso, a especificação sugere três pastas opcionais com nomes padronizados. A pasta scripts/ guarda código executável, references/ reúne documentação extra e assets/ concentra templates e arquivos de dados.
O arquivo SKILL.md
O SKILL.md usa um frontmatter YAML seguido de conteúdo Markdown. Enquanto o frontmatter define os metadados, o corpo traz as instruções propriamente ditas.
---
name: github-issues
description: Creates and manages GitHub issues following team conventions. Use when working with issue tracking, bug reports, or feature requests.
---
When creating GitHub issues:
- Use the standard title format: [Component] Brief description
- Add appropriate labels based on issue type
- Include reproduction steps for bug reports
- Link related issues and PRs
O campo name aceita apenas letras minúsculas, números e hífens, e precisa corresponder ao nome do diretório pai. Segundo a especificação, ele também não pode começar nem terminar com hífen, nem conter dois hífens seguidos.
O campo description é especialmente importante, porque orienta a ativação. Uma descrição clara, com palavras-chave específicas, aumenta a precisão com que o agente reconhece a tarefa.
Propriedades do frontmatter
O arquivo SKILL.md aceita as seguintes propriedades no frontmatter:
| Propriedade | Obrigatória | Descrição |
|---|---|---|
name |
Sim | Letras minúsculas, números e hífens. Máximo de 64 caracteres. |
description |
Sim | Diz o que a skill faz e quando usá-la. Máximo de 1.024 caracteres. |
license |
Não | Nome da licença ou referência a um arquivo de licença. |
compatibility |
Não | Requisitos de ambiente, como produto pretendido ou pacotes necessários. |
metadata |
Não | Mapeamento livre de chave e valor para metadados adicionais. |
allowed-tools |
Não | Lista de ferramentas pré-aprovadas que a skill pode utilizar. |
A especificação marca o campo allowed-tools como experimental, ou seja, o suporte varia entre as ferramentas. Já o compatibility raramente é necessário, então use-o apenas quando a skill depender de algo específico do ambiente.
Onde ficam os agent skills
O Visual Studio descobre os agent skills em dois grupos de localização, cada um com um propósito distinto.
As skills de workspace, ou de projeto, ficam no repositório e chegam a toda a equipe pelo controle de versão. Nesse caso, os caminhos reconhecidos são .github/skills/, .claude/skills/ e .agents/skills/.
As skills pessoais ficam no perfil do usuário e valem para todos os projetos, sem entrar em nenhum repositório. Para elas, os caminhos são ~/.copilot/skills/, ~/.claude/skills/ e ~/.agents/skills/.
Essa separação permite que equipes compartilhem procedimentos padronizados. Ao mesmo tempo, cada desenvolvedor mantém as próprias preferências e automações pessoais.
Repare que os caminhos incluem pastas usadas por outras ferramentas, como .claude/skills/. Assim, um repositório que já tem skills para outro agente aproveita o mesmo conteúdo no Visual Studio.
Criando agent skills no Visual Studio
Existem duas formas de criar agent skills: pela interface do Visual Studio ou manualmente no sistema de arquivos.
Pela interface
Clique no ícone de ferramentas no canto inferior direito do Copilot Chat para abrir o painel de skills. Em seguida, clique no botão + no canto superior direito do painel.
Depois, escolha o escopo da skill, que pode ser de workspace ou pessoal, e informe nome e descrição. O Visual Studio gera então um template do SKILL.md, e o próprio Copilot em modo agente pode ajudar a preenchê-lo.
Manualmente
O processo manual é igualmente simples. Primeiro, crie o diretório da skill, como .github/skills/github-issues/, e depois adicione o SKILL.md seguindo a especificação.
Por fim, inclua scripts, templates ou exemplos no mesmo diretório, se fizer sentido. Como o agente descobre tudo sozinho, não há registro adicional a fazer.
Exemplo de skill para um projeto .NET
Para tornar o conceito concreto, veja uma skill que padroniza a criação de migrations do Entity Framework Core. Ela mostra como uma descrição bem escrita deixa claro quando o agente deve usá-la.
---
name: ef-core-migrations
description: Creates and reviews Entity Framework Core migrations following team conventions. Use when adding, renaming or removing database tables, columns or indexes.
---
When creating a migration:
1. Use a descriptive PascalCase name, such as AddCustomerEmailIndex.
2. Run: dotnet ef migrations add <Name> --project src/Infrastructure
3. Review the generated Up and Down methods before committing.
4. Never edit a migration that was already applied in production.
Com essa skill no repositório, um pedido como criar um índice para o e-mail do cliente leva o agente a seguir o roteiro. Por outro lado, um pedido sem relação com banco de dados nem chega a carregar o corpo da skill.
Boas práticas para escrever skills
A qualidade da descrição no frontmatter é o fator mais crítico. Uma descrição vaga faz o agente ignorar a skill, enquanto uma descrição precisa, com palavras-chave específicas, garante ativações mais certeiras.
A especificação dá um bom exemplo de contraste. Uma descrição como ajuda com PDFs é fraca, porém uma que lista extrair texto, preencher formulários e mesclar arquivos dá ao agente sinais claros.
O SKILL.md principal deve ter no máximo 500 linhas. Caso precise de material de referência extenso, mova esse conteúdo para arquivos separados em references/.
O conteúdo deve trazer instruções passo a passo, exemplos práticos e casos extremos comuns. Quanto mais concreta a instrução, mais consistente o comportamento do agente.
Para validar o formato, a especificação aponta a biblioteca de referência skills-ref. Com ela, um comando como skills-ref validate ./my-skill confere o frontmatter e as regras de nomenclatura.
Gerenciando skills pelo painel
O painel de skills oferece uma visão centralizada de tudo o que o agente descobriu. A partir dele, você edita qualquer skill abrindo o SKILL.md no editor, navega até o diretório no disco e filtra a lista por nome ou palavra-chave.
O painel também exibe diagnósticos para erros de configuração. Essa visibilidade ajuda bastante em projetos com muitas skills, onde manter o controle do que está configurado pode ficar complexo.
Agent skills versus custom instructions
O Visual Studio oferece duas formas principais de personalizar o Copilot, e entender a diferença entre elas é essencial.
As custom instructions, definidas no arquivo .github/copilot-instructions.md, são regras amplas aplicadas a todas as interações. Por isso, servem para preferências gerais, como convenções de nomenclatura, uso de async/await ou formatação.
Os agent skills, por outro lado, são específicos para tarefas e carregados dinamicamente. Eles brilham em fluxos de trabalho, templates e procedimentos com vários passos que só fazem sentido em situações específicas.
| Custom instructions | Agent skills | |
|---|---|---|
| Escopo | Sempre ativas | Ativados por tarefa |
| Melhor para | Estilo de código e convenções gerais | Fluxos de trabalho, templates e procedimentos |
| Estrutura | Um único arquivo Markdown | Diretório com SKILL.md e arquivos de apoio |
| Exemplo | Use PascalCase para métodos públicos | Ao criar uma issue, use este template com severidade e passos de reprodução |
Existe ainda uma terceira peça, os agentes customizados definidos em arquivos .agent.md. Enquanto o agente customizado define uma persona e um conjunto de ferramentas, a skill traz orientação focada que qualquer agente pode descobrir.
Se quiser aprofundar essa escolha, veja o artigo Agents ou Skills: qual escolher?.
Agent skills e ferramentas MCP
Os agent skills complementam de forma natural as ferramentas MCP, sigla de Model Context Protocol. Enquanto a skill descreve como lidar com uma tarefa, a ferramenta MCP fornece a capacidade de executá-la por meio de serviços e APIs externos.
Por exemplo, uma skill pode definir o processo completo de criação de issues no GitHub, com template, campos obrigatórios e convenções do time. Já uma ferramenta MCP conectada ao GitHub cria a issue de fato pela API.
Juntos, os dois recursos permitem que o agente execute procedimentos complexos de ponta a ponta. Em outras palavras, a skill traz o conhecimento e o MCP traz as mãos.
Skills prontas da comunidade e da Microsoft
A comunidade já contribuiu com diversas skills prontas no repositório awesome-copilot. Ele é um bom ponto de partida para quem quer explorar exemplos reais antes de escrever as próprias definições.
A equipe do .NET também mantém o repositório dotnet/skills, com skills criadas por especialistas da plataforma. Exploramos esse conteúdo no artigo Estendendo seu Coding Agent com .NET Skills.
Disponibilidade e evolução dos agent skills
O suporte a agent skills estreou no Visual Studio 2026 versão 18.5, a April Update, lançada em 14 de abril de 2026. Segundo as notas de versão, fluxos mais amigáveis para navegar e criar skills viriam nas versões seguintes.
De fato, a versão 18.6, de 12 de maio de 2026, trouxe o painel para visualizar, editar e localizar as skills. Em seguida, a versão 18.8, de 14 de julho de 2026, adicionou skills embutidas criadas pelos times de .NET e Azure.
Essas skills embutidas aparecem na categoria Built-in do seletor de ferramentas quando as cargas de trabalho correspondentes estão instaladas. Contudo, elas vêm desativadas por padrão, então você escolhe quais habilitar.
Considerações finais
Os agent skills representam um passo importante na evolução do GitHub Copilot como ferramenta de produtividade. Ensinar o agente sobre os padrões e procedimentos de cada projeto transforma uma ferramenta genérica em um colaborador que entende o contexto do time.
A combinação entre skills, custom instructions, agentes customizados e ferramentas MCP cria um ecossistema extensível. Cada recurso atende a uma necessidade específica, e usá-los juntos permite fluxos de trabalho que refletem a forma como cada equipe trabalha.
Para quem já usa o Copilot no Visual Studio, adotar agent skills traz retorno imediato. Assim, procedimentos que antes dependiam de wikis ou da memória de cada desenvolvedor passam a ser executados de forma consistente pelo próprio agente.
FAQ
Qual versão do Visual Studio é necessária?
É necessário o Visual Studio 2026 versão 18.5 ou posterior. Além disso, você precisa de uma assinatura ativa do GitHub Copilot.
Posso compartilhar skills com minha equipe?
Sim, basta guardar as skills em .github/skills/ no repositório. Assim, elas ficam versionadas com o código e disponíveis para todo o time.
Skills pessoais e de projeto podem coexistir?
Sim, as skills pessoais em ~/.copilot/skills/ convivem com as de cada repositório. As pessoais valem para todos os seus projetos.
Preciso ativar as skills manualmente?
Não, o agente descobre e aplica as skills com base no contexto da tarefa. Quando uma skill entra em ação, ela aparece no chat.
Existe limite de tamanho para o SKILL.md?
A recomendação é manter o arquivo com no máximo 500 linhas. Conteúdo extenso deve ir para a pasta references/ dentro da skill.