在 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 仓库。对于 Java，请参阅 github/copilot-sdk-java 仓库。

禁用技能

在保持其他技能活跃的同时禁用特定技能

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

有关 Python、Go 和 .NET 的示例，请参阅 github/copilot-sdk 仓库。对于 Java，请参阅 github/copilot-sdk-java 仓库。

技能目录结构

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

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

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

SKILL.md 格式

SKILL.md 文件是一个带可选 YAML frontmatter 的 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.

frontmatter 字段

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>`	要禁用的技能
Java	`skillDirectories`	`List<String>`	加载技能的目录
Java	`disabledSkills`	`List<String>`	要禁用的技能

最佳实践

按领域组织——将相关技能归为一组（例如 skills/security/、skills/testing/）
使用 frontmatter——在 YAML frontmatter 中包含 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 排除冲突的技能
重新组织技能目录以避免重叠

谁可以使用此功能？

本文内容