Compétences personnalisées

Les compétences sont des modules d’instructions réutilisables qui augmentent les capacités de Copilot. Chargez des compétences depuis des répertoires pour doter Copilot de capacités spécialisées pour des domaines ou des flux de travail spécifiques.

Dans cet article

Overview

Une compétence est un répertoire nommé contenant un fichier SKILL.md, un document markdown qui fournit des instructions pour Copilot. Lors du chargement, le contenu de la compétence est injecté dans le contexte de session.

Les compétences vous permettent de :

  • Emballer l'expertise du domaine en modules réutilisables
  • Partager des comportements spécialisés entre les projets
  • Organiser des configurations d’agent complexes
  • Activer/désactiver des fonctionnalités par session

Compétences de chargement

Spécifiez des répertoires contenant des compétences lors de la création d’une session :

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

Désactivation des fonctionnalités

Désactivez des compétences spécifiques tout en gardant les autres actifs :

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

Structure du répertoire de compétences

Chaque compétence est un sous-répertoire nommé contenant un SKILL.md fichier :

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

L’option skillDirectories pointe vers le répertoire parent (par exemple). ./skills L’interface CLI découvre tous les SKILL.md fichiers dans les sous-répertoires immédiats.

format SKILL.md

Un SKILL.md fichier est un document Markdown avec un frontmatter YAML facultatif :

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

Champs frontmatter :

  • name : L’identificateur de la compétence (utilisé avec disabledSkills pour la désactiver sélectivement). S’il est omis, le nom du répertoire est utilisé.
  • description: brève description de ce que fait la compétence.

Le corps du markdown contient les instructions qui sont injectées dans le contexte de session lorsque la fonctionnalité est chargée.

Options de configuration

Champs de compétence SessionConfig

LanguageChampCatégorieDescription
Node.jsskillDirectoriesstring[]Répertoires à partir duquel charger des compétences
Node.jsdisabledSkillsstring[]Compétences à désactiver
Pythonskill_directorieslist[str]Répertoires à partir duquel charger des compétences
Pythondisabled_skillslist[str]Compétences à désactiver
AllezSkillDirectories[]stringRépertoires à partir duquel charger des compétences
AllezDisabledSkills[]stringCompétences à désactiver
.NETSkillDirectoriesList<string>Répertoires à partir duquel charger des compétences
.NETDisabledSkillsList<string>Compétences à désactiver

Bonnes pratiques

  1. Organiser par domaine - Regrouper les compétences associées (par exemple, skills/security/, skills/testing/)

  2. Utiliser les métadonnées d’en-tête - Inclure name et description dans les métadonnées d’en-tête YAML pour plus de clarté

  3. Dépendances de document - Notez tous les outils ou serveurs MCP dont une compétence nécessite

  4. Tester les compétences séparément - Vérifier que les compétences fonctionnent avant de les combiner

  5. Utiliser des chemins relatifs - Gardez les compétences portables d’un environnement à l’autre

Combinaison avec d’autres fonctionnalités

Compétences + agents personnalisés

Les compétences répertoriées dans le champ d’un skills agent sont préchargées avec impatience : leur contenu complet est injecté dans le contexte de l’agent au démarrage, de sorte que l’agent a accès aux instructions de compétence immédiatement sans avoir besoin d’appeler un outil de compétence. Les noms de compétence sont résolus à partir du niveau skillDirectoriesde la session.

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

Remarque

Les compétences sont facultatives : lorsque skills est omis, aucun contenu des compétences n’est injecté. Les sous-agents n’héritent pas des compétences du parent ; vous devez les répertorier explicitement par agent.

Compétences + serveurs MCP

Les compétences peuvent compléter les fonctionnalités du serveur 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

Compétences qui ne sont pas chargées

  1. Vérifier que le chemin d’accès existe - Vérifiez que le chemin du répertoire de compétences est correct et qu’il contient des sous-répertoires avec des fichiers SKILL.md
  2. Vérifier les autorisations - Vérifier que le Kit de développement logiciel (SDK) peut lire le répertoire
  3. Vérifier SKILL.md format : vérifiez que markdown est bien formé et que tout frontmatter YAML utilise une syntaxe valide
  4. Activer la journalisation du débogage - Définir logLevel: "debug" pour afficher les journaux de chargement des compétences

Conflits de compétences

Si plusieurs compétences fournissent des instructions contradictoires :

  • Utiliser disabledSkills pour exclure les compétences en conflit
  • Réorganiser les répertoires de compétences pour éviter les chevauchements

Voir aussi