Habilidades personalizadas

Overview

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:

TypeScript

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: "approve-once" }),
});

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

Python

from copilot import CopilotClient, PermissionDecisionApproveOnce

async def main():
    client = CopilotClient()
    await client.start()

    session = await client.create_session(
        on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
        model="gpt-4.1",
        skill_directories=[
            "./skills/code-review",
            "./skills/documentation",
        ],
    )

    # Copilot now has access to skills in those directories
    await session.send_and_wait("Review this code for security issues")

    await client.stop()

package main

import (
    "context"
    "log"
    copilot "github.com/github/copilot-sdk/go"
    "github.com/github/copilot-sdk/go/rpc"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)
    if err := client.Start(ctx); err != nil {
        log.Fatal(err)
    }
    defer client.Stop()

    session, err := client.CreateSession(ctx, &copilot.SessionConfig{
        Model: "gpt-4.1",
        SkillDirectories: []string{
            "./skills/code-review",
            "./skills/documentation",
        },
        OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
            return &rpc.PermissionDecisionApproveOnce{}, nil
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // Copilot now has access to skills in those directories
    _, err = session.SendAndWait(ctx, copilot.MessageOptions{
        Prompt: "Review this code for security issues",
    })
    if err != nil {
        log.Fatal(err)
    }
}

.NET

using GitHub.Copilot;
using GitHub.Copilot.Rpc;

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-4.1",
    SkillDirectories = new List<string>
    {
        "./skills/code-review",
        "./skills/documentation",
    },
    OnPermissionRequest = (req, inv) =>
        Task.FromResult(PermissionDecision.ApproveOnce()),
});

// Copilot now has access to skills in those directories
await session.SendAndWaitAsync(new MessageOptions
{
    Prompt = "Review this code for security issues"
});

Java

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.events.*;
import com.github.copilot.sdk.json.*;
import java.util.List;

try (var client = new CopilotClient()) {
    client.start().get();

    var session = client.createSession(
        new SessionConfig()
            .setModel("gpt-4.1")
            .setSkillDirectories(List.of(
                "./skills/code-review",
                "./skills/documentation"
            ))
            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    ).get();

    // Copilot now has access to skills in those directories
    session.sendAndWait(new MessageOptions()
        .setPrompt("Review this code for security issues")
    ).get();
}

Desativando funcionalidades

Desabilite habilidades específicas mantendo outras pessoas ativas:

TypeScript

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

Python

from copilot.session import PermissionHandler

session = await client.create_session(
    on_permission_request=PermissionHandler.approve_all,
    skill_directories=["./skills"],
    disabled_skills=["experimental-feature", "deprecated-tool"],
)

package main

import (
    "context"
    copilot "github.com/github/copilot-sdk/go"
    "github.com/github/copilot-sdk/go/rpc"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)

    session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
        SkillDirectories: []string{"./skills"},
        DisabledSkills:   []string{"experimental-feature", "deprecated-tool"},
        OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
            return &rpc.PermissionDecisionApproveOnce{}, nil
        },
    })
    _ = session
}

session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
    SkillDirectories: []string{"./skills"},
    DisabledSkills:   []string{"experimental-feature", "deprecated-tool"},
})

.NET

using GitHub.Copilot;
using GitHub.Copilot.Rpc;

public static class SkillsExample
{
    public static async Task Main()
    {
        await using var client = new CopilotClient();

        var session = await client.CreateSessionAsync(new SessionConfig
        {
            SkillDirectories = new List<string> { "./skills" },
            DisabledSkills = new List<string> { "experimental-feature", "deprecated-tool" },
            OnPermissionRequest = (req, inv) =>
                Task.FromResult(PermissionDecision.ApproveOnce()),
        });
    }
}

var session = await client.CreateSessionAsync(new SessionConfig
{
    SkillDirectories = new List<string> { "./skills" },
    DisabledSkills = new List<string> { "experimental-feature", "deprecated-tool" },
});

Java

import com.github.copilot.sdk.json.*;
import java.util.List;

var session = client.createSession(
    new SessionConfig()
        .setSkillDirectories(List.of("./skills"))
        .setDisabledSkills(List.of("experimental-feature", "deprecated-tool"))
        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

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 desativá-la 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

Linguagem	Campo	Tipo	Description
Node.js	`skillDirectories`	`string[]`	Diretórios para carregar habilidades 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]`	Funções a desativar
Go	`SkillDirectories`	`[]string`	Diretórios para carregar habilidades de
Go	`DisabledSkills`	`[]string`	Funções a desativar
.NET	`SkillDirectories`	`List<string>`	Diretórios para carregar habilidades de
.NET	`DisabledSkills`	`List<string>`	Funções a desativar

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 documento – 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 as habilidades portáveis entre ambientes

Combinando com outros recursos

Habilidades + agentes personalizados

As habilidades listadas no campo de skills um agente são ansiosamente pré-carregadas– seu conteúdo completo é injetado no contexto do agente na inicialização, portanto, o agente tem acesso às instruções de habilidade imediatamente sem precisar invocar uma ferramenta de habilidade. Os nomes de habilidade são resolvidos no nível da sessão skillDirectories.

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

Observação

As habilidades são opcionais — quando skills é omitido, nenhum conteúdo de habilidades é injetado. Os sub-agentes não herdam habilidades do pai; você deve listá-los explicitamente por agente.

Habilidades + 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: "approve-once" }),
});

Troubleshooting

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 de 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

Consulte também

Crie seu primeiro aplicativo com tecnologia do Copilot – Definir personas de IA especializadas
Crie seu primeiro aplicativo com tecnologia do Copilot – Criar suas próprias ferramentas
Using MCP servers with the GitHub Copilot SDK – Conectar provedores de ferramentas externas

Neste artigo