系统蒸馏成技能（Self-Built System to Reusable Skill）

一句话：把你已跑通、但只有自己懂的东西，连它的搭建过程一起，固化成一个别人能直接用的 WorkBuddy skill。 输入是你某个自研系统/工作流/本地工具 + 它是怎么一步步搭起来的，输出是一个结构合规的 SKILL.md（可再接 skillhub-publish-prep 一键发社区）。

和 self-system-to-content（系统变文章）是上下游兄弟：那哥们管"系统怎么变成能教人的文章"，本 skill 管"系统怎么变成能跑的技能"——文章是给人看的，skill 是给 AI 跑的，这是本质区别。

适用场景

• 你搭了个自研工具/流水线/方法论（本地脚本、AI 工作流、笔记系统、运营 SOP……），只在自己脑子+聊天里，没封装成可复用 skill
• 想把它变成能分享/卖/给别人用的技能，但直接写容易写成"教程"而非"真能跑的 skill"（红线见下）
• 你有一堆"只有自己懂"的资产，想批量"技能化"进分发闭环
• 特别适合：你刚亲手从零搭好一个系统（像今天搭 SkillHub 发布通道），趁热把"搭建过程"也蒸馏进去——过程本身就是最好的教学素材

不适用 / 边界

• 不是"教人从零搭系统"的通用教程生成器（那是 self-system-to-content 的完整篇干的活）
• 输入必须是"已跑通"的东西——它包装你已有的系统，不替你写系统
• 不代发无 API 的平台（小报童需手动贴）；有 API/CLI 的平台按你点名才发（接 skillhub-publish-prep）
• 它管"系统怎么变成 skill"，不管"skill 写得好不好看、文笔如何"（那是通用写作规范的事）

三条蒸馏红线（不破就不是真 skill，是写教程）

> 来源：2026-08-21 早"蒸馏 skill 可行性"拍板。这三条是判断"蒸馏出来的算不算 skill"的硬标准。

1. 去人设化：不写负债数字、关键客户名、具体账号、机器绝对路径。这些必须转成「首次配置项」变量——别人填自己的值就能跑。
2. 工具栈中立：给"最小依赖"（人人都有：bash/python/一个笔记库）和"完整版"（你用的最强栈，如本地语义检索引擎）两条路。别把你的专属工具写死成唯一解。
3. 从0可复现：必须答"零基础到能产出要多久"。用你自己的活体数据（如 5 个月），但诚实标注变量（26年经验打底/全职投入/AI全程加速）——普通兼职用户需打折，写进预期管理，别虚高。

首次配置（必做——去人设化）

把下面这些改成你自己的，否则 skill 跑起来会落到示例值：

> 不改也能跑通方法论，但别人用会落到示例值。建议首次就填，后面每次触发自动用。

工作流（6 步 + 诚实计量）

① 选靶系统（明确蒸馏对象）
   - 从你的系统里挑"已跑通、有真实产物"的，别挑还在脑子里的
   - 确认它是"系统"不是"一次性任务"：有稳定输入输出、可重复流程、活产物
   - 同时抓"搭建过程"：它怎么从 0 长出来的（这份历程是去人设后最好的教学素材）

② 实查（不凭记忆——复用 self-system-to-content 的实查四步）
   - 读源码/配置：找到系统真实文件，读实际实现，不靠印象
   - 跑真实命令：执行系统相关命令，抓真实输出当证据（贴进 skill 的避坑清单）
   - 对真实数字：用跑出来的数字，不写"覆盖92%"之类记忆值
   - 自己纠错：发现错标（数量/覆盖率不符）当场纠正，并在 skill 里记一笔"纠错记录"
   产出：带实据的「系统实查笔记」

③ 抽骨架（把"只有你懂"翻译成"任何人能跑"）
   - 找系统的"不变核心"：换个人、换环境也成立的那部分方法论
   - 剥离"你专属"：账号/客户名/负债数字/机器路径 → 转成「首次配置项」
   - 列依赖：最小依赖（人人有）vs 完整版（你用的最强栈）

④ 去人设化（红线1）+ 工具栈中立（红线2）
   - 首次配置表：把专属值变变量
   - 给两条路：最小依赖 / 完整版（同一动作两种成本）

⑤ 写 SKILL.md（从0可复现 红线3）
   - frontmatter 必填（skillhub 发布硬门槛）：
       name / slug(kebab-case) / displayName(驼峰) / version(须>平台已有) / description / 平台 / license
   - 正文骨架：适用场景 / 边界 / 首次配置 / 工作流 / 诚实计量红线 / 避坑清单 / 依赖 / 最小可跑
   - 必须答"零基础到能产出要多久"——用活体数据但诚实标变量

⑥ 备料+发布（接 skillhub-publish-prep）
   - `skillhub publish --dry-run <目录>` 预检（缺 slug/displayName/version 会当场报错）
   - `skillhub publish <目录>` 真发（CLI 登录态 or --token）
   - 发布后 SkillHub 有强制自动安全审核，过审才公开可见

A→B 两段走路线（推荐 A）

> 来源：2026-08-21 早可行性拍板。

• A 路线（默认·推荐）：先出个人版 skill（自己用+沉淀）→ 跑通验证半年 → 再蒸馏通用版（去人设更彻底、给别人/变现）。好处：有活体验证，不空中楼阁。
• B 路线（直接通用版）：一步到位去人设。风险：缺活体验证，容易写成"我觉得别人会需要"的想象品，不可靠。
• C 路线（只出文档不封装）：没自动化埋点，后续难迭代。不推荐。

本 skill 自身就是 A 路线的产物：它的种子来自老刘知识系统的真实搭建历程（个人版），通过「首次配置项」做了去人设（向通用版迈）。

诚实计量红线（别删——这是 skill 不虚高的根）

