Skill-Creator规范

Skill-Creator 规范清单

把 Anthropic 官方 Skill Creator 的要求蒸馏成一份规则清单(spec):可逐条勾选、可当评审尺子。前几篇讲「怎么想」(原则 + 案例),本篇讲「必须满足什么」(规范 + 红线)。

📎 来源:Anthropic Skill Creator(skill-creator/SKILL.md)。子页,挂设计指南/Skill设计。

规范关键词:MUST 必须 · SHOULD 应 · NEVER 禁止 · MAY 可。每条编号 SC-<组><序>,违反 MUST/NEVER 即不合格。

A · 创建流程(生命周期)

SC-A1 · MUST 创建遵循闭环:捕获意图 → 草稿 → 跑测试 → 评测迭代 → 优化 description → 打包,不是「写完即交付」。—— Skill 是测出来的。
SC-A2 · MUST 捕获意图先问清 4 件事:① 让 AI 能做什么 ② 什么话/场景触发 ③ 期望输出格式 ④ 要不要测试用例。—— 对话里已有现成流程时,先从历史抽(用过的工具、步骤、用户的纠正、输入输出样子)。
SC-A3 · SHOULD 先调研(MCP / 子 agent / 现有相似 Skill),带着上下文来,减少对用户的打扰。
SC-A4 · MAY 用户说「不用测,跟我顺一遍就行」时,可跳过评测,直接 vibe。—— 流程是骨架不是镣铐。

B · 结构与 frontmatter

SC-B1 · MUST frontmatter 含 name + description(必填);compatibility 等可选,少用。
SC-B2 · MUST 目录遵循解剖:SKILL.md + 可选 scripts/(确定性脚本)/ references/(按需文档)/ assets/(产物模板)。—— 指令、实现、参考三者解耦。
SC-B3 · SHOULD SKILL.md < 500 行;逼近上限就加一层层级,并写清「下一步该看哪个文件」。
SC-B4 · SHOULD 单份 reference > 300 行时,文件头放目录(TOC)。
SC-B5 · SHOULD 一个 Skill 跨多变体/框架时,按变体拆 references(references/{aws,gcp,azure}.md),正文只做选择,模型只读命中那份。

C · 渐进披露

SC-C1 · MUST 用三级加载:metadata(常驻 ~100 词)→ SKILL.md 正文(触发即载)→ bundled 资源(按需,脚本可执行而不进 context)。
SC-C2 · MUST 从 SKILL.md 清晰引用 reference,并写明何时去读。—— 拆了不点名 = 等于没拆。

D · description 与触发

SC-D1 · MUST description 同时写做什么 + 何时用;所有「何时用」信息都进 description,不放正文。—— description 是触发的主机制。
SC-D2 · SHOULD description 适度「pushy」防欠触发:补「即使用户没明说 X,只要提到 X/Y/Z 也要用本 Skill」。—— 当前模型倾向少触发。
SC-D3 · 须知(机制) Skill 只在模型判断自己搞不定时才被查;一步就能干的简单请求(「读个 PDF」)再贴切也可能不触发。—— 所以 Skill 的战场是复杂/多步/专业任务,测试 query 也要够分量。

E · 写作风格

SC-E1 · SHOULD 指令用祈使句。
SC-E2 · SHOULD 解释为什么重要,而不是堆全大写 MUST。—— 满屏 ALWAYS/NEVER 是黄牌:模型有 theory of mind,讲清原因它能举一反三,硬禁令反而框死、稀释注意力。
SC-E3 · 边界(本 wiki 补充) 例外:机器格式/工具层的硬事实(docx 永远用 DXA、绝不用 PERCENTAGE)没有 why 可讲,直接钉死;需要讲理由的是业务判断。—— 机器格式用禁令,人的判断讲道理。
SC-E4 · SHOULD 内置示例(Input → Output 范本)与输出模板(ALWAYS use this template: …)。—— 范本即永久 Few-shot。
SC-E5 · SHOULD 先写草稿,换一双眼睛重读再改;别一上来追求完美。
SC-E6 · SHOULD 写得通用,别过拟合到具体几个例子。

