Como instalar uma skill no GitHub Copilot do VS Code (pasta e SKILL.md)

Você usa o GitHub Copilot em agent mode no VS Code e encontrou uma skill pronta, ou quer transformar uma instrução que repete no chat em algo reaproveitável. No VS Code, uma skill é uma pasta com instruções, scripts e recursos que o agente carrega sob demanda, só quando o pedido combina com ela.

Este guia cobre onde colocar a pasta, como montar o SKILL.md, qual versão do editor é necessária e como conferir que a skill carregou de verdade. Se você também usa o Claude Code, a última seção mostra como aproveitar a mesma skill nas duas ferramentas.

O que você precisa antes de instalar uma skill no Copilot do VS Code

Você precisa do VS Code 1.109 ou mais recente. Segundo as notas da versão 1.109, de janeiro de 2026, Agent Skills passaram a ser recurso de disponibilidade geral e vêm ativadas por padrão, sem configuração experimental.

Se a sua instalação ainda está no 1.108, a história muda. Nas notas da versão 1.108, de dezembro de 2025, o recurso era experimental e dependia da configuração chat.useAgentSkills, desligada por padrão. O caminho mais simples é atualizar o editor.

O segundo requisito é usar o Copilot em agent mode. A documentação do GitHub sobre Agent Skills lista o agent mode do VS Code entre os ambientes compatíveis. Se o Copilot ainda nem está no seu editor, comece por baixar e instalar o GitHub Copilot.

O GitHub CLI é opcional. Ele só entra se você quiser instalar skills pelo comando gh skill, que pede a versão v2.90.0 ou mais recente.

Passo a passo: como instalar uma skill no GitHub Copilot do VS Code

Na forma mais direta, você cria uma pasta no lugar certo, coloca um arquivo Markdown dentro e o editor descobre sozinho, sem precisar de nenhum gerenciador. Mais adiante, no passo 5, há também uma alternativa com um gerenciador de linha de comando.

1. Escolha o escopo e a pasta. Pela documentação do VS Code sobre Agent Skills, o editor procura skills por padrão em .github/skills/ e .claude/skills/ dentro do workspace. Para valer em todos os seus projetos, use as pastas pessoais ~/.copilot/skills/ ou ~/.claude/skills/.

   A documentação do GitHub também cita .agents/skills para repositórios, mas a página do VS Code não lista essa pasta entre as padrão. No editor, prefira .github/skills/ ou .claude/skills/. Se precisar de outro local, a configuração chat.agentSkillsLocations adiciona pastas extras à descoberta.

   Erro comum deste passo: jogar o SKILL.md direto em .github/skills/. Cada skill precisa da própria subpasta, por exemplo .github/skills/revisar-pr/SKILL.md.

2. Crie a pasta da skill e o SKILL.md. O arquivo é obrigatório e usa Markdown com frontmatter YAML, conforme a página de Agent Skills do GitHub Docs. Scripts, referências e templates são opcionais e ficam na mesma pasta.

   O exemplo abaixo é ilustrativo e fica em .github/skills/revisar-pr/SKILL.md:

   ---
   name: revisar-pr
   description: Revisa as alterações de código antes de abrir um pull request. Use quando o usuário pedir revisão de mudanças, checklist de PR ou conferência antes do commit.
   ---
   
   # Revisão antes do pull request
   
   1. Liste os arquivos alterados e resuma o que mudou em cada um.
   2. Aponte código duplicado, nomes pouco claros e tratamento de erro ausente.
   3. Termine com um checklist curto do que corrigir antes de abrir o PR.

   As regras do frontmatter estão no arquivo-fonte da documentação do VS Code. O name é obrigatório, aceita só letras minúsculas, números e hífens, tem no máximo 64 caracteres e precisa ser igual ao nome da pasta. A description também é obrigatória e tem limite de 1024 caracteres.

   Erro comum deste passo: pasta revisar-pr com name: Revisar PR. Maiúsculas e espaços quebram a regra, e o nome tem que bater com a pasta.

3. Escreva uma description que diga quando usar a skill. Se liga nisso, porque é aqui que muita skill morre. O VS Code usa o name e a description para descobrir a skill e só carrega o corpo do SKILL.md no contexto quando o pedido combina com a descrição.

   Por isso a descrição precisa dizer o que a skill faz e em que situação entra. "Ajuda com código" não diz nada ao agente. "Use quando o usuário pedir revisão antes do PR" diz.

   Erro comum deste passo: descrição vaga. Sem um gatilho claro, fica difícil o agente perceber que aquela skill serve para o pedido e o carregamento automático não acontece.

4. Opcional: controle como a skill é chamada. O frontmatter aceita dois campos para isso. Com user-invocable: false, a skill some do menu /, mas o agente ainda pode carregá-la sozinho.

   Com disable-model-invocation: true, acontece o contrário: a skill só roda quando você chama pelo comando /, sem carregamento automático. Use essa opção em tarefas que você quer disparar só de propósito.

