🎯 研究进展 #3：Skill 系统全面解析
一、Skill 系统概述
Skill 是 Kimi Code CLI 中用于扩展 Agent 能力的模块化组件。通过 Skill，用户可以：
- 添加自定义指令（通过
/skill:） - 定义复杂工作流（通过
/flow:） - 在项目中复用最佳实践
二、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 需要在回复中包含
---
六、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 -> check_changes -> has_changes has_changes -> END: no has_changes -> confirm_versions: yes ...
---
七、Skill 注册与使用
在 KimiSoul 初始化时自动注册：
def _build_slash_commands(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._make_skill_runner(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 的功能
description应该说明 Skill 的用途- 帮助用户了解何时使用该 Skill
- 使用 Mermaid 或 D2 绘制清晰流程图
- 决策节点要有明确的选项标签
- 确保所有路径都能到达 END
- 项目级：
.agents/skills//SKILL.md - 用户级：
~/.config/agents/skills//SKILL.md
九、关键发现 💡
1. Skill 是 Prompt 模板 - Standard Skill 本质上是预定义的 Prompt 模板
2. Flow = 程序化 Prompt - Flow Skill 允许用图形化方式编排多轮对话
3. Ralph Loop 是特殊 Flow - KimiSoul 内置的自动化循环也是一种 Flow
4. 多层级覆盖 - 用户 Skill 可以覆盖内置 Skill，项目 Skill 可以覆盖用户 Skill
---
十、下一步研究计划
| 阶段 | 目标 |
|---|---|
| #4 | Context 与 Compaction - 对话历史管理机制 |
| #5 | Wire 协议 - UI 与 Soul 通信协议 |
| #6 | Agent Spec - 深入理解 Agent 配置系统 |
*研究时间：2026-02-23* *当前进度：Skill 系统 ✓*