Custom Skills 是以目录为单位封装的可复用提示词模块，每个 Skill 包含一个 SKILL.md 文件定义名称、描述和指令。通过 skillDirectories 参数加载 Skill 目录，Agent 根据任务自动匹配并应用合适的 Skill。

GitHub Copilot SDK Custom Skills：封装可复用的 Agent 能力模块

什么是 Custom Skill

Custom Skill 是"包含 SKILL.md 文件的具名目录"，每个 Skill 封装了一个领域的专项知识和指令。Agent 在处理任务时，会自动识别并加载与任务相关的 Skill。

这和你写 CLAUDE.md 文件给 Claude Code 的思路一样：把常用约束和最佳实践封装起来，不需要每次在 Prompt 里重复。

创建 Skill 目录结构

my-skills/
├── code-review/
│   └── SKILL.md
├── security-audit/
│   └── SKILL.md
└── typescript-style/
    └── SKILL.md

编写 SKILL.md

---
name: code-review
description: 代码审查专家，分析代码质量、安全漏洞和性能问题
---

# 代码审查指南

## 审查重点

- 安全：SQL 注入、XSS、不安全的反序列化
- 性能：N+1 查询、不必要的全量加载、缺少索引
- 可维护性：函数长度（建议 < 50 行）、命名清晰度、注释质量

## 输出格式

每个问题按以下格式输出：
- **[严重程度]** 文件:行号 — 问题描述
  - 原因：为什么这是问题
  - 建议：如何修复

严重程度：[CRITICAL] [HIGH] [MEDIUM] [LOW]

加载 Skill 目录

import { createSession } from '@github/copilot-sdk'

const session = await createSession({
  skillDirectories: [
    './my-skills',                        // 相对路径
    '/path/to/shared-company-skills'      // 绝对路径，可用于团队共享技能库
  ]
})

禁用特定 Skill

如果某次任务不需要某个 Skill，可以临时禁用：

const session = await createSession({
  skillDirectories: ['./my-skills'],
  disabledSkills: ['security-audit']  // 这次不做安全审计
})

结合自定义 Agent 使用

Skills 和 Agents 可以组合，给不同 Agent 限制可用 Skill：

session.registerAgent({
  name: 'code-reviewer',
  description: '专职代码审查，使用代码审查相关技能',
  // 指定这个 Agent 可以使用哪些 Skills
  skills: ['code-review', 'typescript-style']
})

session.registerAgent({
  name: 'security-agent',
  description: '安全专项分析',
  skills: ['security-audit']
})

调试技巧

1. 检查 Skill 目录路径：确认目录存在且 SDK 进程有读取权限

ls -la ./my-skills/code-review/SKILL.md

2. 验证 SKILL.md 格式：frontmatter 必须是有效的 YAML，name 和 description 字段必填

3. 开启调试日志：

const session = await createSession({
  skillDirectories: ['./my-skills'],
  debug: true  // 输出 Skill 加载详情
})

4. Skill 未被加载：检查 description 字段是否清晰描述了适用场景，Agent 根据描述匹配任务。

与 Copilot CLI Skills 的关系

Copilot CLI 也有 Skills 系统（通过 ~/.claude/skills/ 目录）。Copilot SDK 的 Custom Skills 是同一概念在 SDK 层面的实现，结构兼容，可以复用已有的 Skill 定义。

常见问题

Q: Skill 目录可以有子目录吗？

A: 每个 Skill 是一个目录（包含 SKILL.md），多个 Skill 平铺在 skillDirectories 指定的父目录下。如果需要分组，可以传入多个 skillDirectories。

Q: SKILL.md 内容多长合适？

A: 建议 200~500 字，聚焦这个 Skill 的核心规则。太长会稀释重点，太短则缺少足够指导。每个 Skill 关注一个具体领域，不要试图把所有规范塞进一个 Skill。

Q: Skills 会影响所有 Agent 吗？

A: 默认情况下，所有注册的 Skill 对所有 Agent 可用。通过 skills 字段限制某个 Agent 只能使用特定 Skill，实现精确控制。