飞书Skill设计实践

飞书 Skill 设计实践

飞书 larksuite/cli(Lark CLI,2026-03 开源)给出了一套可直接抄的官方范例:26 个 Skill + skill-template + lark-skill-maker。本页把它当案例,把前几篇的原则在真实代码上看一遍。

📎 子页:Skill 切分 设计指南/Skill设计/Skill切分 · reference 切分 设计指南/Skill设计/reference切分 · 调 CLI 设计指南/Skill设计/SKILL里如何调用CLI。

---

一、全景:26 个 Skill 怎么分层

类别	Skill	角色
业务域(主轴)	lark-base lark-im lark-doc lark-calendar lark-sheets lark-drive lark-task lark-wiki lark-mail lark-vc lark-minutes lark-okr lark-approval lark-contact …	每个域独立闭环
横切共享	lark-shared	认证、身份、权限报错——所有域 Skill 首行 MUST 先读
产物编排	lark-workflow-meeting-summary lark-workflow-standup-report	跨域编排成一个交付物
工具兜底	lark-skill-maker lark-openapi-explorer	造 Skill / 挖原生 API
套件入口	master-skill-template(飞书全功能)	用「能力索引」路由到各域

切分逻辑详见 设计指南/Skill设计/Skill切分:域闭环为主轴、横切抽共享、产物薄编排、语义歧义(lark-vc vs lark-vc-agent)就拆。

二、SKILL.md = 路由器 + 护栏,不是知识库

lark-base/SKILL.md 很长,却没有一行 API 参数文档。它自己定下原则:

「SKILL 只保留路由、风险和复杂 JSON/DSL;简单命令由命令自身的参数、tips 和错误恢复承接。」

正文 = 7 个固定区块:

区块	作用
何时用 / 不用	触发边界,反例直接写「转哪个 Skill」
使用边界	与其他 Skill 的转交(导入转 drive、认证转 shared)
快速路由表	心脏:目标 → 命令 → 何时读 reference
心智模型	领域语义护栏(存储字段可写、formula/lookup 只读)
前置/查询/写入规则	经验与坑(7 条查询规则反「拿一页当全量」)
Token 解析 / 错误恢复表	确定性映射(URL→token、错误码→恢复动作)
保留 Reference	索引,每份一句话说明

实样:一个域 Skill(lark-im)长什么样

frontmatter——description 塞满触发词 + 「当用户需要…时使用」,requires.bins 声明硬依赖:

---
name: lark-im
description: "飞书即时通讯:收发消息和管理群聊。…当用户需要发消息、查看或
  搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊时使用。"
metadata:
  requires: { bins: ["lark-cli"] }
  cliHelp: "lark-cli im --help"
---
**CRITICAL — 开始前 MUST 先读 ../lark-shared/SKILL.md(认证、权限)**

Shortcuts 表——每个 +verb 一行说明,并链到自己的 reference(+verb → 说明 → 详细文档):

## 快捷命令(优先用)
| Shortcut         | 说明 |
| +chat-create     | 建群/话题群;user/bot;--chat-mode group|topic;可设机器人管理员 |
| +chat-search     | 按关键词/成员搜可见群,拿 chat_id;支持类型过滤、分页 |
| +messages-mget   | 按 ID 批量取消息;一次最多 50 个 om_ 消息;自动格式化发件人名 |

意图→命令索引(skill-template/domains/base.md 的护栏式路由):

| 意图           | 推荐命令                              | 备注 |
| 查表字段        | table.fields list                    | 写记录/更新前必调 |
| 按视图筛选查询   | view.filter update + table.records list | base/v3 没独立 search |
| 更新记录        | table.records patch                  | 只传需变更的字段 |

错误码速查(确定性映射,模型照表爬坑):

| 1254045 字段名不存在 | 检查字段名(含空格、大小写) |
| 1254066 人员字段错误 | 传 [{ "id": "ou_xxx" }]    |
| 1254104 批量超 200   | 分批调用                   |
| 1254291 并发写冲突   | 串行写入 + 批次间延迟 0.5–1s |

这几张表加起来就是 §二 说的「路由 + 护栏 + 复杂结构」——没有一行在复制 API 的 flag 文档。

三、reference = SSOT,guide + schema 分层

lark-base 25 份 reference,按高熵复杂结构切,各成唯一真源:

