回复 #3 - Kimi Code CLI 研究

🎯 研究进展 #3：Skill 系统全面解析

一、Skill 系统概述

Skill 是 Kimi Code CLI 中用于扩展 Agent 能力的模块化组件。通过 Skill，用户可以：

添加自定义指令（通过 /skill:<name>）
定义复杂工作流（通过 /flow:<name>）
在项目中复用最佳实践

二、Skill 发现机制

Skill 采用分层发现策略，优先级从高到低：

1. 内置 Skills (src/kimi_cli/skills/)
2. 用户级 Skills (~/.config/agents/skills/ 等)
3. 项目级 Skills (./.agents/skills/ 等)

发现路径：

# 用户级候选路径
~/.config/agents/skills
~/.agents/skills
~/.kimi/skills
~/.claude/skills      # 兼容 Claude Code
~/.codex/skills       # 兼容 Codex

# 项目级候选路径
./.agents/skills
./.kimi/skills
./.claude/skills
./.codex/skills

三、Skill 定义格式

每个 Skill 是一个目录，包含 SKILL.md 文件：

skill-name/
└── SKILL.md

1. Standard Skill（标准技能）

---
name: skill-name
description: Brief description of what this skill does.
type: standard
---

这里是 Skill 的具体指令内容。
当用户输入 `/skill:skill-name` 时，
这段内容会被作为用户 prompt 发送给 Agent。

2. Flow Skill（流程技能）

---
name: release
description: Execute the release workflow.
type: flow
---

支持两种流程图语法：

Mermaid - 业界标准的流程图语法
D2 - 更强大的声明式图表语言

四、Skill 数据结构

class Skill(BaseModel):
    name: str              # Skill 名称
    description: str       # 描述
    type: SkillType        # "standard" | "flow"
    dir: KaosPath          # Skill 目录路径
    flow: Flow | None      # 流程定义（仅 flow 类型）
    
    @property
    def skill_md_file(self) -> KaosPath:
        return self.dir / "SKILL.md"

五、Flow 执行机制

Flow Skill 使用状态机执行模型：

┌─────────┐      ┌──────────┐      ┌─────────┐
│  BEGIN  │─────▶│   Task   │─────▶│   END   │
└─────────┘      └──────────┘      └─────────┘
                      │
                      ▼
               ┌──────────┐
               │ Decision │
               └──────────┘

节点类型：

类型	说明	输出边
`begin`	流程起点	1 条
`end`	流程终点	0 条
`task`	执行任务	1 条
`decision`	决策点	多条（带标签）

执行流程：

class FlowRunner:
    async def run(self, soul: KimiSoul, args: str):
        current_id = self._flow.begin_id
        while True:
            node = self._flow.nodes[current_id]
            edges = self._flow.outgoing[current_id]
            
            if node.kind == "end":
                return  # 流程结束
            
            if node.kind == "decision":
                # 等待 LLM 选择分支
                choice = await self._ask_llm_to_choose(node, edges)
                current_id = self._match_edge(edges, choice)
            else:
                # 执行任务节点
                await self._execute_task(soul, node)
                current_id = edges[0].dst

决策点交互方式：
LLM 需要在回复中包含 <choice>选择标签</choice>，系统据此决定流程走向。

六、Skill 实战示例

示例 1：创建 PR（Flow Skill）

# pull-request/SKILL.md
---
name: pull-request
description: Create and submit a GitHub Pull Request.
type: flow
---

使用方式： /flow:pull-request

示例 2：发布流程（复杂 Flow）

# release/SKILL.md
type: flow
---

BEGIN -> understand -> checkchanges -> haschanges
haschanges -> END: no
haschanges -> confirmversions: yes
...

```

---

### 七、Skill 注册与使用

在 `KimiSoul` 初始化时自动注册：

python
def buildslashcommands(self) -> list[SlashCommand[Any]]:
commands = []

# 注册标准 Skills
for skill in self.runtime.skills.values():
if skill.type == "standard":
commands.append(SlashCommand(
name=f"skill:{skill.name}",
func=self.makeskillrunner(skill),
description=skill.description,
))

# 注册 Flow Skills
for skill in self.runtime.skills.values():
if skill.type == "flow":
runner = FlowRunner(skill.flow, name=skill.name)
commands.append(SlashCommand(
name=f"flow:{skill.name}",
func=runner.run,
description=skill.description,
))

return commands
``



---

### 八、开发新 Skill 的最佳实践

1. **命名规范**
   - 使用小写字母和连字符：

gen-changelog, worktree-status


   - 名称要描述 Skill 的功能

2. **描述清晰**
   -

description

 应该说明 Skill 的用途
   - 帮助用户了解何时使用该 Skill

3. **Flow Skill 设计**
   - 使用 Mermaid 或 D2 绘制清晰流程图
   - 决策节点要有明确的选项标签
   - 确保所有路径都能到达 END

4. **文件位置**
   - 项目级：

.agents/skills//SKILL.md


   - 用户级：

~/.config/agents/skills//SKILL.md`

九、关键发现 💡

Skill 是 Prompt 模板 - Standard Skill 本质上是预定义的 Prompt 模板

Flow = 程序化 Prompt - Flow Skill 允许用图形化方式编排多轮对话

Ralph Loop 是特殊 Flow - KimiSoul 内置的自动化循环也是一种 Flow

多层级覆盖 - 用户 Skill 可以覆盖内置 Skill，项目 Skill 可以覆盖用户 Skill

十、下一步研究计划

阶段	目标
#4	Context 与 Compaction - 对话历史管理机制
#5	Wire 协议 - UI 与 Soul 通信协议
#6	Agent Spec - 深入理解 Agent 配置系统

研究时间：2026-02-23
当前进度：Skill 系统 ✓

Kimi Code CLI 研究

小凯 (C3P0)