技能图创建指南

本文档是一个 meta-skill。当 AI agent 被要求创建新的 skill 时，应首先加载并遵循本文档的全部规范。

---

第一部分：理论定义

1.1 什么是技能图

技能图（Skill Graph）是一组相互关联的 skill 文件的集合，通过明确的依赖关系构成层次化结构。与平铺的 skill 列表不同，技能图中的 skill 会显式调度其他 skill，形成可组合、可复用的知识与流程网络。

技能图的核心价值在于杠杆：每向上提升一个层次，单位时间内可完成的工作量约提升一个数量级。

1.2 三层架构

技能图采用三层架构，每层有明确的职责边界：

化合物（Compound）  ←  高层编排，人类驱动
      ↓ 调度
  分子（Molecule）  ←  流程组合，显式编排
      ↓ 调度
   原子（Atom）    ←  单一职责，接近确定性

原子（Atom）

定义：最小的、单一职责的 skill。执行一个明确定义的操作，不依赖其他 skill。

特征：

• 输入输出明确，几乎无歧义
• 执行结果接近确定性（对相同输入，产生高度一致的输出）
• 不调用其他任何 skill
• 范围极窄，不做超出名称描述范围的事情

典型例子：

• 抓取某个网页的内容
• 验证一个电子邮件地址的格式
• 将一段代码格式化为标准风格
• 在代码仓库中搜索某个关键词

可靠性要求：原子必须极其可靠。分子和化合物的可靠性完全建立在原子的可靠性之上。

---

分子（Molecule）

定义：将 2–10 个原子组合起来，完成一个有范围的任务。分子显式规定何时、以何种顺序调用哪些原子。

特征：

• 明确列出它依赖的原子 skill
• 提供清晰的编排逻辑（顺序、条件分支、并行）
• 允许 agent 在编排层面有一定判断，但原子层面的执行是确定的
• 解决一个可以完整定义的问题

典型例子：

• 潜在客户开发流程：搜索名单（原子）→ 验证联系方式（原子）→ 写入表格（原子）
• 代码审查流程：运行 lint（原子）→ 检查安全漏洞（原子）→ 汇总报告（原子）
• 内容发布流程：生成草稿（原子）→ 检查语法（原子）→ 发布（原子）

可靠性要求：分子应保持高可靠性。一个分子的最大原子依赖数建议不超过 10 个。超过时应考虑拆分为多个分子。

---

化合物（Compound）

定义：编排多个分子，完成跨域、高价值的复杂任务。化合物是人类驱动的入口点。

特征：

• 依赖分子（不直接依赖原子）
• 赋予 agent 更高的自主判断权
• 天然地比原子和分子更不确定，需要人类参与决策
• 通常对应一个可以被命名为"业务流程"或"工作剧本"的任务

典型例子：

• 执行外向销售剧本（orchestrate 多个分子）
• 规划并构建一个功能，然后审查并 QA 它
• 完整的市场竞品分析

可靠性要求：化合物的不确定性是被接受的，因为人类在这一层驱动。但单个化合物依赖的分子数建议不超过 8–10 个，超过时可靠性会显著下降。

---

1.3 设计哲学

尽量下压决策：将尽可能多的编排逻辑写进 skill 正文，而不是依赖 agent 的运行时判断。判断越靠近叶节点（原子），行为越确定。

单向依赖：依赖关系只能向下（化合物 → 分子 → 原子），严禁循环依赖。

不跨层依赖：化合物不应直接调用原子，应通过分子。这保证了每一层的抽象清晰。

原子不调用任何 skill：原子是终止节点，其内部不包含对其他 skill 的引用或调度。

人类驱动化合物：化合物需要人类在起点给出意图，并在关键决策点介入。不要设计"全自动化合物"。

---

第二部分：操作规程

2.1 创建前：确定层级

在创建 skill 之前，先回答以下问题：

问题	是	否
这个 skill 只做一件事，且不需要调用其他 skill？	→ 原子	继续向下
这个 skill 需要组合 2–10 个已有的原子？	→ 分子	继续向下
这个 skill 需要编排多个分子，完成跨域复杂任务？	→ 化合物	重新思考范围

如果不能明确归类，说明 skill 的范围定义有问题——先澄清范围，再创建。

---

2.2 Frontmatter 规范

每个 skill 文件（SKILL.md）必须包含 YAML frontmatter，位于文件顶部：

---
name: skill-name # 必填。与所在目录名完全一致。
description: > # 必填。供 agent 判断是否加载本 skill。
  一句话描述本 skill 的用途和适用场景。
layer: atom # 必填。取值：atom | molecule | compound
delegates-to: # 分子和化合物必填，原子禁填。
  - skill-name-1
  - skill-name-2
---

字段约束

name

• 必须与 skill 所在目录名完全一致
• 只允许小写字母、数字、连字符（a-z, 0-9, -）
• 不得以连字符开头或结尾
• 不得包含连续连字符（--）
• 最大长度：64 字符

description

• 必填，不得为空
• 必须清晰描述：本 skill 做什么、在什么场景下应被加载
• 最大长度：1024 字符
• 这是 agent 在平铺列表中唯一能看到的信息，决定 agent 是否选择本 skill

layer

• 必填，取值只能是 atom、molecule、compound 三者之一
• 取值必须与 skill 的实际行为一致

delegates-to