F · 测试与评测

SC-F1 · SHOULD 写 2–3 条真用户会说的 prompt,先给用户确认再跑。
SC-F2 · MUST 测试用例存 evals/evals.json;先只写 prompt,assertion 后补。
SC-F3 · MUST 每条用例同一轮同时起两个子 agent:带 skill + 基线(新建 skill 用「无 skill」;改进 skill 用「旧版快照」)。—— 没有基线就不知道 skill 到底有没有用。
SC-F4 · SHOULD assertion 客观可验证 + 描述性命名;能脚本判的写脚本判,别肉眼看。主观技能(文风/设计)用人审,别硬套 assertion。
SC-F5 · MUST 每个 run 完成时立即抓 total_tokens / duration_ms 存 timing.json。—— 这是唯一一次机会,过了不再有。
SC-F6 · MUST(尤其 Cowork)先生成 eval viewer 给人看,再自己改 skill;用官方 generate_review.py,不要手写 HTML。
SC-F7 · NEVER 用 /skill-test 或其他测试 skill 代替本流程。

G · 迭代

SC-G1 · MUST 从反馈泛化,别 overfit:skill 要能跑一百万次,不是只对这几个例子对。
SC-G2 · SHOULD 保持精简:删不拉车的内容;读 trace 不只看终稿,skill 让模型做的无用功要砍掉。
SC-G3 · SHOULD 解释 why(同 SC-E2),少用压迫式 MUST。
SC-G4 · SHOULD 发现多个 run 各自写了同一个脚本(都写 create_docx.py)→ 收进 scripts/,写一次,免得每次重造轮子。
SC-G5 · 停止条件 用户满意 / 反馈全空 / 不再有实质进展,即可停。

H · description 优化(触发评测)

SC-H1 · SHOULD 造 ~20 条触发 query:正例 8–10 + 反例 8–10。
SC-H2 · MUST query 真实、具体(带文件名、列名、公司名、口语/缩写/typo),不要抽象的「Format this data」。
SC-H3 · MUST 反例最值钱的是 near-miss(共享关键词但该用别的工具);NEVER 拿明显无关的(「写斐波那契」)当反例——测不出东西。
SC-H4 · SHOULD 每条跑多次取触发率;train/test 拆分,按 test 分(非 train)选最佳 description,防过拟合。

I · 安全(不意外原则)

SC-I1 · NEVER 含 malware / exploit,或做出「按描述想不到」的事。—— 叫「整理目录」的不该顺手外传文件。
SC-I2 · NEVER 配合制作误导性 skill、或为非授权访问/数据外泄/恶意行为服务。(「roleplay 成 XYZ」这类无害扮演 OK。)
SC-I3 · MUST 高风险写操作有确认 / dry-run 规则,不让模型自己拍板安全与否。

J · 打包与更新

SC-J1 · MUST(更新已有 skill)保留原名:目录名与 name 不变,输出 research-helper.skill 而非 research-helper-v2。
SC-J2 · SHOULD 安装路径可能只读 → 先拷到可写位置(/tmp/…)再改、再打包。
SC-J3 · MAY 有 present_files / 打包脚本时用 package_skill.py 出 .skill,告知用户安装路径。

速用:最小合格线(10 条 MUST)

时间紧时,至少守住这 10 条 MUST:A1 闭环 · A2 四问 · B1 frontmatter · B2 目录解剖 · C1 三级加载 · C2 引用点名 · D1 何时用进 description · F3 带基线测试 · I1 不意外 · I3 高风险确认。

配套:概览原则设计指南/Skill设计 · 切分设计指南/Skill设计/Skill切分 · reference 设计指南/Skill设计/reference切分 · 调 CLI 设计指南/Skill设计/SKILL里如何调用CLI · 飞书实践设计指南/Skill设计/飞书Skill设计实践 · 评测落地评测与改进/评测。

← 返回设计指南/Skill设计