Uso de aptitudes personalizadas con el SDK de Copilot

          SDK de Copilot actualmente está en Versión preliminar técnica. La funcionalidad y la disponibilidad están sujetas a cambios.

Habilidades son módulos de aviso reutilizables que amplían las funcionalidades de Copilot. Carga habilidades de los directorios para dotar a Copilot de capacidades especializadas para dominios o flujos de trabajo específicos.

Una habilidad es un directorio con nombre que contiene un SKILL.md archivo, 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:

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 obtener ejemplos en Python, Go y .NET, consulte el github/copilot-sdk repositorio.

Deshabilitación de aptitudes

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

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

Para obtener ejemplos en Python, Go y .NET, consulte el github/copilot-sdk repositorio.

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 (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 función.

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

Al llamar a createSession(), pase estos campos relacionados con la aptitud en el objeto de configuración de sesión:

Language	Campo	Tipo	Descripción
Node.js.	skillDirectories	string[]	Directorios desde los que cargar habilidades
Node.js.	disabledSkills	string[]	Aptitudes para deshabilitar
Python	skill_directories	list[str]	Directorios desde los cuales cargar habilidades
Python	disabled_skills	list[str]	Aptitudes para deshabilitar
Go	SkillDirectories	[]string	Directorios desde los que cargar habilidades
Go	DisabledSkills	[]string	Habilidades para desactivar
.NET	SkillDirectories	List<string>	Directorios para cargar habilidades desde
.NET	DisabledSkills	List<string>	Habilidades para desactivar

procedimientos recomendados

•         **Organizar por dominio: agrupar** aptitudes relacionadas (por ejemplo, `skills/security/`, `skills/testing/`)
  

•         **Uso de la frontmatter**: incluir `name` y `description` en la frontmatter de YAML para mayor claridad
  

•         **Dependencias del documento**: tenga en cuenta las herramientas o servidores MCP que requiere una habilidad.
  

•         **Prueba de aptitudes de forma aislada**: compruebe que las aptitudes funcionan antes de combinarlas
  

•         **Usar rutas de acceso relativas**: Mantener las habilidades portátiles entre entornos
  

Combinación con otras características

Habilidades de agentes personalizados

Las habilidades funcionan junto con 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" }),
});

Aptitudes con 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: "approved" }),
});

Solución de problemas

Aptitudes que no se cargan

1.        **Comprobar existencia de la ruta de acceso**: verifique que la ruta de acceso del directorio de habilidades es correcta y contiene subdirectorios con `SKILL.md` archivos.
   

2.        **Comprobar permisos**: asegúrese de que el SDK puede leer el directorio.
   

3.        **Comprobar el formato de SKILL.md**: compruebe que Markdown tiene un formato correcto y que el frontmatter YAML usa una sintaxis válida.
   

4.        **Habilitar el registro de depuración**: configura `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