<!-- title: 2200万安装的飞书Skill家族拆解 -->

# 生态里最大的Skill家族：飞书lark全家桶，SKILL.md逐段拆解

## 概述

翻遍 skills.sh 总榜会发现一个被多数人忽略的事实：单款 Skill 安装量冠军是 300 万的 find-skills，但**单一厂商的最大 Skill 家族既不是 Vercel 也不是 Matt Pocock，而是飞书**。据 skills.sh 2026-08-29 数据，`open.feishu.cn` 名下 24 个 lark 系列 Skill 合计约 1420 万安装，`larksuite/cli` 仓库名下另有约 790 万，两渠道合计约 2200 万——是 find-skills 的 7 倍。本期第 2 轮深拆，选取家族入口 Skill `lark-doc`（单 Skill 约 60 万安装）与其共享底座 `lark-shared`，逐段拆到 SKILL.md 每一行的设计意图。核心发现：这是一套与“纯提示词 Skill”完全不同的**CLI 封装型 Skill 工程体系**，它的共享底座、强触发索引、退出码 10 高危门禁，代表了企业级 Skill 写法的天花板。

## 生态坐标：一个域名发布商，三个渠道矩阵

先看它在总榜里的位置。skills.sh 总榜 All Time 前段被两类账号占据：个人开发者（mattpocock/skills 一人占了榜单 12 席中的 9 席）和厂商账号。飞书的特殊之处在于它是**用域名做发布商**的：

| 发布渠道 | 代表 Skill | 家族合计安装 | 备注 |
|---|---|---|---|
| open.feishu.cn（域名） | lark-doc 约 60万 | 约 1420 万 / 24 个 | 国内飞书官方域名直发 |
| larksuite/cli（GitHub） | lark-doc 约 43万 | 约 790 万 / 19+ 个 | 开源 CLI 仓库随附 |
| open.larksuite.com（域名） | lark-doc 约 2.9K | 数千级 | 国际版 Lark 域名 |

三个渠道发布同名 Skill、安装量分开计数，这本身就是生态里少见的“分发矩阵”打法。作为对比：microsoft/azure-skills 家族合计约 750 万，remotion-dev 约 487 万级别，都不及飞书单渠道。搜索页还能看到长尾——社区仿写品 `lark-mcp`（whatevertogo/feishuskill，约 3.1K 安装）、`feishu-create-doc` 等数十个克隆，官方家族的虹吸效应明显。

```mermaid
mindmap
  root((lark Skill家族<br/>约2200万安装))
    发布渠道
      open.feishu.cn 域名直发<br/>约1420万
      larksuite/cli GitHub仓库<br/>约790万
      open.larksuite.com 国际版
    共享底座
      lark-shared<br/>认证/身份/输出契约/安全规则
    业务Skill 20余个
      文档 lark-doc
      表格 lark-sheets
      多维表格 lark-base
      日历 lark-calendar
      消息 lark-im
      邮件 lark-mail
      会议 lark-meeting
    工作流Skill
      会议纪要汇总
      站会报告
    元Skill
      lark-skill-maker<br/>自定义Skill框架
      lark-openapi-explorer<br/>探索2500+底层API
```

## 家族架构：CLI 是地基，Skill 是说明书

拆 SKILL.md 之前必须先理解它的载体。`larksuite/cli` 是官方维护的 Go 语言 CLI（MIT 协议，npm 包 `@larksuite/cli`），官方 README 的自我定位是"built for humans and AI Agents"，并给出了三层命令体系：

1. **Shortcuts（`+` 前缀）**：人类与 AI 都友好的高级封装，带智能默认值和 dry-run 预览，如 `lark-cli calendar +agenda`；
2. **API Commands**：从飞书开放平台元数据自动生成、经质量门禁筛选的 100+ 命令，与平台端点一一对应；
3. **Raw API**：`lark-cli api GET /open-apis/...` 直调任意端点，覆盖官方宣称的 2500+ API。

这个分层直接决定了 SKILL.md 的写法——**Skill 的职责不是教模型“怎么调 HTTP”，而是教模型“在什么场景选哪一层、怎么避免踩坑”**。这是它与 prompt 型 Skill 最本质的区别。

## lark-doc SKILL.md 逐段拆解

以下引用均来自仓库内 `skills/lark-doc/SKILL.md` 原文（v1.0.0）。

### 第一段：frontmatter——把触发词写进口语

