使用方法
- 复制安装命令,在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/ziyueyijun/skills --skill skill-builder开始前需了解
- 安装不包含模型订阅、API 额度或访问文件的权限。
- 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。
Skill Builder
Soul: 说明书不是论文。删掉任何不会改变执行者行为的话。
造 skill 会写文件——有副作用、时机由人定,所以本 skill 手动触发。模型看不到自动触发用的 description,因此靠前文那句人读的摘要被找到。
契约
输入一段工作流 / 操作步骤 / 踩坑经验,或一份待改的 SKILL.md;输出一个过验收的 SKILL.md。不执行该流程,不写普通文档,不给一次性任务造 skill。
默认值,只在明显不符时才问:自动触发(有副作用才手动)· compact 单文件 · 宿主 skills 目录 · 原地覆盖更新。挨个问用户是审问,不是服务。
五阶段
每阶段可缩成一行,不可跳过。缩的是文字,不是活。只有 Verify 是强制门禁。
1 · Decide 判定
先过 gate,不过就停,并说明该用什么替代:
- 一次性任务 → prompt
- 纯知识 → 文档
- 确定性、有副作用的流水线 → 脚本 / 工具
- 只有"反复发生 + 上下文不可猜 + 流程已稳定"才配一个 skill
已有 skill 时不另造:原地重做。先问真实使用暴露了什么——漏触发、误触发、内容过时、描述漂移。留好部分,改坏部分。
钉死一句话职责:谁、何时、交付什么。出现"以及 / 顺便"连接两个不相干结果就拆成两个 skill。
2 · Draft 起草
- description 三元组 = 用户原话(中/英/混用)+ 场景与文件类型 + 排除项。例:"用户提到 Word / .docx / 修订痕迹时用;不用于 PDF 或表格。"
- frontmatter 硬契约:
name只用小写字母、数字、单连字符,且与目录同名;description≤ 1024 字符。挂了是静默失败,写完必查。 - 从最小模板起手,别从空白页自由发挥:
---
name: xxx
description: 用户措辞 + 场景/文件类型 + 排除项
---
# Xxx
> Soul: 仅当能裁决规则冲突时写,否则删掉这行
## 契约
输入 / 输出 / 不做什么
## 流程
1. 确定性且脆弱的步骤:must / never,单一路径
2. 需要判断的步骤:原则 + 1~2 个例子,留余地
## Checklist
打开 xxx;看 2~3 处;失败信号;不过则回到第 N 步3 · Distill 提纯
三件事,缺一不可:
- 减法仪式:逐段问"删掉它,执行者会做错吗?"不会就删。隐喻不指导行为就删。只写会咬人的地方——什么会失败、为什么、怎么修。
- 冻结确定性:一个正确答案、每次都一样的动作 → 塞进
scripts/,正文只留何时调、怎么调。脚本必须大声失败。单文件就内联最小代码块。 - 校准约束:
| 步骤性质 | 约束形式 |
|---|---|
| 确定性且脆弱 | must / never,只给一条路 |
| 需要判断 | 原则 + 一两个例子,留余地 |
| 红线 | 绝对禁止,无例外 |
密度:默认 compact,100~150 行是天花板不是地板,短且完整合法。rich(主文件 + references/ + examples/ + scripts/)只给复杂、长生命周期的领域。每加一个文件先答"执行者何时会记得去读它",答不出就不加。
坑的出处:只写亲眼见过或能从用户需求里直接引用的失败。greenfield 不发明坑。新 skill 没有可引用的坑时,在 Checklist 写"待观察的失败信号",等真发生再回填。
4 · Verify 验收(唯一强制门禁)
写 + 改都要过完这四关才能交付:
- 触发测试:写 3 句"该触发"、2 句"不该触发",全用用户口吻,逐句比对 description。手动 skill 模型看不到 description——改给人看命令名 + 一行摘要,问人能不能凭它判断何时用。
- 干跑:拿现在就能完成的最小样本,把整个流程走一遍。
- 盲跑:把 SKILL.md 丢给全新 session 或无上下文的 subagent,给真实任务、零解释。数三件事——问了几个问题、返工几次、Checklist 过没过。不过就回灌到对应阶段重跑,最多两轮;两轮还挂就停,报告卡点,不无限重跑。
- 降级:执行环境没有 subagent / 新 session 可用时,改做"清空白盒"——只凭文本逐步推演,把每一步的疑问记为执行者会问的问题。不许假装做过真盲跑,如实标注是降级。
- 反向扫:倒着读全文,删掉每一句"删了也不改变行为"的话。
5 · Ship 交付
存到 Decide 定的位置;更新则原地覆盖。确认 frontmatter 能被解析,请用户在新 session 验一次加载。给 1~2 个第一批任务。
Self-check
打开本目录下的 SKILL.md,查三处:description 的触发 / 排除是否对得上五句测试;坑是否都有出处、没有编造;正文是否只剩五阶段、没有长出第六个元阶段。
失败信号:造出的 skill 超过 150 行还在讲道理;Soul 出现在没有规则冲突的地方;盲跑被无限重跑;在既有 skill 旁造了竞品。
不过则回到对应阶段;两轮仍不过,停并报告卡点。