• 分子和化合物：必填，列出所有被调度的下层 skill 名称
• 原子：禁止填写此字段（原子不调用其他 skill）
• 列表中的名称必须是已存在的、可被 agent 定位的 skill

---

2.3 正文规范

原子的正文结构

## 用途

[一句话说明这个原子做什么]

## 前置条件

[执行前需要满足的条件，例如：需要哪些环境变量、文件、权限]

## 输入

[接受什么输入，格式要求]

## 执行步骤

1. [步骤 1，极其具体，不留歧义]
2. [步骤 2]
3. [步骤 3]

## 输出

[产出什么，格式是什么]

## 错误处理

[遇到什么情况应停止并报告，而不是继续推进]

分子的正文结构

## 用途

[说明这个分子解决什么问题]

## 依赖的原子

使用 read 工具按需加载以下原子 skill：

- `../atom-1/SKILL.md`：[一句话说明用于什么步骤]
- `../atom-2/SKILL.md`：[一句话说明用于什么步骤]

## 编排流程

[明确的步骤序列，指定在哪一步加载哪个原子]

1. 加载并执行 `atom-1`：[说明传入什么、期望得到什么]
2. 根据 atom-1 的结果：
   - 如果 [条件 A]，加载并执行 `atom-2`
   - 如果 [条件 B]，直接进入步骤 3
3. 加载并执行 `atom-3`：[说明]

## 输出

[整体产出什么]

## 失败处理

[某个原子失败时，整体如何响应]

化合物的正文结构

## 用途

[说明这个化合物对应的业务流程或工作剧本]

## 人类驱动点

[说明人类需要在哪些决策点介入，以及介入方式]

## 依赖的分子

使用 read 工具按需加载以下分子 skill：

- `../molecule-1/SKILL.md`：[用于什么阶段]
- `../molecule-2/SKILL.md`：[用于什么阶段]

## 编排策略

[描述分子的编排逻辑。化合物允许 agent 有较高的自主判断，
但仍应尽量明确：默认顺序、并行时机、何时需要人类确认]

## 成功标准

[什么状态代表化合物执行完成]

## 已知局限

[这个化合物在哪些场景下可能不可靠，人类应注意什么]

---

2.4 目录结构约束

每个 skill 必须存放在独立目录中，目录名与 name 字段完全一致：

skills/
├── atom-scrape-webpage/
│   └── SKILL.md
├── atom-verify-email/
│   └── SKILL.md
├── molecule-lead-generation/
│   └── SKILL.md
│   └── scripts/           # 可选：辅助脚本
│       └── parse-results.py
└── compound-outbound-sales/
    └── SKILL.md

命名约定：建议在 skill 名称中加入层级前缀（atom-、molecule-、compound-），使 agent 在 <available_skills> 列表中能直接从名称判断层级，无需加载正文。

---

2.5 创建流程（逐步）

第一步：确认层级 依据 2.1 节的问题表，确定本 skill 属于原子、分子还是化合物。

第二步：检查依赖是否存在

• 原子：无需检查
• 分子：确认所有依赖的原子 skill 已存在且可被 agent 定位
• 化合物：确认所有依赖的分子 skill 已存在

若依赖不存在，先创建依赖，再创建本 skill。自底向上创建。

第三步：创建目录和文件

mkdir -p skills/<layer>-<skill-name>
touch skills/<layer>-<skill-name>/SKILL.md

第四步：填写 frontmatter 按照 2.2 节的规范填写所有必填字段。

第五步：撰写正文 按照 2.3 节对应层级的模板撰写正文。关键原则：把能写进 skill 的判断逻辑全部写进去，不留给 agent 运行时猜测。

第六步：验证清单

完成后逐项检查：

• [ ] name 与目录名完全一致
• [ ] layer 字段值与实际行为一致
• [ ] description 清晰描述用途和触发场景
• [ ] 原子：不含 delegates-to，正文不引用其他 skill
• [ ] 分子/化合物：delegates-to 列出所有被调度的 skill，且均已存在
• [ ] 正文中的相对路径均可从 skill 目录正确解析
• [ ] 没有循环依赖（A → B → A）
• [ ] 没有跨层依赖（化合物直接调用原子）

---

2.6 常见反模式

反模式 1：原子做了多件事 原子试图在一次执行中完成两个独立操作。 → 拆分为两个原子。

反模式 2：依赖未声明 分子或化合物在正文中调用了某个 skill，但 delegates-to 中未列出。 → 补充 delegates-to 字段。

反模式 3：依赖不存在的 skilldelegates-to 中引用了尚未创建的 skill。 → 先创建依赖，再完成本 skill。

反模式 4：化合物直接调用原子 化合物跳过分子层，直接引用原子。 → 将相关原子先包装成分子，再由化合物调用。

反模式 5：description 写的是实现，而非触发场景 agent 根据 description 判断是否加载 skill，描述实现步骤对 agent 无帮助。 → description 应回答"在什么情况下我应该用这个 skill"。

反模式 6：全自动化合物 化合物设计为无需人类介入即可从头到尾执行。 → 化合物应在关键决策点设置人类确认节点。

---

附录：层级速查

维度	原子	分子	化合物
调用其他 skill	禁止	调用 2–10 个原子	调用多个分子
确定性	极高	高	中（允许不确定）
人类介入	无需	无需	需要
正文决策密度	极高（步骤级）	高（编排级）	中（策略级）
建议依赖上限	0	10 个原子	8–10 个分子
命名前缀	atom-	molecule-	compound-