Kimi Code CLI 扩展能力与生态集成教程

Agent Skills

2 分钟阅读

Agent Skills

Agent Skills 是 Kimi Code CLI 扩展模型能力的轻量机制。一个 Skill 就是一份带 YAML frontmatter 的 Markdown 文档，描述某项专业知识或工作流程——例如项目的代码风格规范、PR review 流程、提交消息格式。作为最低门槛的扩展方式，你不需要掌握任何开发技能，只需编写Markdown文档即可为Agent注入专属知识，配合DeepSeek的长上下文理解能力，可让Agent完全适配团队的开发习惯与业务规范。相比每次把同样的指引粘到提示词里，Skill 的优势在于：内容沉淀在文件里、可以跨项目和团队复用、可以通过斜杠命令一键加载，也可以让模型在需要时自动调用，大幅提升开发效率与代码一致性。

通过阅读本文，你将全面掌握Skill的创建方法、存放规则、调用方式与实际应用场景，能够根据需求开发自定义Skill提升Agent的适配性。

创建 Skill

Skill 文件需放在已知的扫描目录中。支持两种文件结构，适配不同复杂度的需求：

目录形式（推荐）：在 Skills 目录下创建一个子目录，主文件命名为 SKILL.md，可在同目录下放置脚本、参考资料、模板文件等辅助文件。同目录下同时存在 <name>/SKILL.md 和同名 <name>.md 时，以子目录为准，适合包含辅助资源的复杂Skill。
扁平形式：直接使用单个 .md 文件，Skill 名称取文件名（去掉 .md），适合无需辅助资源的简单Skill。

Skill命名建议使用小写字母、中划线分隔，避免使用中文与特殊字符，方便斜杠命令调用。

文件格式

SKILL.md 由 YAML frontmatter 和 Markdown 正文两部分组成，Frontmatter必须放在文件最开头，用---包裹，YAML语法需正确，否则会解析失败。正文支持所有Markdown语法，Agent可正确理解列表、代码块、表格等格式：

---
name: code-style
description: 项目代码风格规范，定义命名、缩进、注释和文件组织，编写或修改代码时使用
type: prompt
whenToUse: 当用户让我编写、修改或审查项目源代码时
disableModelInvocation: false
arguments:
  - target
  - mode
---

请按下述规范处理代码：
- 缩进使用 2 空格
- 变量名使用 `camelCase`，类型名使用 `PascalCase`
- 公开函数必须带 TSDoc 注释
- 单行不超过 100 字符

Frontmatter 字段

字段	说明
`name`	Skill 名称。目录型 `SKILL.md` 中为必填；扁平 `.md` 文件省略时使用文件名。名称大小写不敏感，是调用Skill的唯一标识。
`description`	一行总结，模型用它来判断何时使用这个 Skill，需清晰准确描述Skill的用途与适用场景。目录型 `SKILL.md` 中为必填；扁平 `.md` 文件省略时回退到正文第一行非空内容（截至 240 字符）。
`type`	Skill 类型：`prompt`（默认）、`inline`（与 `prompt` 语义相同）、`flow`（只支持手动调用，不支持模型自动调用）。其他值会被跳过，`flow`类型适合需要用户确认的敏感工作流。
`whenToUse`	触发场景描述，比`description`更详细，模型会结合两者判断是否需要调用Skill。也接受 `when-to-use`、`when_to_use` 写法。
`disableModelInvocation`	设为 `true` 时禁止模型自动调用此 Skill，只能用户手动调用，适合敏感操作的Skill。也接受 `disable-model-invocation`、`disable_model_invocation` 写法。
`arguments`	命名参数列表，可写成字符串数组或空白分隔的字符串（如 `arguments: target mode`）。声明后，正文可用 `$<name>` 读取参数，未声明的参数不会被自动解析。

注意

目录型 SKILL.md 中 name 和 description 必须显式填写，省略任意一项均会导致解析失败，可运行/skills validate <Skill路径>检查语法正确性。

正文占位符

正文在发送给模型前会展开少量占位符，无需硬编码路径与参数：

$ARGUMENTS：调用时附带的完整原始参数字符串
$ARGUMENTS[0]、$ARGUMENTS[1] 及简写 $0、$1：按空白分词后的位置参数（从 0 开始），支持单双引号包裹的带空格参数
$<name>：arguments 中声明的命名参数，用户调用时传入的对应值会替换该占位符
${KIMI_SKILL_DIR}：当前 Skill 文件所在目录的绝对路径，可用于引用同目录下的辅助文件

位置参数支持单双引号包裹，如 /skill:commit "fix login" patch 中 $0 展开为 fix login，$1展开为patch。若正文不含任何参数占位符，调用时附带的文本会以 \n\nARGUMENTS: <文本> 的形式追加到正文末尾，模型可直接读取。例如Skill声明了target参数，用户调用/skill:code-style src/utils strict时，$target会被替换为src/utils，$ARGUMENTS会被替换为src/utils strict；若Skill路径为~/.kimi-code/skills/review-pr/，${KIMI_SKILL_DIR}会被展开为/Users/xxx/.kimi-code/skills/review-pr，可直接引用同目录下的文件如${KIMI_SKILL_DIR}/references/checklist.md。