• 公式 formula-field-guide.md(55KB)、workflow …-workflow-schema.md(39KB)、角色 role-config.md(21KB)、聚合 DSL …-data-query.md(20KB)。
• 入口 + 真源双层:workflow-guide(怎么用,先读)+ workflow-schema(完整 JSON SSOT,深入读)。
• 简单命令(list/get/enable)无 reference。

详见 设计指南/Skill设计/reference切分:25 份不是「知识多」,是「25 个互不重叠、各自只被一类任务触发」的点。

四、命令三档 + schema 先查

lark-cli <service> +<verb>                      # L1 Shortcut（场景封装，优先）
lark-cli <service> <resource> <method>          # L2 已注册 API（原子，可组合）
lark-cli api <METHOD> <path> [--data/--params]  # L3 裸 OpenAPI（低频兜底）
lark-cli schema <service.resource.method>       # 调用前必查参数，不猜字段

优先级 L1 > L2 > L3,详见 设计指南/Skill设计/SKILL里如何调用CLI。CLI 没覆盖的接口,用 lark-openapi-explorer 从官方文档逐层挖,再 api 裸调。

五、飞书独有的几个工程细节(值得抄)

① 每个 Skill 自带权限表 + 结构化错误

正文末尾列 操作 → 所需 scope;报错走结构化字段引导修复:

• permission_violations(缺哪些 scope,N 选 1)· console_url(后台配置链接)· hint(建议命令)。
• 最小权限增量授权:lark-cli auth login --scope "calendar:calendar:readonly",多次 login 累积。

② 身份模型 user / bot,错误别盲目重试

--as user(用户资源)vs --as bot(应用资源);bot 看不到用户日历/云盘。91403 / ErrNotInGray 这类不要循环换身份重试,按既定流程转 lark-shared 或提示用户。

③ 硬门控 flag:把「读了文档」变成强制 gate

建公式/lookup 字段前必须先读 guide,读完才允许加隐藏 flag --i-have-read-guide,CLI 在执行层卡住。不靠模型自觉读文档,靠 flag 钉死——「确定性覆盖概率性」的极致。

④ frontmatter 声明硬依赖

metadata:
  requires:
    bins: ["lark-cli"]      # 让 Harness 知道前置工具
  cliHelp: "lark-cli base --help"

⑤ 套件级渐进披露:hub Skill + 能力索引

master-skill-template(飞书全功能)不含细节,用能力索引路由:「根据用户需求,必须读取对应业务域的详细文档」,再给一个命令探索阶梯兜底:

lark-cli <service> <resource> <method>   # 调原生 API
lark-cli schema <service.resource.method># 调用前查参数结构
lark-cli <service> --help                # 列出某域可用资源和命令
lark-cli --help                          # 探索更多能力

一个总入口,平时只占能力索引那几行;用到哪个域,才 Read 哪份域文档、或 --help 逐层展开。这是 §三 的渐进披露上升到套件级。

六、lark-skill-maker:飞书版 Skill Creator 的 4 原则

飞书自己造 Skill 的工具,把要点压成 4 条(与 Anthropic Skill Creator 高度一致):

1. description 决定触发 —— 功能词 + 「当用户需要…时使用」
2. 认证 —— 说明所需 scope,lark-cli auth login --domain <name>
3. 安全 —— 写操作前确认意图,建议 --dry-run 预览
4. 编排 —— 讲清数据传递 / 失败回滚 / 可并行步骤

可借鉴清单(抄飞书的话抄这些)

• SKILL.md 当路由器:只放路由 / 风险 / 复杂结构,简单命令交给 CLI 自己
• 横切关注点(认证/权限)抽成 lark-shared 式共享 Skill,各 Skill 首行引用
• reference 按高熵结构切,guide + schema 双层,命名带语义后缀
• 命令三档 + schema 先查,高频场景上提到 L1 Shortcut
• 每 Skill 带权限表,错误用 code/hint/console_url 结构化引导
• 高风险动作用 CLI flag 硬门控(--i-have-read-guide)而非口头叮嘱
• 产物型 Skill 做薄编排层,复用域 Skill 不重定义

---

回到原则:Skill 设计 设计指南/Skill设计 · CLI 深规范 设计指南/CLI设计/CLI设计规范。

← 返回 设计指南/Skill设计