Adicionando habilidades de agente para CLI do GitHub Copilot

Altere o comportamento e as habilidades de Copilot quando ela trabalha em tarefas específicas.

Neste artigo

As habilidades do agente são pastas de instruções, scripts e recursos que Copilot podem ser carregados quando relevantes para melhorar seu desempenho em tarefas especializadas. Para obter mais informações, consulte Sobre as habilidades do agente.

Criando e adicionando uma habilidade

Para criar uma habilidade de agente, você escreve um SKILL.md arquivo e, opcionalmente, outros recursos, como arquivos markdown suplementares ou scripts, que você faz referência nas SKILL.md instruções.

  1. Se você ainda não fez isso, crie um skills diretório em um dos locais a seguir. É aqui que você localizará sua habilidade e qualquer outra que você queira criar no futuro.

    Para habilidades de projeto, específicas para um único repositório, crie um .github/skills, .claude/skillsou .agents/skills diretório em seu repositório.

    Para habilidades pessoais, compartilhadas entre projetos, crie um diretório ~/.copilot/skills ou ~/.agents/skills em seu diretório pessoal.

  2.        `skills` No diretório, crie um subdiretório para sua nova habilidade. Cada habilidade deve ter seu próprio diretório (por exemplo, `.github/skills/webapp-testing`).

    Os nomes de subdiretórios para habilidades devem ser minúsculos e substituir espaços por hifens.

  3. Em seu subdiretório de habilidades, crie um SKILL.md arquivo que contenha as instruções de sua habilidade.

    Importante

    Os arquivos de skill devem ser nomeados SKILL.md.

           `SKILL.md` arquivos são arquivos Markdown com página inicial YAML. Em sua forma mais simples, eles incluem:
    • Front matter YAML
      • nome (obrigatório): um identificador exclusivo para a habilidade. O texto deve estar em minúsculas, usando hifens para espaços. Normalmente, isso corresponde ao nome do diretório da habilidade.
      • descrição (obrigatório): uma descrição do que a habilidade faz e quando Copilot deve usá-la.
      • licença (opcional): uma descrição da licença que se aplica a essa habilidade.
    • Um corpo em Markdown, com as instruções, exemplos e diretrizes a serem seguidas por Copilot.

  4. Opcionalmente, adicione scripts, exemplos ou outros recursos ao diretório da sua habilidade.

    Para obter mais informações, consulte "Habilitando uma habilidade para executar um script".

Arquivo de exemplo SKILL.md

Para uma habilidade de projeto, esse arquivo estaria localizado em um .github/skills/github-actions-failure-debugging diretório do repositório.

Para uma experiência pessoal, esse arquivo estaria localizado em um ~/.copilot/skills/github-actions-failure-debugging diretório.

Markdown
---
name: github-actions-failure-debugging
description: Guide for debugging failing GitHub Actions workflows. Use this when asked to debug failing GitHub Actions workflows.
---

To debug failing GitHub Actions workflows in a pull request, follow this process, using tools provided from the GitHub MCP Server:

1. Use the `list_workflow_runs` tool to look up recent workflow runs for the pull request and their status
2. Use the `summarize_job_log_failures` tool to get an AI summary of the logs for failed jobs, to understand what went wrong without filling your context windows with thousands of lines of logs
3. If you still need more information, use the `get_job_logs` or `get_workflow_run_logs` tool to get the full, detailed failure logs
4. Try to reproduce the failure yourself in your own environment.
5. Fix the failing build. If you were able to reproduce the failure yourself, make sure it is fixed before committing your changes.

Habilitando uma habilidade para executar um script

Quando uma habilidade é invocada, Copilot descobre automaticamente todos os arquivos no diretório da habilidade e os disponibiliza junto com as instruções da habilidade. Isso significa que você pode incluir scripts ou outros recursos no diretório de habilidades e referenciá-los em suas SKILL.md instruções.

Para criar uma habilidade que executa um script:

  1.        **Adicione o script ao diretório da sua habilidade.** Por exemplo, uma habilidade para converter imagens SVG em PNG pode ter a estrutura a seguir.

    .github/skills/image-convert/
├── SKILL.md
└── convert-svg-to-png.sh

  2.        **Opcionalmente, aprove previamente as ferramentas necessárias para a competência.** No frontmatter `SKILL.md`, você pode utilizar o campo `allowed-tools` para listar as ferramentas que Copilot podem usar sem solicitar confirmações a cada vez. Se uma ferramenta não estiver listada no `allowed-tools` campo, Copilot solicitará permissão antes de usá-la.

    ---
