摘要

随着大型语言模型（LLM）在软件开发领域的广泛应用，如何有效地扩展 AI Agent 的专业能力成为一个重要课题。Kimi Code CLI 通过引入 Agent Skills 机制，为用户提供了一种模块化、可复用的能力扩展方案。本文系统性地介绍了 Kimi CLI Skills 的架构设计、开发流程，并重点阐述了 Flow Skill 这一特殊类型的工作流自动化机制。通过实际案例分析，本文展示了如何构建从简单的知识型 Skill 到复杂的多步骤自动化工作流，为开发者提供完整的 Skills 开发实践指南。

1. 引言

1.1 背景与动机

在现代软件开发中，AI 编程助手已成为提升效率的重要工具。然而，通用的 AI 模型往往缺乏特定领域的专业知识，例如团队编码规范、项目特定的业务逻辑、或复杂的多步骤工作流程。传统的解决方案是通过详细的提示词（Prompt Engineering）来引导 AI，但这种方法存在明显的局限性：提示词难以复用、知识难以沉淀、工作流程难以自动化。

Agent Skills 作为一种开放格式，旨在解决上述问题。它将专业知识和工作流程封装为独立的模块，使 AI Agent 能够按需加载和执行。Kimi Code CLI 作为支持 Agent Skills 的开发工具，为开发者提供了完整的 Skills 开发、管理和使用框架。

1.2 核心概念

Skill 本质上是一个包含 SKILL.md 文件的目录，其中定义了：

  • 元数据 ：Skill 的名称、描述、类型等信息
  • 指令内容 ：详细的操作指南、最佳实践、代码示例
  • 辅助资源 ：脚本、参考文档、模板文件等

Kimi CLI 在启动时发现所有可用的 Skills，并将其元数据注入系统提示词。AI 根据当前任务自动判断是否需要读取特定 Skill 的详细内容。

1.3 本文结构

本文第 2 节介绍 Skills 的基础架构和目录结构；
第 3 节详细阐述普通 Skill 的开发流程；
第 4 节重点分析 Flow Skill 的设计原理和实现方法；
第 5 节通过实际案例展示 Skills 的应用；
第 6 节总结最佳实践和未来展望。

2. Skills 架构与发现机制

2.1 分层加载机制

Kimi CLI 采用分层加载机制发现 Skills，优先级从高到低依次为：

层级 位置 作用范围
内置 Skills 软件包内部 全局可用
用户级 Skills ~/.config/agents/skills/ 所有项目
项目级 Skills .agents/skills/ 当前项目

这种设计允许 Skills 在不同粒度上进行定制：内置 Skills 提供基础能力，用户级 Skills 保存个人偏好，项目级 Skills 则针对特定项目需求。

2.2 目录结构规范

一个标准的 Skill 目录结构如下：

1
2
3
4
5
skill-name/
    ├── SKILL.md              # 必需：主文件，包含元数据和指令
    ├── scripts/              # 可选：可执行脚本
    ├── references/           # 可选：参考文档
    └── assets/               # 可选：模板、图片等资源

SKILL.md 是 Skill 的核心文件，采用 YAML Frontmatter + Markdown 的格式：

1
2
3
4
5
6
7
8
9
10
---
name: skill-name
description: Skill 的详细描述，说明用途和触发场景
type: flow  # 可选，默认为普通 skill
---
# Skill 标题

## 使用指南

详细的操作步骤和最佳实践...

2.3 渐进式披露设计

Skills 采用三级加载系统管理上下文：

  1. 元数据层 ：名称和描述始终存在于上下文中（约 100 词）
  2. SKILL.md 主体 ：Skill 触发时加载（建议 < 500 行）
  3. 捆绑资源 ：按需加载（无限制，脚本可直接执行）

这种设计确保上下文窗口的高效使用，避免无关信息干扰。

3. 普通 Skill 开发

3.1 开发流程

Skill 创建遵循六个步骤：

1
2
3
4
5
6
7
8
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  1. 理解需求     │ -> │  2. 规划资源     │ -> │  3. 初始化目录   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         |                                               |
         v                                               v
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  6. 迭代优化     │ <- │  5. 打包分发     │ <- │  4. 编写内容     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

