Verwenden von benutzerdefinierten Fähigkeiten mit dem Copilot SDK

Hinweis

          Copilot SDK ist zurzeit in Technische Preview. Funktionalität und Verfügbarkeit können geändert werden.

Fähigkeiten sind wiederverwendbare Prompt-Module, die die Funktionen von Copilot erweitern. Fähigkeiten aus Verzeichnissen laden, um Copilot spezialisierte Kompetenzen für spezifische Domänen oder Workflows bereitzustellen.

Eine Fähigkeit ist ein benanntes Verzeichnis, das eine SKILL.md Datei enthält, ein Markdown-Dokument, das Anweisungen für Copilot bereitstellt. Beim Laden wird der Inhalt der Fähigkeit in den Sitzungskontext eingefügt.

Fähigkeiten ermöglichen Folgendes:

Packen von Domänenkenntnissen in wiederverwendbare Module
Spezialisierte Verhaltensweisen über Projekte hinweg teilen
Organisieren komplexer Agentkonfigurationen
Aktivieren/Deaktivieren von Funktionen pro Sitzung

Ladefähigkeiten

Geben Sie Verzeichnisse an, die Fähigkeiten enthalten, wenn Sie eine Sitzung erstellen:

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

Beispiele in Python, Go und .NET finden Sie im github/copilot-sdk Repository.

Deaktivieren von Fähigkeiten

Deaktivieren Sie bestimmte Fähigkeiten, während andere aktiv bleiben:

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

Beispiele in Python, Go und .NET finden Sie im github/copilot-sdk Repository.

Kompetenzverzeichnisstruktur

Jede Fähigkeit ist ein benanntes Unterverzeichnis, das eine SKILL.md Datei enthält:

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

Die skillDirectories-Option verweist auf das übergeordnete Verzeichnis (z. B. ./skills). Die CLI ermittelt alle SKILL.md Dateien in unmittelbaren Unterverzeichnissen.

SKILL.md Format

Eine SKILL.md Datei ist ein Markdowndokument mit optionalem YAML-Frontmatter:

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

Die Frontmatterfelder: * ** name **— Der Bezeichner der Fähigkeit (wird mit disabledSkills zum selektiven Deaktivieren verwendet). Wenn nicht angegeben, wird der Verzeichnisname verwendet. * ** description **— Eine kurze Beschreibung, was die Fähigkeit tut.

Der Markdowntext enthält die Anweisungen, die in den Sitzungskontext eingefügt werden, wenn die Fähigkeit geladen wird.

Konfigurationsoptionen

SessionConfig-Qualifikationsfelder

Übergeben Sie beim Aufrufen createSession() diese kompetenzbezogenen Felder im Sitzungskonfigurationsobjekt:

Sprache	Feld	Typ	Beschreibung
Node.js	`skillDirectories`	`string[]`	Verzeichnisse zum Laden von Fähigkeiten
Node.js	`disabledSkills`	`string[]`	Zu deaktivierende Fähigkeiten
Python	`skill_directories`	`list[str]`	Verzeichnisse zum Laden von Fähigkeiten aus
Python	`disabled_skills`	`list[str]`	Fähigkeiten deaktivieren
Los geht's	`SkillDirectories`	`[]string`	Verzeichnisse, aus denen Fähigkeiten geladen werden
Los geht's	`DisabledSkills`	`[]string`	Fähigkeiten zum Deaktivieren
.NET	`SkillDirectories`	`List<string>`	Verzeichnisse, aus denen Fähigkeiten geladen werden
.NET	`DisabledSkills`	`List<string>`	Fähigkeiten, die deaktiviert werden sollen

Bewährte Methoden

        **Organisieren nach Domäne – Gruppieren** Sie verwandte Fähigkeiten zusammen (z. B `skills/security/`. , `skills/testing/`)

Verwende Frontmatter—name und description in YAML-Frontmatter zur Übersichtlichkeit einschließen

        **Dokumentabhängigkeiten** – Beachten Sie alle Tools oder MCP-Server, die eine Fähigkeit erfordern

        **Fähigkeiten isoliert überprüfen** – Überprüfen Sie die Fähigkeiten, bevor Sie sie kombinieren.

        **Verwenden von relativen Pfaden** – Portieren von Fähigkeiten über Umgebungen hinweg

Kombinieren mit anderen Features

Fähigkeiten mit benutzerdefinierten Agenten

Fähigkeiten arbeiten zusammen mit benutzerdefinierten Agents:

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

Fähigkeiten mit MCP-Servern

Fähigkeiten können MCP-Serverfunktionen ergänzen:

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

Problembehandlung

Fähigkeiten, die nicht geladen werden

       **Der Überprüfungspfad ist vorhanden** – Überprüfen Sie, ob der Pfad des Kompetenzverzeichnisses korrekt ist und Unterverzeichnisse mit `SKILL.md` Dateien enthält.

       **Überprüfen Von Berechtigungen** – Stellen Sie sicher, dass das SDK das Verzeichnis lesen kann.

       **Überprüfen Sie SKILL.md Format**: Stellen Sie sicher, dass der Markdown wohlgeformt ist, und jeder YAML-Frontmatter verwendet eine gültige Syntax.

       **Debugprotokollierung aktivieren –** Festlegen `logLevel: "debug"` , dass Die Protokolle zum Laden von Fähigkeiten angezeigt werden.

Qualifikationskonflikte

Wenn mehrere Fähigkeiten widersprüchliche Anweisungen bereitstellen:

Verwenden Sie disabledSkills, um widersprüchliche Fähigkeiten auszuschließen
Neuorganisieren von Kompetenzverzeichnissen, um Überlappungen zu vermeiden