Skill切分

Skill 怎么切分:一个还是多个

一句话判据:一个 Skill = 能独立闭环完成的一类任务,或 一个明确的交付产物。既不是「一个 API 一个 Skill」(太碎),也不是「一个 Skill 管全部」(太粗)。

📎 实例取自飞书 larksuite/cli 的 26 个官方 Skill;本页是设计指南/Skill设计的子页。

核心判据:闭环 + 交付物

切 Skill 不是按「功能模块」切,是按**「谁能独立把一件事干完」**切。两个落点:

能闭环完成一类任务 → 一个 Skill。用户说一句话,这个 Skill 能从理解意图到给出结果,中途不需要切到别的能力。
产出一个明确交付物 → 一个 Skill。哪怕它跨多个能力域,只要最终交付的是「一份会议周报」「一张调研大纲」,就值得为这个产物单独立一个 Skill。

反过来:如果一段能力永远不能独立交付什么,只是被别人调用的公共规则(认证、口径),它不该是一个面向用户的 Skill,而该是共享 Skill(见下)。

五种切法(飞书 26 个 Skill 实证)

切法	判据	飞书实例
① 按业务域闭环(主轴)	一个域内的任务能自成闭环	`lark-base` / `lark-im` / `lark-doc` / `lark-calendar` / `lark-sheets`…… 每个域独立完成该域全部任务
② 横切关注点抽共享	多个 Skill 都要、但自己不交付什么	`lark-shared`:认证、身份 `--as`、权限报错处理。每个域 Skill 首行 `MUST 先读 ../lark-shared/SKILL.md`
③ 按交付产物编排	跨多个域,但目标是一个产物	`lark-workflow-meeting-summary`(会议周报 = vc + drive)、`lark-workflow-standup-report`(日程待办摘要 = calendar + task)
④ 按语义/阶段拆歧义	同一对象,但混在一起会触发错	`lark-vc`(会后查询)vs `lark-vc-agent`(会中动作):同是「会议」,按时间阶段拆成两个,明确「按此分工路由,避免语义混淆」
⑤ 工具能力独立	低频、探索性、给别的 Skill 兜底	`lark-skill-maker`(造 Skill)、`lark-openapi-explorer`(挖原生 API)

重点一:产物型 Skill 是「薄编排层」,不重新定义

lark-workflow-meeting-summary 自己几乎不含领域知识——它 Read 了 lark-vc/SKILL.md 和 vc 的领域边界文档,然后只写编排:

{时间范围} ─► vc +search ──► 会议列表 ──► vc +notes ──► 纪要 tokens ──► AI 汇总 ──► 周报

lark-vc-agent 也明说「核心概念直接复用 lark-vc,不再重复定义」。

法则:产物/工作流型 Skill 坐在域 Skill 之上,只负责「按什么顺序调谁、数据怎么传、失败怎么回滚」,绝不复制底层域的概念与命令。这样底层域一改,编排层自动跟上。

重点二:语义歧义大就拆,别硬塞

lark-vc 和 lark-vc-agent 操作的都是「会议」,本可合成一个。飞书拆开,因为「会后查纪要」和「会中让机器人入会读事件」触发语境完全不同,合在一起会:① description 太杂、触发不准 ② 正文里两套流程互相干扰。

法则:当一个 Skill 的「何时用」里出现两组互不相干的触发语境,且各自都能独立闭环,就该拆。判断信号:你在写反例边界时,发现「该用 A 却触发 B」的风险很高。

三个真实案例(看飞书怎么下刀)

案例 A · 产物型薄编排 —— `lark-workflow-meeting-summary`

「整理这周的会议纪要、生成周报」是一个交付物,要跨 vc + drive + doc 三个域。飞书没把它塞进 lark-vc,而是单立一个工作流 Skill。它的正文几乎只有编排——领域知识全靠 Read 别的域 Skill:

**CRITICAL — 开始前 MUST 先读 ../lark-shared/SKILL.md(认证)**;
然后读 ../lark-vc/SKILL.md 了解会议纪要操作。