1. 数字必须来自实跑，不来自记忆：覆盖率/利用率/数量有缺口就明说，不写"全自动""全覆盖"
2. 去人设化必须真做：账号/客户/机器路径必须变量化，不能正文里还藏着你的具体值
3. 工具栈必须给两条路：不能只写你的最强栈当唯一解，最小依赖路必须能独立跑通
4. 从0可复现必须答得出：明说"零基础到产出要多久"+ 诚实标变量（经验/投入/AI加速）
5. 第一人称只用于你亲身经历：他人系统/案例只能署名转述，拿不准不用"我"

避坑清单（来自实战——必读）

> 维护原则：发现新坑立刻加，别憋到下次出问题。

• 坑1：把"精选取料菜单"当"总量" → 统计卡片/笔记数时区分"精选子集"和"全量台账"，别误读数量（如 49 张精选 ≠ 387 张全量）。蒸馏时如果系统内部有"精选 vs 全量"结构，skill 里要讲清，否则别人照做会懵。
• 坑2：工具警告的"覆盖率"可能误导 → vsearch 弹"XX% need embeddings"是用另一口径算的，可能与 embed_loop（DISTINCT hash）的"满额"结论打架。❌ 别信单条警告字面；✅ 交叉验证。2026-08-20 曾因信警告误判"覆盖崩"，实查后 100.4% 已全量。蒸馏带"覆盖率"声明的系统时，必须实查，不抄工具警告。
• 坑3：AI 自己的结论也要实查 → 本 skill 的"实查四步"不仅用于写 skill，AI 在下任何数字/覆盖率/状态结论前也必须对自己跑实查：单源数字（含自己旧输出、工具警告字面、对话摘要里的旧结论）不得直接当真理。对应长期记忆"AI 自查铁律"。
• 坑4：CLI 是 bash 脚本，Python 子进程直调找不到命令 → 正文含反引号/双引号时，在 Bash 里用 $(cat 临时文件) 把全文喂给参数，文本只在 cat 输出里、不触发 shell 二次解析；或先用 Python 把正文写临时文件再读。
• 坑5：建专库接口 → POST /resource/knowledge/create {name,description} 建库，返回 topic_id；首次存档前先确认库存在。
• 坑6：skillhub 发布 frontmatter 三件套缺一不可 → slug(kebab-case) / displayName(驼峰，不是你已有的 display_name) / version(每次真发必须比平台已有版本高，否则报"已存在"拦截)。dry-run 会逐个报缺，先跑 dry-run 再发。
• 坑7：发布通道用官方 CLI，别裸 REST → 2026-08-13 曾用裸 curl 打 api.skillhub.cn REST 写接口全 401，误判"PAT 推不动"；实际正确通道是 skillhub CLI 的 auth+publish（2026-08-21 实测推翻旧结论）。发布走 skillhub publish --token skh_xxx 或先 skillhub login --key 建登录态后直接 publish。

依赖

• 能读你系统的源码/配置/运行命令（本地文件系统或同步源）
• 至少 1 个笔记库（存档/备份）
• 可选：本地 CLI（如 skillhub / zsxq-cli）用于自动发平台
• 推荐配套：self-system-to-content（系统变文章）、skillhub-publish-prep（一键发社区）

最小可跑

只要你说得出"把 XX 蒸馏成 skill"且 XX 是你已跑通的东西，①②③④⑤ 就能产出结构合规的 SKILL.md；⑥ 在你建好 CLI 登录态或手传 token 后自动走。

实战范例：老刘知识系统 → 可蒸馏素材（本 skill 的种子）

> 这一段是"系统蒸馏成技能"的活标本——它展示从老刘真实系统里能抽出什么。不是让你照搬，是让你看"抽骨架"长什么样。

源系统（已跑通、有真实产物）： 老刘 + AI 用"按意思检索"从知识库协作产出内容的系统
- 四层架构：输入层(8库+vault 5400+篇) → 卡片层(飞轮台账≈387张) → 检索层(5取料口，最强=qmd vsearch 全库捞) → 产出层(口播/小报童/公众号/某书/星球/直播，走五连派生)
- 8 库分区（topic_id 已固化，去人设后变首次配置项）：4输入(复盘记录40DBk2vn/扯蛋知识库yYv67gaY/短视频话题pn514jMn/痛点库oJOz9La0)+2深加工(案例库MJa3gyaY/金句库rYM6KLW0)+2成品(口播库JOaa7GNY/方法论库EJl7k1j0)
- 核心引擎命令（真实可跑）：cd "工作区" && bash qmd.sh vsearch "你想找的意思" --limit 5
- 搭建过程：从 5000+ 篇散笔记 → 分区架构 → 自动化四轨 → 知识卡片飞轮 → 语义检索打通，5个月爆发式积累（诚实标注：26年经验+全职+AI加速）

抽骨架后是这样（去人设 + 工具栈中立 + 从0可复现）：
- 不变核心："分散笔记→分区沉淀→卡片化→语义捞料→派生产出"的方法论，换个人也成立
- 去人设：8 库 topic_id → 首次配置项 NOTE_LIB_ID；机器路径 → TOOL_SPECS 变量
- 工具栈中立：最小依赖=bash+任意笔记库；完整版=本地 qmd 语义引擎（慢但强，无显卡首条等1~2分钟，timeout≥280s）
- 从0可复现："零基础到能产出内容约需数月持续积累，本系统实证 5 个月；普通兼职用户需打折"——诚实不虚高

> 这就是 card-first-drafting / knowledge-card-flywheel 等已发布 skill 的来历：它们本身就是这套蒸馏法的产物。

反馈与共建

用着卡壳、有改进点子 → 反馈作者，跟进更新。发现新坑立刻补进避坑清单。