```yaml
name: lark-doc
version: 1.0.0
description: "飞书云文档：创建和编辑飞书文档。从 Markdown 创建文档、获取文档内容、
更新文档（追加/覆盖/替换/插入/删除）、上传和下载文档中的图片和文件、搜索云空间文档。
当用户需要创建或编辑飞书文档、读取文档内容、在文档中插入图片、搜索云空间文档时使用；
如果用户是想按名称或关键词先定位电子表格、报表等云空间对象，也优先使用本 skill 的
docs +search 做资源发现。"
metadata:
  requires:
    bins: ["lark-cli"]
  cliHelp: "lark-cli docs --help"
```

四个设计点值得逐个说：

- **description 全中文、塞满口语动词**。“创建/编辑/读取/插入/搜索”每个动词对应一类真实用户请求。对比 mattpocock 系 Skill 偏好的一句话式英文 description，这里是为中文用户触发率做的显式优化。
- **description 里藏了跨域路由**。最后一句“如果用户是想按名称或关键词先定位电子表格、报表……也优先使用本 skill 的 docs +search”——文档 Skill 主动把“找表格”这类本属 lark-sheets 的流量先接到自己手里做资源发现，再转交。这是一种**入口 Skill（entry-point skill）设计**：宁可自己多接一步，不让模型在 20 个 Skill 里犹豫。
- **`requires.bins: ["lark-cli"]`**：声明二进制依赖。框架和 Agent 据此可以在缺 CLI 时直接给出可执行的修复动作，而不是运行到一半报 command not found。
- **`cliHelp` 字段**：给模型一个“忘了用法就跑这条命令”的逃生口，与 lark-shared 里“调用前先确认用法，别猜 flag 盲调”的准则呼应。

### 第二段：CRITICAL 依赖声明——Skill 之间的显式引用

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

正文第一行不是功能介绍，而是一条强制指令。官方 README 的说法是 lark-shared 会被所有其他 Skill 自动加载，而 lark-doc 内部又写了一条 CRITICAL 兜底——**双保险**。这是目前生态里少见的“Skill 依赖 Skill”写法：把认证、身份、输出契约这些横切关注点抽到一个 25 KB 级的共享文件，而不是在每个 Skill 里复制粘贴。代价是每次会话多一次文件读取，收益是安全规则只有一份、改一处全局生效。

### 第三段：Token 概念表——给模型装“世界观”

这是全文最长的部分，也是最有教学价值的部分。核心是一张 URL 格式对照表：

| URL 格式 | Token 类型 | 处理方式 |
|---|---|---|
| `/docx/` | `file_token` | 直接使用 |
| `/doc/` | `file_token` | 直接使用 |
| `/wiki/` | `wiki_token` | ⚠️ **不能直接使用**，需先查询获取真实 `obj_token` |
| `/sheets/` | `file_token` | 直接使用 |
| `/drive/folder/` | `folder_token` | 作为文件夹 token 使用 |

为什么这张表值钱？因为“知识库链接背后的 token 不是文档 token”是飞书 API 真实的高频坑——模型拿到一个 `/wiki/wikcnXXX` 链接，最自然的反应是拿路径里的 token 去调文档接口，然后收到一个莫名其妙的报错。SKILL.md 不但用 ⚠️ 标出，还给出完整处理流程：先跑 `lark-cli wiki spaces get_node` 查询节点，从返回的 `obj_type`/`obj_token` 字段取真实值，再按类型路由到 `docx.*`/`sheets.*`/`bitable.*` 等对应 API。后面甚至附了一段 ASCII 资源关系树（Wiki Space → Wiki Node → 各类型文档）帮助模型建立心智模型。

**这一段是“给模型写文档”和“给人写文档”的分水岭**：人类开发者会去查 API 文档，模型没有“查了再试”的耐心，把坑直接预判进 SKILL.md 是唯一可靠的做法。

### 第四段：边界声明——先说不能做什么

```markdown
## 重要说明：画板编辑
> ⚠️ lark-doc skill 不能直接编辑已有画板内容，但 `docs +update` 可以新建空白画板
```

随后分两个场景给出动作：已获取到画板 token 的引导去看 `lark-whiteboard` Skill；刚创建空白画板的教它从响应的 `data.board_tokens` 字段记录 token 再转交。大多数业余 Skill 只写“能做什么”，这份 SKILL.md 花了整整一节写**能力边界和转交路径**——模型知道“这事我干不了，但我知道该找谁”，比多十个功能更能减少胡编。

