Aptitudes personalizadas

Las habilidades son módulos de prompts reutilizables que amplían las capacidades de Copilot. Cargue aptitudes de directorios para proporcionar Copilot capacidades especializadas para dominios o flujos de trabajo específicos.

En este artículo

Visión general

Una habilidad es un directorio con nombre que contiene un archivo SKILL.md: un documento Markdown que proporciona instrucciones a Copilot. Cuando se carga, el contenido de la habilidad se inyecta en el contexto de la sesión.

Las aptitudes le permiten:

  • Empaquetar la experiencia de dominio en módulos reutilizables
  • Uso compartido de comportamientos especializados entre proyectos
  • Organizar las configuraciones complejas del agente
  • Habilitación o deshabilitación de funcionalidades por sesión

Aptitudes de carga

Especifique directorios que contengan aptitudes al crear una sesión:

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()
Go
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();
}

Deshabilitación de aptitudes

Deshabilite aptitudes específicas mientras mantiene a otros usuarios activos:

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"],
)
Go
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();

Estructura del directorio de aptitudes

Cada aptitud es un subdirectorio con nombre que contiene un SKILL.md archivo:

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

La skillDirectories opción apunta al directorio primario (por ejemplo, ./skills). La CLI detecta todos los SKILL.md archivos en subdirectorios inmediatos.

formato SKILL.md

Un archivo SKILL.md es un documento Markdown con un frontmatter YAML opcional.

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

Los campos de frontmatter:

  • name: identificador de la aptitud (que se usa con disabledSkills para deshabilitarla de forma selectiva). Si se omite, se usa el nombre del directorio.
  • description: Una breve descripción de lo que hace la habilidad.

El cuerpo de Markdown contiene las instrucciones que se insertan en el contexto de sesión cuando se carga la skill.

Opciones de configuración

Campos de habilidades de SessionConfig

LanguageCampoTipoDescription
Node.jsskillDirectoriesstring[]Directorios desde los que cargar habilidades
Node.jsdisabledSkillsstring[]Habilidades para desactivar
Pythonskill_directorieslist[str]Directorios desde los que cargar habilidades
Pythondisabled_skillslist[str]Habilidades para desactivar
IrSkillDirectories[]stringDirectorios desde los que cargar habilidades
IrDisabledSkills[]stringHabilidades para desactivar
.NETSkillDirectoriesList<string>Directorios desde los que cargar habilidades
.NETDisabledSkillsList<string>Habilidades para desactivar

procedimientos recomendados

  1. Organizar por dominio : agrupar aptitudes relacionadas (por ejemplo, skills/security/, skills/testing/)

  2. Usa metadatos preliminares - Incluye name y description en los metadatos preliminares de YAML para mayor claridad

  3. Dependencias del documento: indica las herramientas o servidores MCP que requiere una habilidad.

  4. Prueba de aptitudes de forma aislada : compruebe que las aptitudes funcionan antes de combinarlas

  5. Utiliza rutas relativas - Mantén las habilidades portátiles en distintos entornos

Combinación con otras características

Habilidades + agentes personalizados

Las habilidades enumeradas en el campo skills de un agente se precargan de forma anticipada: su contenido completo se inserta en el contexto del agente al iniciarse, por lo que el agente tiene acceso inmediato a las instrucciones de la habilidad sin necesidad de invocar una herramienta de habilidades. Los nombres de habilidad se resuelven a partir de skillDirectories de nivel de sesión.

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

Nota:

Las aptitudes son opcionales, cuando skills se omite, no se inserta ningún contenido de aptitudes. Los subagentes no heredan habilidades del agente principal; debe enumerarlas explícitamente para cada agente.

Habilidades y servidores MCP

Las aptitudes pueden complementar las funcionalidades del 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" }),
});

Solución de problemas

Aptitudes que no se cargan

  1. Compruebe que la ruta existe - Verifique que la ruta del directorio de habilidades es correcta y que contiene subdirectorios con archivos SKILL.md
  2. Comprobación de permisos : asegúrese de que el SDK puede leer el directorio.
  3. Comprobar el formato de SKILL.md - Verificar que el archivo Markdown esté bien formado y que cualquier encabezado YAML utilice una sintaxis válida.
  4. Activar el registro de depuración - Establece logLevel: "debug" para ver los registros de carga de habilidades

Conflictos de aptitudes

Si varias aptitudes proporcionan instrucciones en conflicto:

  • Use disabledSkills para excluir habilidades en conflicto
  • Reorganización de directorios de aptitudes para evitar superposiciones

Consulte también