将自定义技能与 Copilot SDK 配合使用

注意

          Copilot SDK 当前处于 技术预览版. 功能和可用性可能会发生更改。

技能是扩展 Copilot功能的可重用提示模块。从目录中加载技能，为特定域或工作流提供 Copilot 专用功能。

能力是包含 SKILL.md 文件的命名目录，即一个 markdown 文档，用于提供给 Copilot 的说明。加载后，技能的内容将注入到会话上下文中。

技能允许您：

将域专业知识打包到可重用模块中
跨项目共享特定行为
整理复杂的代理配置
每个会话启用/禁用功能

加载技能

创建会话时，指定包含技能的目录：

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

有关 Python、Go 和 .NET 中的示例，请参阅 github/copilot-sdk 存储库。

禁用技能

禁用特定技能，同时使其他人保持活动状态：

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

有关 Python、Go 和 .NET 中的示例，请参阅 github/copilot-sdk 存储库。

技能目录结构

每个技能都是一个包含 SKILL.md 文件的命名子目录：

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

选项 skillDirectories 指向父目录（例如 ./skills，）。 CLI 可发现即时子目录中的所有 SKILL.md 文件。

SKILL.md 格式

          `SKILL.md`文件是一个具有可选 YAML 头部信息的 Markdown 文件：

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

"前置信息字段：" * ** name **— 技能的标识符（用于与 disabledSkills 一起有选择地禁用该技能）。如果省略，则使用目录名称。 * ** description **— 技能的作用的简短说明。

Markdown 正文包含加载技能时注入到会话上下文中的指令。

配置选项

SessionConfig 技能字段

调用 createSession()时，在会话配置对象中传递这些技能相关字段：

语言	领域	类型	说明
Node.js	`skillDirectories`	`string[]`	要从中加载技能的目录
Node.js	`disabledSkills`	`string[]`	禁用技能
Python	`skill_directories`	`list[str]`	要从中加载技能的目录
Python	`disabled_skills`	`list[str]`	禁用技能
Go	`SkillDirectories`	`[]string`	要从中加载技能的目录
Go	`DisabledSkills`	`[]string`	禁用技能
.NET	`SkillDirectories`	`List<string>`	要从中加载技能的目录
.NET	`DisabledSkills`	`List<string>`	禁用技能

最佳做法

        **按域组织** - 将相关技能组合在一起（例如， `skills/security/``skills/testing/`）

        **使用前置内容** — 在 YAML 前置内容中包括 `name` 和 `description` 以便于清晰

        **文档依赖项** - 记下技能所需的任何工具或 MCP 服务器

        **单独测试技能** - 在组合技能之前验证技能是否有效

        **使用相对路径** - 使技能在环境中保持可移植性

与其他功能结合使用

使用自定义代理的技能

与自定义代理一起工作的技能：

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

使用 MCP 服务器的技能

技能可以补充 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" }),
});

故障排除

技能未加载

       **检查路径是否存在** — 验证技能目录路径是否正确，并包含包含 `SKILL.md` 文件的子目录。

       **检查权限** - 确保 SDK 可以读取目录。

       **检查 SKILL.md 格式** - 验证 markdown 格式正确，并且任何 YAML frontmatter 都使用有效的语法。

       **启用调试日志记录** - 设置为 `logLevel: "debug"` 查看技能加载日志。

技能冲突

如果多个技能提供冲突的说明：

使用 disabledSkills 来排除冲突技能
重新组织技能目录以避免重叠

谁可以使用此功能？

在本文中