## 工作流
{时间范围} ─► vc +search ──► 会议列表(meeting_ids)
          ─► vc +notes  ──► 纪要 tokens(note_doc_token)
          ─► drive metas batch_query ──► 文档链接 ──► 结构化报告
### Step 5: 生成文档(可选)
阅读 ../lark-doc/SKILL.md,用 docs +create 落地

每一步都是调别的域的命令(vc +search / vc +notes / drive metas batch_query / docs +create),工作流自己只管顺序 + 数据怎么传(meeting_ids → note_doc_token → 文档链接)。

这就是「薄编排层坐在域 Skill 之上」:vc 域命令一改,周报 Skill 不用动。判据命中:它交付一个明确产物(周报),且跨域——按产物切。

案例 B · 语义阶段拆分 —— `lark-vc` vs `lark-vc-agent`

两个 Skill 操作的都是「会议」,却被拆开,因为触发语境是两组:

Skill	description(节选)	触发语境
`lark-vc`	搜索历史会议、参会人快照、纪要/逐字稿/录制	会后查询
`lark-vc-agent`	机器人代入会/离会、读取进行中会议的实时事件	会中动作

lark-vc-agent 正文直接给路由表消歧:

| 用户意图              | 应路由到                         |
| "帮我入会 123456789"  | 本 skill +meeting-join          |
| "昨天那场会有谁参加"   | lark-vc                         |
| "参会后把纪要发到群"   | 本 skill(入会→读事件→离会)→ lark-vc(拉纪要)→ lark-im(发群) |

判据命中:「会后查纪要」和「会中入会读事件」是两组互不相干的触发语境,各自能独立闭环——按语义/阶段拆。跨阶段的复合需求则用编排(最后一行)把两个 Skill 串起来。

案例 C · 横切共享 —— `lark-shared`

认证、身份(--as user/bot)、权限报错处理,几乎每个 Skill 都要、但谁也不靠它单独交付。飞书抽成一个 lark-shared,每个域 Skill 正文第一行都是同一句:

**CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md,
其中包含认证、权限处理**

判据命中:它永远不独立交付什么,只被别人依赖——不做成面向用户的 Skill,做成共享 Skill,公共规则只写一处。

切太碎 vs 切太粗(两个坏味道)

坏味道	症状	后果
太碎(一个 API 一个 Skill)	`base-record-create`、`base-record-update`…… 各自成 Skill	metadata 爆炸(常驻成本飙升)、路由困难、公共规则到处抄
太粗(一个 Skill 管全部)	一个 `lark` Skill 把 base+im+doc+calendar 全塞进去	正文几千行、references 永远全加载、触发命中率低

飞书的平衡点:按域闭环(②)做主轴,横切抽共享(②),产物再单独编排(③)。lark-base 一个 Skill 管多维表格全部(建表/字段/记录/视图/公式/仪表盘/workflow/角色),但不把它再拆成几十个;同时多维表格也不和即时消息合并。

落到你的世界(本仓库类比)

按闭环:问数类 Skill = 「一类业务的提问」能闭环;bw-todo = 待办的增删查改+推送能闭环。
按产物:business-survey-outline(调研大纲)、报告类 Skill(一份报告)——产物导向,可跨多个底层能力。
横切共享:口径/术语/认证如果被多个 Skill 共用,抽成一份共享 reference 或共享 Skill,别每个都抄。

自检清单

这个 Skill 能独立闭环完成一类任务,或交付一个明确产物?
它的「何时用」是不是一组连贯的触发语境(没有两组互不相干的)?
公共规则(认证/口径)有没有抽成共享 Skill / reference,而不是各抄一份?
产物型 Skill 是不是薄编排层(复用域 Skill,不重定义概念)?
有没有切太碎(一个 API 一个)或太粗(一个管全部)?

切完之后:每个 Skill 内部的 reference 怎么切 → 设计指南/Skill设计/reference切分;正文怎么描述调 CLI → 设计指南/Skill设计/SKILL里如何调用CLI;飞书整体实践 → 设计指南/Skill设计/飞书Skill设计实践。

← 返回设计指南/Skill设计