name: image-convert
description: Converts SVG images to PNG format. Use when asked to convert SVG files.
allowed-tools: shell
---

    Aviso

    Somente aprove previamente as ferramentas shell ou bash se você tiver revisado esta habilidade, bem como quaisquer scripts referenciados, e confia plenamente na fonte deles. A pré-aprovação de shell ou bash remove a etapa de confirmação para a execução de comandos no terminal e pode permitir que habilidades controladas por atacantes ou injeções de prompts executem comandos arbitrários em seu ambiente. Quando estiver em dúvida, omita shell e bash de allowed-tools modo que Copilot deve solicitar sua confirmação explícita antes de executar comandos de terminal.

  3.        **Escreva instruções que informam Copilot como usar o script.** No corpo de Markdown de `SKILL.md`, descreva quando e como executar o script.

    When asked to convert an SVG to PNG, run the `convert-svg-to-png.sh` script
from this skill's base directory, passing the input SVG file path as the
first argument.

Adicionando uma habilidade que outra pessoa criou

Além de criar suas próprias habilidades, você também pode adicionar habilidades que outras pessoas criaram.

Dica

Você também pode usar gh skill em GitHub CLI para pesquisar, instalar, atualizar e publicar habilidades do agente. Para obter mais informações, consulte Adicionando habilidades de agente para GitHub Copilot.

  1. Baixe um diretório de habilidades (ou seja, um diretório que contém um arquivo SKILL.md e, opcionalmente, outros arquivos e subdiretórios).

    Por exemplo, baixe uma habilidade do repositório Awesome GitHub Copilot : https://awesome-copilot.github.com/skills/.

  2. Se você baixou um .zip arquivo, descompacte isso.

  3. Mova o diretório de habilidades para o local necessário:

    • Para habilidades de projeto específicas para um único repositório: .github/skills, .claude/skills, ou .agents/skills em seu repositório.

    • Para habilidades pessoais, que são compartilhadas em vários projetos: ~/.copilot/skills ou ~/.agents/skills no seu diretório pessoal local.

  4. Inicie uma sessão da CLI ou, se você estiver atualmente em uma sessão da CLI, insira /skills reload.

  5. Insira /skills info SKILL-NAME para verificar se a habilidade foi recarregada.

    SKILL-NAME é definido no arquivo SKILL.md e normalmente é o mesmo que o nome do diretório de habilidades.

Usando habilidades de agente

Ao executar tarefas, Copilot decidirá quando usar suas habilidades com base na sua solicitação e na descrição da habilidade.

Quando Copilot opta por usar uma habilidade, o arquivo SKILL.md será injetado no contexto do agente, dando ao agente acesso às suas instruções. Em seguida, ele pode seguir essas instruções e usar scripts ou exemplos que você possa ter incluído no diretório da habilidade.

Para dizer Copilot para usar uma habilidade específica, inclua o nome da habilidade em seu prompt, precedido por uma barra de avanço. Por exemplo, se você tiver uma habilidade chamada "front-end-design", poderá usar um prompt como:

Use the /frontend-design skill to create a responsive navigation bar in React.

Comandos de habilidades na CLI

  • Listar as habilidades disponíveis no momento: use o comando /skills list ou o prompt:

    What skills do you have?

  • Habilitar ou desabilitar habilidades específicas: use o comando /skills e, em seguida, use as teclas para cima e para baixo no teclado e a barra de espaço, para ativar ou desativar as habilidades.

  • Saiba mais sobre uma habilidade (incluindo sua localização): use o comando /skills info.

  • Adicione um local de habilidades: para adicionar um local alternativo no qual armazenar habilidades, use o comando /skills add.

  • Recarregar habilidades: se você adicionou uma habilidade durante uma sessão da CLI, poderá adicioná-la usando o comando /skills reload para evitar a necessidade de reiniciar a CLI para usá-la.

  • Remova as habilidades: para remover uma habilidade que você adicionou diretamente, não por meio de um plug-in, use o comando /skills remove SKILL-DIRECTORY. Para remover as habilidades adicionadas como parte de um plug-in, você deve gerenciar o plug-in em si. Use o info subcomando para descobrir de qual plug-in uma habilidade veio.

Habilidades versus instruções personalizadas

Você pode usar habilidades e instruções personalizadas para ensinar Copilot como trabalhar em seu repositório e como executar tarefas específicas.

É recomendável usar instruções personalizadas para instruções simples relevantes para quase todas as tarefas (por exemplo, informações sobre os padrões de codificação do repositório) e habilidades para instruções mais detalhadas que Copilot só devem ser acessadas quando forem relevantes.

Para saber mais sobre instruções personalizadas do repositório, consulte Adicionando instruções personalizadas do repositório para GitHub Copilot.

Para saber mais sobre como as habilidades diferem de outros recursos de personalização, consulte Comparando os recursos de personalização do GitHub Copilot na CLI.