### 第五段：快速决策 + Shortcuts 表——渐进披露的双层结构

```markdown
## 快速决策
- 用户说"找一个表格""按名称搜电子表格""找报表""最近打开的表格"，
  先用 `lark-cli docs +search` 做资源发现。
```

然后是一张 Shortcut 表：`+search`、`+create`、`+fetch`、`+update`、`+media-insert`（标注“4步编排+自动回滚”）、`+media-download`、`+whiteboard-update`，每个都链接到 `references/` 下的独立文档。主 SKILL.md 只负责“什么时候用哪个”，参数细节全部下沉到 references——典型的**渐进披露（progressive disclosure）**：常驻上下文的只有决策表，模型真正执行某操作时才加载那一份参考文档，token 成本被精确控制。

```mermaid
flowchart TD
    A[用户请求] --> B{请求类型?}
    B -->|找一个表格/报表| C["docs +search 资源发现"]
    C --> D{找到的对象类型?}
    D -->|电子表格| E[转交 lark-sheets]
    D -->|文档| F[lark-doc 自己处理]
    B -->|文档操作| F
    F --> G{URL 是 /wiki/ 格式?}
    G -->|是| H["wiki.spaces.get_node<br/>换取真实 obj_token"]
    H --> I{obj_type?}
    I -->|docx/doc| J[文档 API]
    I -->|sheet| E
    I -->|bitable| K[转交 lark-base]
    G -->|否| J
    B -->|编辑已有画板| L[转交 lark-whiteboard]
    F -.开头必读.-> M[../lark-shared/SKILL.md]
```

## lark-shared：共享底座才是精华

如果说 lark-doc 展示的是“业务 Skill 怎么写”，`lark-shared/SKILL.md`（v1.1.0）展示的是“平台型 Skill 怎么管住模型的手”。它的 description 是英文的、面向 flag 级触发："auth login/status/logout, user vs bot identity, ... missing scopes, or handling _notice JSON"——底座关心的是机器问题，业务 Skill 才关心人的口语。四个设计值得单独立传：

**其一，身份模型讲成第一准则。**通用准则第 2 条：`--as user` 代表用户本人、`--as bot` 代表应用自己，并特别警告“bot 查用户资源会返回**空成功而非报错**”——这是又一种“静默失败”型大坑，不写进 SKILL.md 模型永远以为查询成功只是没数据。

**其二，输出契约纠偏。**准则第 4 条原文：“判断成功用 `ok == true`（或进程退出码 0），**不要用 `code == 0`**”，并解释了原因——成功信封没有顶层 `code` 字段，按 OpenAPI 老格式判断会把所有成功调用误判为失败，“封装写入类命令时尤其危险”。这是从无数次真实误判里提炼出来的一条，典型的“被坑过才知道要写”。

**其三，退出码 10 高危门禁。**安全规则第 4 条是全文最硬的一条：退出码 10 不是错误，而是高风险写入操作的确认门禁——必须停下、向用户展示 `action`/`risk`/关键参数、取得**显式同意**后把确认 flag 追加到原始 argv 末尾重试，“**绝不**静默加确认 flag 绕过”。加粗写死。这等于把 human-in-the-loop 做成了协议：模型想绕都绕不过去，因为绕过的动作本身被明文禁止了。

**其四，Reference 强触发索引。**文末一张两列表格：左列是触发条件（如“遇到 `missing_scopes` 或 `console_url`"“准备执行 high-risk-write”“输出含 `_notice`"），右列是必读的 reference 文件，并规定“命中多条时按表中顺序读取，同一 reference 只读取一次”。这把渐进披露从“模型自行判断要不要读”升级成了**条件→动作的确定性映射**，大幅降低了漏读率。

## 设计模式提炼：能抄走的三条

从这套 SKILL.md 里可以提炼出几条可迁移的写法，适用于任何 CLI 封装型 Skill：

1. **description 写用户口语，不写功能清单。**lark-doc 的 description 里“找一个表格”“按名称搜电子表格”这类引号短语，就是预期用户会敲的原话。你的 description 应该是触发词的集合，不是 README 的缩写。
2. **坑要写成“症状→动作”，不是“注意事项”。**“wiki token 不能直接用”配上立即执行的命令和字段提取步骤，模型才用得起来。只写“注意 wiki 链接需要特殊处理”等于没写。
3. **危险操作走协议不走自觉。**lark-shared 用退出码把“该不该问用户”变成了机器可判断的状态，再用加粗禁令封死绕过路径。凡是会花钱、删数据、发消息出去的 Skill，都值得抄这个模式。