3.2 命名规范

  • 使用小写字母、数字和连字符
  • 长度不超过 64 字符
  • 优先使用动词开头的短语
  • 按工具命名空间化（如 gh-address-comments）

3.3 内容编写原则

简洁优先 ：默认假设 Kimi 已具备通用知识，只添加非显而易见的领域知识。

自由度匹配 ：

  • 高自由度 ：文本指令，适用于多种有效方法的场景
  • 中自由度 ：伪代码或参数化脚本，适用于有推荐模式但允许变体的场景
  • 低自由度 ：特定脚本，适用于易错、需严格顺序的操作

渐进式组织 ：当 Skill 支持多种变体时，将核心流程保留在 SKILL.md，变体细节移至 references 文件。

3.4 示例：Python 项目规范 Skill

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
---
name: python-project
description: Python 项目开发规范，包括代码风格、测试和依赖管理。
             当需要初始化 Python 项目、进行代码审查或选择技术栈时触发。
---
# Python 项目规范

## 技术栈

- Python 3.14+
- ruff：代码格式化和 lint
- pyright：类型检查
- pytest：测试框架
- uv：依赖管理

## 代码风格

- 行长度限制 100 字符
- 使用类型注解
- 公开函数需要 docstring

## 快速导航

| 需求 | 参考文件 |
|------|----------|
| 详细编码规范 | [references/coding-standards.md](references/coding-standards.md) |
| 测试最佳实践 | [references/testing.md](references/testing.md) |

4. Flow Skill：工作流自动化

4.1 设计理念

Flow Skill 是一种特殊的 Skill 类型，它在 SKILL.md 中内嵌 Agent Flow 流程图，用于定义多步骤的自动化工作流。与普通 Skill 不同，Flow Skill 通过 /flow: 命令调用，会按照流程图自动执行多个对话轮次。

Flow Skill 的核心价值在于：

  • 流程可视化 ：使用 Mermaid 或 D2 图形化描述工作流
  • 自动化执行 ：AI 自动按流程推进，减少人工干预
  • 条件分支 ：支持基于 AI 判断的动态流程控制
  • 状态持久 ：多轮对话间保持上下文连续性

4.2 创建 Flow Skill

4.2.1 Frontmatter 配置

创建 Flow Skill 需要在 Frontmatter 中设置 type: flow：

1
2
3
4
5
---
name: code-review-flow
description: 自动化代码审查工作流，分析代码变更、检查质量、生成报告
type: flow
---

4.2.2 流程图语法

Flow Skill 支持 Mermaid 和 D2 两种流程图格式。

Mermaid 格式示例 ：

1
2
3
4
5
6
7
8
9
```mermaid
flowchart TD
    A([BEGIN]) --> B[分析代码变更，列出所有修改的文件和功能]
    B --> C{代码质量是否达标？}
    C -->|是| D[生成代码审查报告]
    C -->|否| E[列出问题并提出改进建议]
    E --> B
    D --> F([END])
```

D2 格式示例 ：

1
2
3
4
5
6
7
8
9
```d2
BEGIN -> analyze -> check_quality
analyze: 分析现有代码，为功能编写设计文档
check_quality: Review 设计文档是否足够详细
check_quality -> analyze: 否
check_quality -> implement: 是
implement: 开始实现
implement -> END
```

4.2.3 流程图规范

必需元素 ：

  • BEGIN 节点 ：流程起点，标记为 ([BEGIN]) 或 BEGIN
  • END 节点 ：流程终点，标记为 ([END]) 或 END
  • 普通节点 ：矩形框，文本作为提示词发送给 Agent
  • 分支节点 ：菱形框，需要 Agent 在输出中使用 <choice>分支名</choice> 选择下一步

节点类型说明 ：

编号 节点类型 Mermaid 语法 D2 语法 作用
1 开始/结束 ([BEGIN]) BEGIN 标记流程起点/终点
2 普通节点 [提示词文本] name: 提示词 执行特定任务
3 分支节点 {判断条件} 通过连接标签 条件判断和分支选择

4.3 执行机制详解

4.3.1 调用方式

Flow Skill 支持两种调用方式：

1
2
3
4
5
# 执行流程（自动按流程图执行多轮对话）
/flow:code-review-flow

# 作为普通 Skill 加载（仅加载 SKILL.md 内容）
/skill:code-review-flow

