Benutzerdefinierte Fähigkeiten

Skills sind wiederverwendbare Promptmodule, die die Fähigkeiten von Copilot erweitern. Laden Sie Fähigkeiten aus Verzeichnissen, um Copilot mit spezialisierten Fähigkeiten für bestimmte Domänen oder Workflows auszustatten.

In diesem Artikel

Übersicht

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:

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

Deaktivieren von Fähigkeiten

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

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

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: Die Kennung der Fähigkeit (wird zusammen mit disabledSkills verwendet, um sie gezielt zu deaktivieren). 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

SpracheFeldTypDescription
Node.jsskillDirectoriesstring[]Verzeichnisse, aus denen Fähigkeiten geladen werden
Node.jsdisabledSkillsstring[]Zu deaktivierende Fähigkeiten
Pythonskill_directorieslist[str]Verzeichnisse, aus denen Fähigkeiten geladen werden
Pythondisabled_skillslist[str]Zu deaktivierende Fähigkeiten
GoSkillDirectories[]stringVerzeichnisse, aus denen Fähigkeiten geladen werden
GoDisabledSkills[]stringZu deaktivierende Fähigkeiten
.NETSkillDirectoriesList<string>Verzeichnisse, aus denen Fähigkeiten geladen werden
.NETDisabledSkillsList<string>Zu deaktivierende Fähigkeiten

Bewährte Methoden

  1. Nach Domäne organisieren - Gruppieren verwandter Fähigkeiten (z. B. skills/security/, ) skills/testing/

  2. Frontmatter verwenden – name und description zur besseren Übersicht in das YAML-Frontmatter aufnehmen

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

  4. Fähigkeiten isoliert testen – Überprüfen Sie, ob die Fähigkeiten funktionieren, bevor Sie sie kombinieren

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

Kombinieren mit anderen Features

Fähigkeiten + benutzerdefinierte Agents

Die im Feld eines Agenten skills aufgeführten Fähigkeiten werden eifrig vorab geladen – ihr vollständiger Inhalt wird beim Start in den Kontext des Agents eingefügt, sodass der Agent sofort Zugriff auf die Qualifikationsanweisungen hat, ohne ein Qualifikationstool aufrufen zu müssen. Qualifikationsnamen werden auf Sitzungsebene skillDirectoriesaufgelöst.

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

Hinweis

Fähigkeiten sind opt-in – wenn skills nicht angegeben wird, wird kein Qualifikationsinhalt eingefügt. Sub-Agents erben keine Fähigkeiten vom Elternteil; Sie müssen sie pro Agent explizit auflisten.

Fähigkeiten + MCP-Server

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

Troubleshooting

Fähigkeiten, die nicht geladen werden

  1. Pfad prüfen - Überprüfen Sie, ob der Pfad zum Skill-Verzeichnis korrekt ist und Unterverzeichnisse mit SKILL.md-Dateien enthält
  2. Überprüfen von Berechtigungen – Stellen Sie sicher, dass das SDK das Verzeichnis lesen kann
  3. Überprüfen sie SKILL.md Format : Überprüfen, ob der Markdown wohlgeformt ist und alle YAML-Frontmatter gültige Syntax verwenden
  4. Debug-Protokollierung aktivieren – Legen Sie logLevel: "debug" fest, um Protokolle zum Laden von Skills anzuzeigen

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

Siehe auch