反过来也有短板：全家桶上手门槛显著高于纯提示词 Skill——装 CLI、`config init` 建应用、OAuth 授权一个不能少，官方自己估的流程是“3 分钟”但前提是你有飞书开放平台账号。另外 README 披露 CLI 默认随请求上报操作系统类型和硬件型号作为风控信号（可用 `lark-cli config risk-control off` 关闭），对隐私敏感的用户是个需要知道的点。

## 评测对比表

| 维度（权重） | lark-doc | lark-shared | 家族整体（以 lark-sheets/base 为代表） |
|---|---|---|---|
| 功能完整度 25% | ★★★★★ | ★★★★ | ★★★★ |
| 设计质量 25% | ★★★★★ | ★★★★★ | ★★★★ |
| 实战效果 20% | ★★★★ | ★★★★ | ★★★★ |
| 上手难度 15% | ★★★ | ★★★ | ★★★ |
| 社区活跃度 15% | ★★★★★ | ★★★★★ | ★★★★★ |
| **加权总分** | **4.50** | **4.25** | **3.90** |

上手难度给 3 星是诚实的：对已有飞书团队的用户几乎零成本（官方安装脚本一路自动化），对个人开发者则有建应用、配权限的真实摩擦。社区活跃度 5 星基于两点：官方团队高频维护（README 与 Skill 同仓库演进，CLI 明确写着“每个命令都用真实 Agent 测试过”），以及约 2200 万的真实安装盘子。

## 安装与使用

```bash
# 1. 安装 CLI（npm 分发，Go 二进制）
npx @larksuite/cli@latest install

# 2. 安装 Skill 到全局（Claude Code / Cursor 等 20+ Agent 通用）
npx skills add larksuite/cli -y -g

# 3. 配置应用凭证（后台运行，输出授权 URL 交给用户）
lark-cli config init --new

# 4. 登录（--recommend 自动勾选常用 scope）
lark-cli auth login --recommend

# 5. 验证
lark-cli calendar +agenda
```

## 适用与不适用

**适合**：团队已用飞书/Lark 且想让 Agent 读写文档、表格、多维表格、日历、会议纪要；想把周报、站会纪要、OKR 更新这类重复操作交给 Agent；想研究“CLI+Skill”范式怎么做的开发者（这套仓库本身就是最好的参考实现）。

**不适合**：不用飞书生态的团队——约 22 个 Skill 全部绑定 lark-cli，没有飞书账号一个都用不了；只想轻量读取公开文档、不想建应用走 OAuth 的场景；以及期待“装完就能干活”的新手——它更像一套需要 10 分钟初始化的司机驾驶舱，而不是即开即用的玩具。

## 推荐排行榜

- **SKILL.md 设计质量榜**：lark-doc 与 lark-shared 并列第一。前者是渐进披露+入口路由的范本，后者是安全门禁+强触发索引的范本，两份加起来是目前公开可见的最完整的企业级 Skill 工程教材。
- **“最值得抄的一段”**：lark-shared 的 Reference 强触发索引表。任何 Skill 只要超过 200 行，都该有这张表。
- **生态意义**：它是第一个用“域名发布商”身份、以三渠道矩阵进入总榜的传统软件厂商——对观望中的 SaaS 公司而言，飞书已经把“官方 Skill 该怎么做”的模板焊死了。

## 参考来源

1. [Skills Leaderboard — skills.sh](https://skills.sh/) — 2026-08-29 抓取的总榜数据：find-skills 3.0M、lark 家族 14.2M/7.9M、azure-skills 7.5M 等安装量均出自此处
2. [larksuite/cli — GitHub](https://github.com/larksuite/cli) — 官方 README：三层命令体系、24~26 个 Skill 清单、安装流程、安全与风控披露
3. [lark-doc SKILL.md 原文](https://raw.githubusercontent.com/larksuite/cli/main/skills/lark-doc/SKILL.md) — 本文逐段拆解的第一手文本（v1.0.0）
4. [lark-shared SKILL.md 原文](https://raw.githubusercontent.com/larksuite/cli/main/skills/lark-shared/SKILL.md) — 共享底座全文（v1.1.0），退出码 10 门禁与强触发索引出处
5. [skills.sh 搜索页：lark-doc](https://skills.sh/search?q=lark-doc) — 三渠道安装量对照与社区仿写品长尾数据

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)