5. Alternativa: instale pela linha de comando ou pelo editor. O GitHub CLI ganhou o comando gh skill, lançado em public preview na v2.90.0 em 16 de abril de 2026, segundo o changelog do GitHub. Ele descobre, instala e gerencia skills a partir de repositórios do GitHub e suporta o GitHub Copilot e o Claude Code, entre outros agentes:

gh skill install github/awesome-copilot documentation-writer

Depois de rodar, confira o resultado pelo próprio VS Code, como mostra a próxima seção. Também dá para criar e gerenciar skills sem sair do editor: abra a Paleta de Comandos (Ctrl+Shift+P no Windows e Linux, Shift+Cmd+P no macOS), rode Chat: Open Customizations e escolha a opção Skills.

Como conferir se a skill foi carregada (e o que fazer quando ela não aparece)

A checagem mais rápida é digitar / no chat do Copilot. Skills aparecem como comandos de barra, junto com os prompt files, então a sua deve estar na lista.

Para ver o que aconteceu por baixo, abra o painel Agent Debug. Rode Developer: Open Agent Debug Panel na Paleta de Comandos ou, no menu de reticências do Chat, escolha Show Agent Debug Logs.

Segundo a página de troubleshooting do VS Code, esse painel mostra quais prompt files, skills e outras customizações foram carregados na sessão. Ele também traz os eventos de carregamento e os caminhos verificados, o que ajuda a descobrir se o editor sequer olhou a sua pasta.

Tome cuidado com tutoriais mais antigos que mandam clicar com o botão direito no chat e abrir Diagnostics. Esse modo surgiu no 1.109 e, segundo as notas da versão 1.110, foi substituído pelo painel Agent Debug.

A skill não aparece no menu /

As causas documentadas são estas:

• Editor no 1.108: naquela versão o recurso dependia de chat.useAgentSkills, desligada por padrão. Atualize para o 1.109 ou mais recente.
• user-invocable: false no frontmatter: a skill está escondida do menu de propósito, mas o agente ainda pode carregá-la.
• Pasta fora das localizações padrão: se a skill não está em .github/skills/, .claude/skills/, ~/.copilot/skills/ ou ~/.claude/skills/, adicione o caminho em chat.agentSkillsLocations.
• Estrutura ou frontmatter fora da regra: confira se existe a subpasta da skill e se o name é igual ao nome dela. Os caminhos verificados no Agent Debug mostram onde o editor procurou.

A skill aparece, mas não carrega sozinha

Aqui sobram duas causas. Ou a description não deixa claro quando usar a skill, ou o frontmatter tem disable-model-invocation: true, que limita a skill ao comando /.

Para prevenir as duas situações, mantenha o VS Code atualizado, respeite a estrutura pasta mais SKILL.md e revise o frontmatter antes de culpar o agente.

Dá para usar a mesma skill no Copilot e no Claude Code?

Dá, desde que ela fique nas pastas do Claude. Pela documentação de skills do Claude Code, o Claude Code lê .claude/skills/<nome>/SKILL.md no projeto e ~/.claude/skills/<nome>/SKILL.md na pasta pessoal, e o name vira o comando /nome.

Como o VS Code também lê .claude/skills/ e ~/.claude/skills/, uma skill guardada ali serve nas duas ferramentas sem duplicar arquivo. Já .github/skills/ e ~/.copilot/skills/ são pastas do lado do Copilot, e o Claude Code não aparece na documentação lendo esses caminhos.

O alcance do lado do GitHub também é maior que o editor. Segundo a documentação do GitHub, skills funcionam no GitHub Copilot app, no Copilot CLI, no Copilot cloud agent, no Copilot code review no GitHub.com e no agent mode do Visual Studio e das IDEs JetBrains, além do VS Code.

Se o seu time mistura as duas ferramentas, .claude/skills/ no repositório é o ponto de encontro. Se todo mundo está no ecossistema do GitHub, .github/skills/ deixa a intenção mais explícita.

Próximo passo: transforme uma tarefa repetida em skill

Pegue uma instrução que você cola no chat toda semana, tipo o seu checklist de revisão ou o padrão de mensagem de commit do projeto. Crie .github/skills/<nome-da-tarefa>/SKILL.md, escreva uma description que diga exatamente quando usar e faça commit, assim o time recebe a skill junto com o código.

Depois abra o painel Agent Debug numa sessão nova e confirme que a skill aparece entre as customizações carregadas. Se quiser exemplos prontos antes de escrever a sua, o repositório github/awesome-copilot, citado pelo próprio GitHub, reúne skills da comunidade para estudar a estrutura e adaptar ao seu caso.

Encontre outros guias no YouTube da Hora de Codar.