4.3.2 执行流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
用户调用 /flow:code-review-flow
         |
         v
┌─────────────────┐
│ 解析 SKILL.md   │
│ 提取流程图定义   │
└─────────────────┘
         |
         v
┌─────────────────┐
│ 定位 BEGIN 节点  │
└─────────────────┘
         |
         v
┌─────────────────┐     ┌─────────────────┐
│ 执行当前节点     │ --> │ 获取 AI 响应     │
│ (发送节点文本)   │     │                 │
└─────────────────┘     └─────────────────┘
         |                       |
         v                       v
┌─────────────────┐     ┌─────────────────┐
│ 解析响应中的     | <-- │ AI 输出结果     │
│ <choice>标签    │     │ 可能包含分支选择 │
└─────────────────┘     └─────────────────┘
         |
         v
┌─────────────────┐
│ 确定下一节点     │
│ (分支或顺序)     │
└─────────────────┘
         |
         +---> END 节点? ---> 流程结束
         |
         +---> 继续执行下一节点

4.3.3 分支选择机制

在分支节点，AI 需要在输出中包含特定的 XML 标签来指示选择：

1
2
3
4
5
经过分析，代码存在以下问题：
1. 缺少类型注解
2. 函数过长，需要重构

<choice>否</choice>

系统解析 分支名，根据流程图定义跳转到对应节点。

4.4 高级 Flow Skill 设计

4.4.1 循环结构

Flow Skill 支持通过分支实现循环：

1
2
3
4
5
6
7
8
9
```mermaid
flowchart TD
    A([BEGIN]) --> B[收集需求]
    B --> C{需求是否完整？}
    C -->|否| D[询问缺失信息]
    D --> B
    C -->|是| E[生成方案]
    E --> F([END])
```

4.4.2 多分支决策

复杂决策可以有多条出口：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
```d2
BEGIN -> analyze
analyze: 分析代码复杂度
analyze -> simple: 简单
analyze -> moderate: 中等
analyze -> complex: 复杂

simple: 直接审查
moderate: 标准审查流程
complex: 深度审查 + 架构分析

simple -> END
moderate -> END
complex -> END
```

4.4.3 多行节点文本

D2 格式支持使用块字符串语法编写详细的节点指引：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
```d2
BEGIN -> review_step -> END

review_step: |md
  ## 代码审查步骤

  1. **静态分析**
     - 运行 linter 检查代码风格
     - 检查类型注解完整性

  2. **逻辑审查**
     - 验证业务逻辑正确性
     - 检查边界条件处理

  3. **生成报告**
     - 汇总发现的问题
     - 提供改进建议
|
```

4.5 Flow Skill 开发最佳实践

4.5.1 设计原则

  1. 单一职责 ：每个 Flow Skill 专注于一个完整的工作流
  2. 清晰边界 ：BEGIN 和 END 节点明确标记流程范围
  3. 合理粒度 ：节点任务不宜过大或过小，保持可管理性
  4. 错误处理 ：考虑异常情况的分支路径

4.5.2 调试技巧

  • 使用 Mermaid Playground 或 D2 Playground 预览流程图
  • 先用 /skill: 命令测试 SKILL.md 内容
  • 逐步验证每个节点的提示词效果
  • 检查 <choice> 标签的格式正确性

4.5.3 常见陷阱

编号 问题 原因 解决方案
1 流程卡住 缺少 <choice> 标签 确保分支节点输出包含正确格式的选择标签
2 流程图解析失败 语法错误 使用官方 Playground 验证流程图
3 节点执行不符合预期 提示词不清晰 细化节点文本，提供具体指令
4 无限循环 循环条件设置不当 设置最大迭代次数或明确的退出条件

5. 实践案例

5.1 案例一：代码审查工作流

需求 ：创建一个自动化的代码审查流程，包括变更分析、质量检查、问题反馈和报告生成。

实现 ：

