Skill设计
🧩 Skill 设计 · 能力层
Section titled “🧩 Skill 设计 · 能力层”定位:Skill 不是「更长的 prompt」,是把一个场景的经验 / 流程 / 工具 / 输出契约沉淀成给 AI 用的可复用资产(服务对象是 AI,不是人)。本层关注:能不能被叫起来(触发率)、叫起来后怎么组织、怎么迭代到稳定。
📎 来源:实践分享第二章 + 好 Skill 与 AI 原生 CLI/CI 设计指南 + Anthropic Skill Creator + 飞书 Lark CLI 官方实践。配套 CLI 规范见 设计指南/CLI设计/CLI设计规范。
核心命题:用确定性,覆盖概率性
Section titled “核心命题:用确定性,覆盖概率性”Skill 不是教模型新知识——是把模型「凭概率猜」的地方,换成「按规则做」。
模型能力越强、翻车越多,根因是训练方式本身的六大结构性缺陷,Skill 逐一用确定性钉死:
| 缺陷 | Skill 的解法 | 例 |
|---|---|---|
| ① 知识时效断层 | references/ 随时更新,知识与模型解耦 | 库升 v3,只改 api.md,AI 立刻按新版写 |
| ② 私有知识不可获取 | SKILL.md 编码私有流程/口径 | 「单方成本=不含税÷可售面积」写进正文 |
| ③ 会踩坑(毒性遗产) | 确定性规则「永远这样/永远别那样」 | docx 写死 Always DXA, never PERCENTAGE |
| ④ 缺质量标准 | 精确定义输入输出规范 | 报告必须六段式、结论前置 |
| ⑤ 不知用什么工具 | scripts/ 把最佳路径编码成脚本 | 查数固定调 query.py,不纠结 SQL/API |
| ⑥ 缺样例参考 | 正文/references 内置范本=永久 Few-shot | 内置「投标评分表」标准范本 |
证据:docx 的
never PERCENTAGE、never unicode bullets这些话人类开发者根本不需要——它只对 AI 有意义,这就是「Skill 是给 AI 用的」最硬的证明。
三级加载:能力很大,context 很小
Section titled “三级加载:能力很大,context 很小”| 层级 | 内容 | 关键点 |
|---|---|---|
| L1 · metadata | name + description 常驻(~1500 token / 40 个 Skill) | AI 靠它判断该不该用 |
| L2 · SKILL.md | 按需载入完整正文 | 真要操作时才读进来 |
| L3 · references / scripts | 关联资源 / 脚本 | 脚本不进 context,由 Harness 执行,AI 只读 stdout |
用户没碰 Excel 时,整个技能只占描述那几十字;一旦说「改这张表」,才逐层把正文、
formulas.md、recalc.py取进来。详见 设计指南/本体设计 的渐进披露。
目录解剖(三类资源各司其职):
skill-name/├── SKILL.md # 必需:frontmatter(name+description) + 正文指令├── scripts/ # 确定性/重复动作的可执行脚本(不进 context,执行即可)├── references/ # 按需载入的补充文档(API、术语、DSL 规范)└── assets/ # 产物用的静态资源(模板、字体、图标)造一个 Skill:从草稿到稳定的 5 步闭环
Section titled “造一个 Skill:从草稿到稳定的 5 步闭环”Skill 不是「写完即交付」,是测出来、迭代出来的。Skill Creator 的核心不是模板,而是这个循环。
| 步 | 做什么 | 要点 |
|---|---|---|
| 1 捕获意图 | 问清 4 件事:① 让 AI 能做什么 ② 什么话/场景该触发 ③ 期望输出格式 ④ 要不要测试用例 | 若对话里已有现成流程(「把刚才这套变成 skill」),先从历史里抽:用过的工具、步骤顺序、用户的纠正、输入输出样子 |
| 2 写草稿 | 先填 frontmatter,再写正文核心流程/边界/导航 | 草稿写完换一双眼睛重读再改;别一上来追求完美 |
| 3 跑测试 | 造 2–3 条「真用户会怎么说」的 prompt,带 skill 跑一遍,并跑一条不带 skill 的基线 | 没有基线就不知道 skill 到底有没有用;输出可客观验证的(文件转换、抽取、固定流程)才值得配测试集 |
| 4 看结果迭代 | 人看产物 + 量化指标一起评;读 trace 不只看终稿 | 从反馈泛化(别 overfit 到这几个例子);删不拉车的内容(prompt 要瘦);三条 case 都各自写了同一个 create_docx.py→该把它收进 scripts/ |
| 5 优化触发 + 打包 | 用触发评测集专门调 description(见下),再打包交付 | description 是触发的唯一机制,值得单独优化一轮 |
这是概念级闭环;评测怎么分层落地、会话 JSONL 怎么当数据源,见 评测与改进/评测。
Skill Creator 四原则
Section titled “Skill Creator 四原则”| 原则 | 含义 |
|---|---|
| 简洁 | SKILL.md 不是知识库——上下文窗口是公共资源。正文放核心流程/触发/边界/导航,详细业务知识进 references/,易错执行进 scripts/,模板进 assets/。 |
| 自由度匹配脆弱度 | 文本分析=高自由度(给原则);业务流程=中自由度(给框架+检查点);文件写入/写操作/财务=低自由度(用脚本/CLI 固化)。高自由度放 Skill,低自由度放 CLI。 |
| 渐进披露 | Skill 像地图不是百科:「A 场景看 references/a.md;要执行调 CLI;高风险先 dry-run」。 |
| 不重复 | CLI 已有 help/doctor/schema/examples 就不在 Skill 里复制完整参数说明,只写「默认先 doctor、查询用 query、写操作先 dry-run」。 |
Skill 负责「判断何时做什么」,CLI/CI 负责「稳定地把动作做对」。详见 设计指南/CLI设计/CLI设计规范。
官方范例 —— 飞书 Lark CLI 的 26 个官方 Skill 怎么组织(2026-03 开源,larksuite/cli):
- 横切关注点抽成「共享技能」:认证、身份(
--as user/bot)、权限报错处理全沉到lark-shared,每个域 Skill 正文第一行MUST 先读 ../lark-shared/SKILL.md。这才是「不重复」的完整形态——公共规则只写一处,各技能用相对路径指针引用,而非每个技能各抄一遍认证流程。 - 命令分三档 +
schema先查:优先级Shortcut(+verb) > 已注册 API > api 裸调,能用高层动词就别拼裸接口;调任何 API 前先lark-cli schema <…>查参数,不让模型猜字段。印证「好 CLI 是业务动作接口,不是 API wrapper」。 - 每个 Skill 自带权限表:末尾列
操作 → 所需 scope;报错走结构化字段(permission_violations/console_url/hint)引导修复,按最小权限增量授权。印证 设计指南/CLI设计/CLI设计规范 的输出协议。 - 套件级渐进披露:一个「飞书全功能」总 Skill 用能力索引路由到各业务域 reference,用到哪个域才读哪份文档。
飞书自己的
lark-skill-maker(等价于 Skill Creator)把要点压成 4 条:description 决定触发(功能词 + 「当用户需要…时使用」)· 认证说明 scope · 写操作前确认 + 建议--dry-run· 编排要讲清数据传递 / 失败回滚 / 可并行步骤。
description 怎么写(决定触发率)
Section titled “description 怎么写(决定触发率)”黄金公式:[功能] + [触发场景/触发词] + [边界(该用 / 不该用)]。
- 以触发条件/触发词开头,而非「我能做什么」:列出用户会怎么说(中英文、口语变体、不点名 skill 也该命中的说法)。
- 正反例都给:明确「该用」与「不该用(用别的 Skill)」,减少误触发。
- 适度 pushy,防欠触发:当前模型倾向少触发(该用不用)。与其写「构建内部数据看板的方法」,不如补一句「只要用户提到 dashboard / 数据可视化 / 展示公司数据,即使没明说『看板』也要用本 Skill」。
- 参考实战 A 的真实 description:大量触发词 + 一句「走 API 模式,不连库不写 SQL」边界声明。
触发机制的真相:Skill 只在 AI 判断自己搞不定时才会被查。一步就能干的请求(「读一下这个 PDF」)description 写得再贴切也可能不触发——因为模型直接用基础工具就做了。所以复杂、多步、专业的场景才是 Skill 真正的战场,设计触发评测时也要用这种「够分量」的 query,别拿「读个文件」当测试。
怎么把 description 调准(触发评测集):造 ~20 条 query,正例 8–10(同一意图的不同说法,含不点名、含罕见用法)、反例 8–10。最值钱的是 near-miss 反例——和本 Skill 共享关键词、但其实该用别的工具的「擦边球」;别拿「写个斐波那契」这种明显无关的当反例,测不出东西。每条跑几次取触发率,据失败项改 description。
SKILL.md 怎么写
Section titled “SKILL.md 怎么写”正文常见骨架(问数类实战 A/C 同构,6 段):
- YAML description(触发词)
- 前置条件 / 强制流程(如「生成报告前必须先 Ask Question」)
- 能力清单(端点 / DSL 指令 / 模板)
- 调用流程(理解意图 → 抽参 → 调脚本 → 整理回答)
- 边界声明(不连库、503 如实告知不编造)
- 典型对话(4–6 个真实问句)
结构要点(操作类 Skill):When to use → Default workflow(先 doctor、读任务用 query、写任务先 dry-run、确认后 --yes、verify) → Command interface(指向 references) → Output rules(优先 JSON) → Failure handling(读 error_code/hint,环境错跑 doctor)。
长度:200–500 行内,越短越好;细节迁 references,易错执行迁 scripts。
frontmatter:name + description 必填;可加 version、metadata.requires.bins(声明依赖的 CLI/工具,让 Harness 知道前置)、cliHelp(指向 xxx --help)。飞书每个官方 Skill 都靠 requires.bins: ["lark-cli"] 声明硬依赖。
写作风格(容易写歪的一条):
- 讲清 why,胜过满屏大写 MUST。模型有 theory of mind——告诉它「为什么重要」,它能举一反三;堆
ALWAYS/NEVER反而把它框死、还稀释注意力。满屏全大写禁令是黄牌,看到就该反问:能不能改成「解释原因」? - 但确定性约束该绝对就绝对:
docx 永远用 DXA、绝不用 PERCENTAGE这种格式/工具层的硬事实没有「为什么」可讲,直接钉死;需要解释的是业务判断(为什么报告要结论前置、为什么写操作前要确认)。一句话:机器格式用禁令,人的判断讲道理。 - 用祈使句写指令;给正例(
Input → Output样例)和输出模板(ALWAYS use this template: …),范本即永久 Few-shot。
命名与受众:
- skill 名用名词/执行者式 + kebab-case:
pdf-translator、skill-reviewer,不是translate-pdf。 - 受众隔离:分清「给 AI 读」还是「给人看」。
description写准最关键——飞书lark-shared的 description 用英文以利触发匹配;正文中文也跑得很稳(飞书 26 个官方 Skill 正文均为中文),关键是触发词到位;给人看的最终交付物另讲排版。
安全(不意外原则):Skill 内容不能藏 malware/exploit,也不该做出「按描述想不到」的事——一个叫「整理目录」的 skill 不该顺手外传文件。高风险写操作必须有确认/dry-run 规则,不让模型自己拍板安全与否。
深入:五个专题(子页)
Section titled “深入:五个专题(子页)”本页是概览;下面五篇是可直接落地的深挖,案例取自飞书 larksuite/cli 与 Anthropic Skill Creator:
| 专题 | 一句话判据 |
|---|---|
| 设计指南/Skill设计/Skill切分 · 一个还是多个 | 按「能独立闭环」或「一个交付物」切;横切关注点抽共享 Skill |
| 设计指南/Skill设计/reference切分 | 看加载分布:90% 任务都加载全部就别拆,长尾才拆 |
| 设计指南/Skill设计/SKILL里如何调用CLI | 指令清单+少样本+易错点;CLI 分三层 L1>L2>L3;默认走 CLI 不放裸脚本 |
| 设计指南/Skill设计/Skill-Creator规范 | Skill Creator 规范蒸馏成可勾选规则清单(MUST/SHOULD/NEVER) |
| 设计指南/Skill设计/飞书Skill设计实践 | 26 个官方 Skill 的全景与可抄清单 |
何时拆多文件
Section titled “何时拆多文件”- 正文 > 一屏 / 含大段模板 → 拆到 reference,正文只留导航(设计指南/本体设计;细则见 设计指南/Skill设计/reference切分)
- 有确定性流程/数据操作 → 拆出 CLI 脚本(设计指南/CLI设计)
- 一个 Skill 跨多个变体/领域 → 按变体拆 references,正文只做选择:
cloud-deploy/├── SKILL.md # 工作流 + 「用哪个云看对应文件」└── references/{aws,gcp,azure}.md # 模型只读命中的那一份五种常用 Skill 模式
Section titled “五种常用 Skill 模式”| 模式 | 用途 | 对应 |
|---|---|---|
| 生成器 | 模板+风格指南,强制一致输出 | 场景指南/报告、录入 |
| 审查器 | 评分标准与检查流程分离,系统化审查 | 场景指南/审核 |
| 反转(先问后做) | 收齐上下文前不动手,扮演「面试官」 | 设计指南/AUI设计 |
| 管道(硬检查点) | 多步流程用强制检查点串起,不许跳步 | 强制流程(报告前先 Ask) |
| 工具包装 | 给模型注入某库/框架/平台的上下文与最佳路径 | 飞书 CLI、问数 CLI |
选模式 ≈ 选场景:先去 场景指南 找最近的类型,再回本页定原则。
排查:为什么不触发
Section titled “排查:为什么不触发”| 症状 | 多半原因 |
|---|---|
| 老是不触发 | description 只写「功能」没写「触发条件/词」;或场景太简单、模型直接自己干了(见上「触发真相」) |
| 该用 A 触发了 B | 两个 Skill 场景重叠,缺 near-miss 反例边界 |
| 触发了但做错 | 指令层不清晰,或正文太长被稀释,或确定性动作没下沉到 scripts/CLI |
系统性的失败归因(8 层排查 + 「是不是模型问题」决策树)见 评测与改进/失败分析与治理。
坏味道 & 评估清单
Section titled “坏味道 & 评估清单”Skill 坏味道:SKILL.md 太长 / 把 API 文档复制进来 / 没写何时用·何时不用 / 满屏全大写 MUST 却不讲为什么 / 高风险操作无确认规则 / 没 examples·troubleshooting / 让模型自己拼复杂 JSON / 让模型自己判断写操作是否安全。
好 Skill 自检:触发描述一说就中 · SKILL.md 短而流程清 · references 分文件 · 稳定动作靠 scripts/CLI · 高风险有边界 · 有 troubleshooting · 有端到端示例 · 有明确完成标准 · 有测试用例并跑过基线对比。完整清单见 参考/检查清单。
- 一句话:Skill 把一位资深专家的脑子,沉淀成了文件——换谁来问,AI 都按同一套专业方法答。
- 官方实践:Anthropic Skill Creator(创建→测试→迭代→优化触发的闭环);飞书 Lark CLI 26 个官方 Skill(共享技能抽公共规则、Shortcut/
schema命令分档、每技能带权限表 · larksuite/cli · 见skills/、skill-template/、lark-skill-maker)。 - 配套 CLI 规范 → 设计指南/CLI设计/CLI设计规范;失败治理 → 评测与改进/失败分析与治理;评测落地 → 评测与改进/评测。
- 场景模板见 场景指南/问数;工程化全流程见 场景指南/问数。