Usando habilidades personalizadas com o SDK do Copilot

Observação

          SDK do Copilot está atualmente em versão prévia técnica. A funcionalidade e a disponibilidade estão sujeitas a alterações.

As habilidades são módulos de prompt reutilizáveis que estendem Copilot capacidades. Carregue habilidades a partir de diretórios para dotar Copilot de habilidades especializadas em domínios ou fluxos de trabalho específicos.

Uma habilidade é um diretório nomeado que contém um arquivo SKILL.md — um documento Markdown que fornece instruções para Copilot. Quando carregado, o conteúdo da habilidade é injetado no contexto da sessão.

As habilidades permitem que você:

Empacotar expertise de domínio em módulos reutilizáveis
Compartilhar comportamentos especializados entre projetos
Organizar configurações complexas do agente
Habilitar/desabilitar recursos por sessão

Carregando habilidades

Especifique os diretórios que contêm habilidades ao criar uma sessão:

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-4.1",
    skillDirectories: [
        "./skills/code-review",
        "./skills/documentation",
    ],
    onPermissionRequest: async () => ({ kind: "approved" }),
});

// Copilot now has access to skills in those directories
await session.sendAndWait({ prompt: "Review this code for security issues" });

Para obter exemplos em Python, Go e .NET, consulte o github/copilot-sdk repositório.

Desativando funcionalidades

Desabilite habilidades específicas mantendo outras pessoas ativas:

const session = await client.createSession({
    skillDirectories: ["./skills"],
    disabledSkills: ["experimental-feature", "deprecated-tool"],
});

Para obter exemplos em Python, Go e .NET, consulte o github/copilot-sdk repositório.

Estrutura do diretório de habilidades

Cada habilidade é um subdiretório nomeado que contém um SKILL.md arquivo:

skills/
├── code-review/
│   └── SKILL.md
└── documentation/
    └── SKILL.md

A skillDirectories opção aponta para o diretório pai (por exemplo, ./skills). A CLI descobre todos os SKILL.md arquivos em subdiretórios imediatos.

formato SKILL.md

Um SKILL.md arquivo é um documento de markdown com metadados YAML opcionais:

---
name: code-review
description: Specialized code review capabilities
---

# Code Review Guidelines

When reviewing code, always check for:

1. **Security vulnerabilities**—SQL injection, XSS, etc.
2. **Performance issues**—N+1 queries, memory leaks
3. **Code style**—Consistent formatting, naming conventions
4. **Test coverage**—Are critical paths tested?

Provide specific line-number references and suggested fixes.

Os campos de elementos iniciais: * ** name **—O identificador da habilidade (usado com disabledSkills para desabilitá-lo seletivamente). Se omitido, o nome do diretório será usado. * ** description **— Uma breve descrição do que a habilidade faz.

O corpo do markdown contém as instruções que são injetadas no contexto da sessão quando a habilidade é carregada.

Opções de configuração

Campos de habilidade SessionConfig

Ao chamar createSession(), passe esses campos relacionados à habilidade no objeto de configuração de sessão:

Linguagem	Campo	Tipo	Descrição
Node.js	`skillDirectories`	`string[]`	Diretórios para carregar funcionalidades de
Node.js	`disabledSkills`	`string[]`	Funções a desativar
Python	`skill_directories`	`list[str]`	Diretórios para carregar habilidades de
Python	`disabled_skills`	`list[str]`	Habilidades para desativar
Go	`SkillDirectories`	`[]string`	Diretórios de onde carregar habilidades
Go	`DisabledSkills`	`[]string`	Habilidades para desabilitar
.NET	`SkillDirectories`	`List<string>`	Diretórios para carregar habilidades de
.NET	`DisabledSkills`	`List<string>`	Habilidades para desabilitar

Práticas recomendadas

        **Organizar por domínio** — agrupar habilidades relacionadas (por exemplo, `skills/security/`, ) `skills/testing/`

        **Usar frontmatter** — Incluir `name` e `description` no frontmatter do YAML para maior clareza

        **Dependências de documentos** — observe as ferramentas ou servidores MCP que uma habilidade requer

        **Testar habilidades isoladamente** — verificar se as habilidades funcionam antes de combiná-las

        **Usar caminhos relativos** — Manter habilidades portáteis entre ambientes

Combinando com outros recursos

Habilidades com agentes personalizados

As habilidades funcionam junto com agentes personalizados:

const session = await client.createSession({
    skillDirectories: ["./skills/security"],
    customAgents: [{
        name: "security-auditor",
        description: "Security-focused code reviewer",
        prompt: "Focus on OWASP Top 10 vulnerabilities",
    }],
    onPermissionRequest: async () => ({ kind: "approved" }),
});

Habilidades com servidores MCP

As habilidades podem complementar os recursos do servidor MCP:

const session = await client.createSession({
    skillDirectories: ["./skills/database"],
    mcpServers: {
        postgres: {
            type: "local",
            command: "npx",
            args: ["-y", "@modelcontextprotocol/server-postgres"],
            tools: ["*"],
        },
    },
    onPermissionRequest: async () => ({ kind: "approved" }),
});

Solução de problemas

Habilidades que não estão carregando

       **Caminho de verificação existe** — verifique se o caminho do diretório de habilidades está correto e contém subdiretórios com `SKILL.md` arquivos.

       **Verificar permissões** — verifique se o SDK pode ler o diretório.

       **verificar o formato do SKILL.md** — certifique-se de que o markdown está bem formado e que qualquer frontmatter YAML use sintaxe válida.

       **Habilitar o registro em log de depuração** — Defina `logLevel: "debug"` para ver os logs de carregamento de habilidades.

Conflitos de habilidades

Se várias habilidades fornecerem instruções conflitantes:

Usar disabledSkills para excluir habilidades conflitantes
Reorganizar diretórios de habilidades para evitar sobreposições