Skill 存放位置

Kimi Code CLI 按作用域分四档扫描，越具体的作用域优先级越高：Project > User > Extra > Built-in，高优先级的同名Skill会覆盖低优先级的。

用户级（对所有项目生效）：

$KIMI_CODE_HOME/skills/（默认：~/.kimi-code/skills/）：Kimi专属用户级Skill目录，随KIMI_CODE_HOME移动，适合存放仅在Kimi Code中使用的个人Skill
~/.agents/skills/：跨工具通用Skill目录，放在真实OS home下，适合存放所有AI助手通用的Skill，可跨工具共享

项目级（项目根 = 工作目录向上最近的含 .git 的目录）：

.kimi-code/skills/：Kimi专属项目级Skill目录，可提交到Git仓库，团队成员拉取代码后自动生效
.agents/skills/：跨工具项目级Skill目录，可提交到Git仓库，适合团队共享的通用Skill

额外目录：通过 config.toml 顶层的 extra_skill_dirs 声明，适合存放团队共享的Skill，可指向内网Git仓库目录，所有成员配置后可自动同步团队Skill，无需手动拷贝：

extra_skill_dirs = ["~/team-skills", ".agents/team-skills"]

内置 Skills 随 CLI 一起分发，优先级最低。它们为常见任务提供开箱即用的工作流，例如配置 MCP server、定制 TUI 主题和编辑配置文件。完整列表详见内置 Skill 命令，你可创建同名自定义Skill覆盖内置Skill。

CLI会在会话启动时扫描所有Skill目录，运行/skills reload可手动重新扫描，无需重启会话；运行/skills list可查看所有已加载的Skill，包含名称、描述、来源信息。

调用 Skill

用户通过斜杠命令主动调用，参数支持引号包裹带空格的内容：

/skill:code-style
/skill:git-commits 修复登录接口的并发问题
/skill:review-pr "#1234" "重点检查安全问题"

模型也可以根据 description 和 whenToUse 自动调用 Skill（除非 disableModelInvocation 设为 true 或 type 为 flow）。Skill 调用时最多允许嵌套 3 层，超过后会被终止，避免无限递归。

完整示例

以下是一个团队PR Review的Skill示例，可大幅提升Review效率，无需每次重复输入Review要求：

---
name: review-pr
description: 按团队标准审查一个 Pull Request，输出结构化的 review 报告
type: prompt
whenToUse: 当用户让我审查 PR、检查代码变更或评估提交质量时
arguments:
  - pr_ref
---

请按照以下流程审查用户指定的 PR：$pr_ref
1. 拉取并阅读 `$pr_ref` 的全部 diff。
2. 对照以下检查项逐条核对：
   - 是否包含对应的测试用例，覆盖率是否达标
   - 公开 API 是否有文档更新，符合团队文档规范
   - 是否引入了新的依赖；若有，说明引入理由与兼容性影响
   - 错误处理是否覆盖了边界情况，是否有合理的日志输出
3. 参考同目录下的检查清单：`${KIMI_SKILL_DIR}/references/checklist.md`
4. 输出一份 review 报告，包含：
   - 总体结论（approve / request changes / comment）
   - 必须修改项（blocking），需明确指出文件位置与问题原因
   - 建议改进项（non-blocking），给出优化建议
   - 值得肯定的地方，鼓励团队成员

保存为 $KIMI_CODE_HOME/skills/review-pr/SKILL.md（未设置 KIMI_CODE_HOME 时为 ~/.kimi-code/skills/review-pr/SKILL.md），检查清单放在同目录的 references/checklist.md，运行/skills reload重载后即可通过 /skill:review-pr #1234 调用，其中 #1234 会展开到 $pr_ref。调用后Agent会自动拉取PR diff、读取检查清单、输出结构化Review报告，大幅提升Review效率与一致性。

常见问题（FAQ）

Skill没有被模型自动调用怎么办？ 首先检查Skill的description和whenToUse是否清晰准确，是否与当前任务匹配；然后检查disableModelInvocation是否设为true、type是否为flow。若都没问题，可手动调用一次，模型后续会学习到该使用场景，自动调用概率会提升。
可以创建私有Skill吗？ 可以，只需将Skill放在个人用户级目录中，不要提交到公共仓库，其他人就无法访问。
Skill里可以引用外部文件吗？ 可以，使用${KIMI_SKILL_DIR}引用同目录下的文件，Agent会自动读取这些文件的内容，但禁止引用Skill目录外的文件，避免安全风险。

上一页Agent 与子 Agent 下一页 Plugins