1
2
3
4
5
6
---
name: pr-code-review
description: 自动化 Pull Request 代码审查工作流
type: flow
---
# PR 代码审查流程
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
```mermaid
flowchart TD
    A([BEGIN]) --> B[获取 PR 变更，列出所有修改的文件]
    B --> C[分析每个文件的变更类型和影响范围]
    C --> D{是否存在高风险变更？}
    D -->|是| E[标记高风险文件，进行深度审查]
    D -->|否| F[进行标准审查]
    E --> G[检查安全问题、性能影响、兼容性]
    F --> H[检查代码风格、命名规范、注释完整性]
    G --> I[汇总审查结果]
    H --> I
    I --> J{是否发现严重问题？}
    J -->|是| K[生成阻断性审查报告，列出必须修复的问题]
    J -->|否| L[生成通过性审查报告，可选优化建议]
    K --> M([END])
    L --> M
```

审查标准

  • 高风险变更：涉及数据库迁移、API 变更、安全相关代码
  • 代码风格：遵循项目编码规范，使用统一的格式化工具
  • 测试覆盖：新功能必须有对应的单元测试

5.2 案例二：需求分析工作流

需求 ：创建一个引导式需求收集和分析流程，确保需求完整性。

实现 ：

1
2
3
4
5
6
---
name: requirements-gathering
description: 引导式需求收集和分析工作流
type: flow
---
# 需求收集流程
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
```d2
BEGIN -> context -> problem -> users -> features -> validate

context: |md
## 步骤 1：了解业务背景

询问用户： 
- 这个项目的业务目标是什么？ 
- 当前面临的痛点有哪些？ 
- 项目的成功标准是什么？ 
|

problem: |md
## 步骤 2：定义核心问题

基于业务背景，提炼： 
- 要解决的核心问题 
- 问题的优先级排序 
- 不解决的问题范围 
|

users: |md
## 步骤 3：识别目标用户

定义用户画像： 
- 主要用户群体 
- 用户的使用场景 
- 用户的痛点和期望 
|

features: |md
## 步骤 4：梳理功能需求

列出功能清单： 
- 必须实现的核心功能（P0） 
- 重要的增强功能（P1） 
- 可选的优化功能（P2） 
|

validate: |md
## 步骤 5：验证需求完整性

检查清单： 
- [ ] 业务目标清晰 
- [ ] 核心问题定义明确 
- [ ] 目标用户已识别 
- [ ] 功能需求已分级 
- [ ] 非功能需求已考虑 
|

validate -> complete: 是
validate -> missing: 否

missing: 补充缺失信息
missing -> context

complete: 生成需求文档
complete -> END
```

输出格式

最终生成包含以下章节的需求文档：

  1. 项目背景
  2. 问题定义
  3. 用户画像
  4. 功能需求
  5. 非功能需求
  6. 里程碑规划

5.3 案例三：Bug 诊断工作流

需求 ：创建一个结构化的 Bug 诊断流程，帮助快速定位和解决问题。

实现 ：

1
2
3
4
5
6
---
name: bug-diagnosis
description: 结构化 Bug 诊断和修复工作流
type: flow
---
# Bug 诊断流程
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
```mermaid
flowchart TD
    A([BEGIN]) --> B[收集 Bug 报告：现象、复现步骤、环境信息]
    B --> C[尝试复现 Bug]
    C --> D{能否复现？}
    D -->|否| E[检查环境差异，询问更多信息]
    E --> C
    D -->|是| F[分析错误日志和堆栈跟踪]
    F --> G[定位问题代码范围]
    G --> H{问题原因是否明确？}
    H -->|否| I[添加调试日志，缩小范围]
    I --> F
    H -->|是| J[设计修复方案]
    J --> K{修复方案是否通过评审？}
    K -->|否| L[重新设计修复方案]
    L --> J
    K -->|是| M[实现修复并验证]
    M --> N[更新测试用例]
    N --> O([END])
```

诊断清单

  • [ ] 错误现象描述清晰
  • [ ] 复现步骤完整
  • [ ] 环境信息齐全（OS、版本、依赖）
  • [ ] 相关日志已收集
  • [ ] 影响范围已评估

6. 最佳实践总结

6.1 Skill 设计原则

  1. 触发精准 ：描述应明确说明 Skill 的用途和触发场景
  2. 内容简洁 ：SKILL.md 控制在 500 行以内，详细内容移至 references
  3. 示例丰富 ：提供具体的输入输出示例，降低理解成本
  4. 持续迭代 ：基于实际使用反馈不断优化

