SDK 自定义 Skills

Skill 是包含 SKILL.md 的命名目录。SDK 通过会话配置加载这些可复用指令；技能依赖的工具或 MCP 服务仍需另行提供。

先组织目录，再配置加载路径

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

官方目录结构段明确要求 skillDirectories 指向父目录，例如 ./skills，runtime 从其直接子目录查找 SKILL.md。同页开头和组合示例也出现直接指向具体技能目录的写法，两处没有完全统一；下面按目录结构段配置，不把任意深度递归发现当作保证。

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

路径必须在运行环境中存在且可读。相对路径方便随项目分发，但部署时仍应核对 runtime 的实际工作目录。

编写 SKILL.md

---
name: code-review
description: Review code changes for correctness and test coverage
---

# Code review

Check changed behavior, failure paths, and missing tests.
Report file locations and explain the impact of each finding.

官方 SDK 专题将 YAML frontmatter 说明为可选：name 是技能标识，省略时使用目录名；description 简述用途。正文写具体操作和输出要求。disabledSkills 按技能标识排除指定技能，而非删除目录。

不同客户端字段为 TypeScript skillDirectories / disabledSkills、Python skill_directories / disabled_skills、Go 和 .NET SkillDirectories / DisabledSkills。不要把 SDK 专题的可选元数据规则外推到其他产品的发布或校验流程。

empty 模式中的内置技能

runtime 随附的内置 Skills 默认可参与加载，但多租户部署推荐的 mode: "empty" 会在创建和恢复后的选项更新中发送空 includedBuiltinSkills，同时清空 installedPlugins。

这是默认排除，而非禁止以后启用。可以用 includedBuiltinSkills 指定允许的内置技能名称；也可以在 empty 模式中启用技能并配置自己的 skillDirectories。自定义技能即使与某个内置技能同名，仍可使用。在 mode: "copilot-cli" 下，未设置该选项时 SDK 不主动发送这个字段。

为代理预加载技能

自定义代理的 skills 字段按名称引用会话目录中的技能：

const session = await client.createSession({
  skillDirectories: ["./skills"],
  customAgents: [{
    name: "reviewer",
    description: "Reviews code changes and test coverage",
    prompt: "Review the assigned change and report actionable findings.",
    skills: ["code-review"],
  }],
});

列出的技能会在代理启动时把完整内容注入上下文，不必等代理先调用技能工具。此行为必须显式选择：省略代理的 skills 就不会预加载技能内容，subagent 也不继承父代理的技能。

排查加载与指令冲突

依次核对父目录、直接子目录中的文件、读取权限和 YAML 语法；需要日志时可设置客户端 logLevel: "debug"。多个技能指令冲突时，通过 disabledSkills 排除冲突项，或重组目录与职责。先单独验证技能，再与 MCP 或多个代理组合，更容易判断缺的是指令还是工具。