翻遍 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 等数十个克隆，官方家族的虹吸效应明显。
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
拆 SKILL.md 之前必须先理解它的载体。larksuite/cli 是官方维护的 Go 语言 CLI（MIT 协议，npm 包 @larksuite/cli），官方 README 的自我定位是"built for humans and AI Agents"，并给出了三层命令体系：
+ 前缀）：人类与 AI 都友好的高级封装，带智能默认值和 dry-run 预览，如 lark-cli calendar +agenda；lark-cli api GET /open-apis/... 直调任意端点，覆盖官方宣称的 2500+ API。这个分层直接决定了 SKILL.md 的写法——Skill 的职责不是教模型“怎么调 HTTP”，而是教模型“在什么场景选哪一层、怎么避免踩坑”。这是它与 prompt 型 Skill 最本质的区别。
以下引用均来自仓库内 skills/lark-doc/SKILL.md 原文（v1.0.0）。
name: lark-doc
version: 1.0.0
description: "飞书云文档：创建和编辑飞书文档。从 Markdown 创建文档、获取文档内容、
更新文档（追加/覆盖/替换/插入/删除）、上传和下载文档中的图片和文件、搜索云空间文档。
当用户需要创建或编辑飞书文档、读取文档内容、在文档中插入图片、搜索云空间文档时使用；
如果用户是想按名称或关键词先定位电子表格、报表等云空间对象，也优先使用本 skill 的
docs +search 做资源发现。"
metadata:
requires:
bins: ["lark-cli"]
cliHelp: "lark-cli docs --help"
四个设计点值得逐个说：
requires.bins: ["lark-cli"]：声明二进制依赖。框架和 Agent 据此可以在缺 CLI 时直接给出可执行的修复动作，而不是运行到一半报 command not found。cliHelp 字段：给模型一个“忘了用法就跑这条命令”的逃生口，与 lark-shared 里“调用前先确认用法，别猜 flag 盲调”的准则呼应。**CRITICAL — 开始前 MUST 先用 Read 工具读取 `../lark-shared/SKILL.md`**，
其中包含认证、权限处理
正文第一行不是功能介绍，而是一条强制指令。官方 README 的说法是 lark-shared 会被所有其他 Skill 自动加载，而 lark-doc 内部又写了一条 CRITICAL 兜底——双保险。这是目前生态里少见的“Skill 依赖 Skill”写法：把认证、身份、输出契约这些横切关注点抽到一个 25 KB 级的共享文件，而不是在每个 Skill 里复制粘贴。代价是每次会话多一次文件读取，收益是安全规则只有一份、改一处全局生效。
这是全文最长的部分，也是最有教学价值的部分。核心是一张 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 是唯一可靠的做法。
## 重要说明：画板编辑
> ⚠️ lark-doc skill 不能直接编辑已有画板内容，但 `docs +update` 可以新建空白画板
随后分两个场景给出动作：已获取到画板 token 的引导去看 lark-whiteboard Skill；刚创建空白画板的教它从响应的 data.board_tokens 字段记录 token 再转交。大多数业余 Skill 只写“能做什么”，这份 SKILL.md 花了整整一节写能力边界和转交路径——模型知道“这事我干不了，但我知道该找谁”，比多十个功能更能减少胡编。
## 快速决策
- 用户说"找一个表格""按名称搜电子表格""找报表""最近打开的表格"，
先用 `lark-cli docs +search` 做资源发现。
然后是一张 Shortcut 表：+search、+create、+fetch、+update、+media-insert（标注“4步编排+自动回滚”）、+media-download、+whiteboard-update，每个都链接到 references/ 下的独立文档。主 SKILL.md 只负责“什么时候用哪个”，参数细节全部下沉到 references——典型的渐进披露（progressive disclosure）：常驻上下文的只有决策表，模型真正执行某操作时才加载那一份参考文档，token 成本被精确控制。
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-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：
反过来也有短板：全家桶上手门槛显著高于纯提示词 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 万的真实安装盘子。
# 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 分钟初始化的司机驾驶舱，而不是即开即用的玩具。
[!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 等场景全覆盖。