6.2 Flow Skill 特有原则

  1. 流程清晰 ：确保每个节点有明确的输入输出
  2. 分支完备 ：考虑所有可能的执行路径
  3. 退出明确 ：每个分支最终都应导向 END 节点
  4. 提示词精确 ：节点文本应足够具体，指导 AI 完成特定任务

6.3 组织策略

1
2
3
4
5
6
7
8
9
10
11
12
13
skills/
    ├── coding/                 # 编码相关 Skills
    │   ├── code-review/
    │   ├── refactoring/
    │   └── testing/
    ├── workflow/               # 工作流 Skills
    │   ├── pr-workflow/
    │   ├── release-flow/
    │   └── incident-response/
    └── domain/                 # 领域特定 Skills
        ├── frontend/
        ├── backend/
        └── data-pipeline/

6.4 版本管理

Skills 可以通过 .skill 文件（zip 格式）进行分发：

1
2
3
4
5
6
# 打包 Skill
cd ~/.config/agents/skills/
zip -r my-skill.skill my-skill

# 安装 Skill
unzip my-skill.skill -d ~/.config/agents/skills/

7. 未来展望

7.1 潜在增强

  1. 条件表达式 ：支持更复杂的分支条件，不仅依赖 <choice> 标签
  2. 并行执行 ：支持多个节点并行处理
  3. 状态持久 ：跨会话保存和恢复 Flow 执行状态
  4. 可视化编辑器 ：提供图形化界面设计和调试 Flow

7.2 生态建设

随着 Agent Skills 格式的普及，可以预见：

  • 社区驱动的 Skill 市场
  • 跨平台 Skill 兼容性
  • 与 CI/CD 系统的深度集成

8. 结论

Kimi CLI 的 Skills 机制为 AI Agent 的能力扩展提供了一种优雅而强大的解决方案。通过将专业知识和工作流程封装为可复用的模块，开发者可以：

  • 沉淀最佳实践 ：将团队经验固化为可复用的 Skill
  • 提升一致性 ：确保 AI 在不同场景下遵循统一标准
  • 自动化复杂流程 ：通过 Flow Skill 实现多步骤工作流的自动执行

特别是 Flow Skill 的引入，使得 AI Agent 能够按照预定义的流程自动执行复杂任务，标志着从 “单次对话” 向 “持续工作流” 的重要演进。这为未来的 AI 辅助开发开辟了新的可能性。

参考文献

  1. Kimi Code CLI 官方文档. https://moonshotai.github.io/kimi-cli/
  2. Agent Skills 开放格式规范. https://agentskills.io/
  3. Mermaid 流程图文档. https://mermaid.js.org/
  4. D2 声明式图表语言. https://d2lang.com/
  5. Kimi CLI Skill Creator 指南. Built-in Skill: skill-creator

附录 A：Flow Skill 快速参考

A.1 Mermaid 语法速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
```mermaid
flowchart TD
    %% 节点定义
    A([BEGIN])              %% 开始节点
    B[普通节点]              %% 处理节点
    C{分支节点}              %% 决策节点
    D([END])                %% 结束节点
    
    %% 连接
    A --> B                 %% 直接连接
    B --> C
    C -->|条件1| D          %% 带标签连接
    C -->|条件2| E
```

A.2 D2 语法速查

1
2
3
4
5
6
7
8
9
10
11
12
```d2
BEGIN -> step1 -> decision

step1: 执行步骤
decision: 决策点

decision -> step2: 分支A
decision -> step3: 分支B

step2 -> END
step3 -> END
```

A.3 常用模板

线性流程 ：

1
2
3
4
5
6
7
```mermaid
flowchart TD
    A([BEGIN]) --> B[步骤1]
    B --> C[步骤2]
    C --> D[步骤3]
    D --> E([END])
```

分支流程 ：

1
2
3
4
5
6
7
8
```mermaid
flowchart TD
    A([BEGIN]) --> B{判断条件}
    B -->|是| C[分支A]
    B -->|否| D[分支B]
    C --> E([END])
    D --> E
```

循环流程 ：

1
2
3
4
5
6
7
```mermaid
flowchart TD
    A([BEGIN]) --> B[处理]
    B --> C{完成？}
    C -->|否| B
    C -->|是| D([END])
```

原文地址