Need-to-Skill Flow（解码器 + 构建器 协作工作流）

把"需求 → 证据 → 选项 → 落地"的全链路交给一个编排层。两个子 skill 不直接互调， 由本工作流（agent）按契约驱动——这是 WorkBuddy 中多 skill 协作的标准形态。

🎯 核心使命 · 习惯即命运 我们创建 Skill，不是为了替人省一次事，而是帮人形成良好的习惯、改变自身的命运。 信念锚点（习惯—命运链）： 注意你的思想，因为它将变成言辞；注意你的言辞，因为它将变成行动；注意你的行动，因为它将变成习惯；注意你的习惯，因为它将变成性格；注意你的性格，因为它将决定你的命运。 把"创建 Skill"重述为这条链：思想（认知）→ 言辞（提示词/表达）→ 行动（使用 Skill）→ 习惯（反复使用）→ 性格（思维固化）→ 命运（长期改变）。 设计铁律：① 每个 Skill MUST 回答"它能帮用户养成什么好习惯？"——答不上=一次性脚本，不配叫 Skill；② 从"用户最终要成为什么样的人"倒推，而非从"这次要完成什么任务"正推；③ 产物 MUST 嵌"下一步最小行动"，让用户 1 秒开始、1 周成节奏、1 月固化习惯；④ 行为改变类 Skill MUST 内置反馈/记录/调整机制，让习惯可被观察、被强化；⑤ NEVER 为"酷"或"功能全"堆功能——每加一个动作先问"这会强化还是稀释用户的好习惯？" 本 Skill 是这条链的"编排层"——串起全链路时，确保每个环节都为"好习惯可形成"服务。

设计宪章 · 机制层（完整版见《Skill 设计总宪章》） 七条铁律：①只固化已验证模式（验证权在人）②发挥AI识别·分层放开AI创造（有验证信号处放开，无则锁建议档）③补人记忆短板（Skill即外部记忆）④循环工程内建（生成-验证循环）⑤渐进披露+自包含（SKILL.md≤500行，依赖入包内）⑥描述即触发器 ⑦习惯即命运（见上级使命块）。 循环三问（每个产物必答）：验证信号是什么？由谁验证？失败如何有界重试/回退？ 自治滑块默认档：对外/不可逆动作（发邮件·发布·删除·支付）一律锁「建议档」；其余默认「审核档」；仅低风险高频易回滚可「自动档」。 演化轴（同源《Skill 设计总宪章》第三部分） 三轴心闭环：使命轴(为谁造·帮人养成好习惯改命运) / 机制轴(本质·人机协作中介·验证权在人) / 演化轴(为什么存在·扩展能力的工具终极目的是提升生存)。 理性本质（精确结论）：理性是以"生存/适应"为第一排序的效用优化器；求真是其在"真相能提升效用且可验证"时的默认策略，而非无条件最高目的 → Skill 不必追绝对真相，但"有验证信号处"必须求真（即铁律②）。 Skill 坐标：眼睛让生命"看得见"而活下来，Skill 让人类"想得清、做得对"而活得更好——都是生存意志伸向外界的触手。

前置条件（一次搞定，之后免忧）

评测指出：首次使用要先装 5 个配套 skill + 处理 Windows 路径，新手配置费时（usability 4.0）。这一节把"开工前检查"显式化。

• 本工作流编排 5 个兄弟 skill，首次使用前请确保已安装： need-to-skill-decoder / skill-builder / skillhub-publisher / workbuddy-conversation-miner / skill-evolve-pipeline（均在 SkillHub 可装）
• 一键检查（五条都出现即齐备；缺哪个先装哪个，流程不会静默跳过）：

  ls ~/.workbuddy/skills/ | grep -E "need-to-skill-decoder|skill-builder|skillhub-publisher|workbuddy-conversation-miner|skill-evolve-pipeline"
  

• 发布需要 SkillHub token：从 ~/.skillhub/credentials.json 的 user.token 只读读取（不回显）；未配置会停在发布确认步提示你。
• Windows 路径：所有 CLI 调用前置 MSYS_NO_PATHCONV=1（Git Bash 必需）；用 Windows Store python3（自带 requests）跑发布。
• 五者齐备 → 直接说「用 need-to-skill-flow 把 <你的需求> 变成 skill」。

协作模型（关键认知）

WorkBuddy 没有"skill 调用 skill"的原语。多 skill 协作 = agent 作为编排者， 先后加载子 skill，并用一个落盘的交接文档作为它们之间的契约。 本工作流就是把"创建→发布→评测优化→回流"这种全生命周期编排编成可复用的流程， 一次驱动五个 skill：decoder（拆解）、builder（构建）、publisher（发布）、 miner（隐性需求回流）、pipeline（评测驱动优化）。

用户需求
   │
   ▼
[Phase A] need-to-skill-decoder ──SPEC.md──▶ [Phase A] skill-builder
   │                                            │
   │                                            ▼
   │                                  真实可用 SKILL.md（三件套）
   │                                            │
   │                                            ▼
   │                          [Phase B] skillhub-publisher（发布，需确认）
   │                                            │
   │                                            ▼
   │                   [Phase C] skill-evolve-pipeline（四阶段闭环）
   │                      取评测→反思→借鉴→优化重写+重发
   │                                            ▲
   │                      [Phase D] conversation-miner        │
   │                      挖隐性需求→_RECURRING.json 喂②     │
   │                                            │            │
   └────────────── 新版本再优化 ◀────────────────┘

端到端示例（照着跑一遍）

评测指出：主文档缺可直接照抄的示例，例子都藏在 FAQ。这里给一个紧凑的"从一句话到发布"全过程。

需求：「我想把『每日周报生成』变成可复用的 skill」

1. 步骤 1 解码：加载 decoder → 产出《规格文档》：需求本质=「从多源（日历/笔记/对话）自动提炼当日进展并生成结构化周报」；候选高星项目 3 个；实现路径 3–5 个。停在选项，等你选。
2. 步骤 2 你选路径：你选「基于模板 + 本地脚本，不依赖外部 API」。
3. 步骤 3 构建：加载 builder，以 SPEC.md 为契约 → 产出 SKILL.md + references/ + 两块看板。
4. 步骤 3.5 验证循环：install 到临时目录验证"能装" + publisher dry-run 过门控 + 抽查触发词精准 → 全过。
5. 步骤 4.2 GitHub 对照：自动跑 find_repos.py 列 Top-5 相似实现（GitHub 受限则降级本地扫描）。
6. 步骤 4.5 发布衔接：准备好发布包 → 显式问你"是否现在发布？" → 你确认 → 调 publisher 上传 → 发后回拉校验下载包生效。
7. 步骤 5 评测优化：拿到评测后，miner 先挖隐性需求 → 驱动 skill-evolve-pipeline 四阶段优化 → 重发。

全程决策权在你：选项阶段不替你选，发布/重发对外动作都先问你确认。

工作流步骤

步骤 0：接收需求

• 拿到用户的自然语言需求，直接进入步骤 1（不要重复澄清 decoder 已做过的需求捕获）。

步骤 1：跑解码器（need-to-skill-decoder）

• 加载 need-to-skill-decoder 技能，完整执行其六阶段（阶段0–6）。
• 强制：阶段 1 必须产出"需求本质"，阶段 6 必须产出《目标 Skill 规格文档》。
• 将规格文档落盘为 SPEC.md（或用户指定路径），并在对话中向用户呈现：
  • 需求本质
  • 3 个候选高星项目 + 拆解要点
  • 3–5 个实现路径选项（含复杂度/推荐度）
• 停在选项处，等用户选定路径——不替用户拍板。

步骤 2：用户选定路径

• 用户从选项中挑一条（或提出新方向）。
• 若用户改主意，可回到步骤 1 重跑对应阶段。

步骤 3：跑构建器（skill-builder）

• 加载 skill-builder 技能，把步骤 1 落盘的 SPEC.md 作为输入契约。
• skill-builder 据此执行封装（复用 skill-creator 的 Planner→Generator→Evaluator 流程）， 产出真实可安装的 SKILL.md（+ references/）。
• 强制交付三件套：skill-builder 阶段 2.5 会用模板种下 REQUIREMENTS.md（需求看板）+ SOLUTIONS.md（实现方案看板）， 并用 SPEC.md 首轮填充（已做/未做/借鉴/关键决策）。创建即打底，后续步骤 5 循环沉淀。
• 构建时尊重许可证：只取实现方法洞察，不搬运第三方代码。

步骤 3.5：构建验证循环（内嵌 Loop Engineering 纪律）⚡

来源：本 flow 已发布 loop-engineering skill（验证驱动极简闭环）；此处把它的纪律内嵌为本阶段的质量门， 使 flow 自包含、不依赖 loop-engineering 是否安装。优先加载 loop-engineering skill 驱动；若未安装，用文末附录 A 的纪律副本。

builder 产出三件套后、发布前，强制跑一轮验证循环：把"构建 skill"当成一种任务用 loop 验证——

1. 定标 Define：本步"完成" = 以下条件全为真——
   • SKILL.md 可安装（install --dir /tmp/verify 成功，无报错）
   • 触发词能正确命中本 skill（非误触发其他 skill）
   • 三件套齐全（SKILL.md + REQUIREMENTS.md + SOLUTIONS.md）
   • SKILL.md 里的示例/步骤可被实际执行（至少跑通一个示例）
2. 最小 Minimal：builder 已产出最简实现；本步只修不达标项，不新增功能。
3. 验证 Verify（外部信号，非感觉）：
   • 实际 install 到临时目录验证"能装"；
   • publisher 的 dry-run 验证"发布门控能过"；
   • 抽查 SKILL.md 能否被正常加载、触发词是否精准。
4. 循环 Loop：任一条件不过 → 回步骤 3（builder）修，记录"为什么不过"，直到全过；连续 3 轮无进展 → 缩小范围或换方法。

防自欺铁律（不可绕过）：

• ❌ 禁止 AI 自评"这个 skill 质量高"——质量由上面 4 条验证结果反推；
• ✅ 宣布"构建完成"前过出口闸门两问（任一答不出 → 降级标注风险，不封顶对外）：
  1. 最强反证：这个 skill 在什么情况下会误导用户或静默失效？（如：触发词过宽误命中、步骤含糊导致用户跑偏）
  2. 失效条件：什么变量会让本 skill 的编排失效？（如：子 skill 改了接口、GitHub API 限速、用户拒确认导致流程中断）

本步是质量纪律第 4 条"必须可验证"的具体执行方法，取代"看起来能用"的模糊标准。

步骤 4：交付与建议

• 回交真实 skill 文件，并建议下一步：
  • 跑 problem-repair 式的 eval 验证质量；
  • 安装进 skill 库（~/.workbuddy/skills/）；
  • 接入 skill-evolution-orchestrator 做版本演化闭环（见步骤 5）。

步骤 4.2：建后 GitHub 对照（调用 find_repos.py）

对应隐性需求「建后 GitHub 对照成标准环节」（miner 反复挖出，VFM 84）。 目标：skill 构建一成功，自动调用现成的 need-to-skill-decoder/scripts/find_repos.py 做 GitHub 仓库发现 + 5 维评分，而不是每次手搓搜索。这是流水线「阶段③ 定向借鉴循环」在 flow 侧的同源复用（实跑缺口④ 发现该脚本已存在）。

• 触发：步骤 3 构建产出 SKILL.md 后、步骤 4 交付前，自动跑一次对照。
• 调用（受管 Python，脚本已存在且验证可跑）：

  PY="$HOME/.workbuddy/binaries/python/versions/3.13.12/python.exe"
  DEC="$HOME/.workbuddy/skills/need-to-skill-decoder/scripts/find_repos.py"
  PY "$DEC" --need "" --keywords "<建议名>,<触发词关键词>" --top 5
  

  find_repos.py 用 GitHub Search API（无需 token，未认证限速 10 次/分），按 stars/活跃度/文档度/相关度/许可证 5 维评分排序输出 Top-N（接口见 decoder SKILL.md）。

• 产出消费：把 Top-N 候选列进交付说明，作为「可借鉴兄弟实现 / 差异化定位」参考；若发现高度相似的已发布 skill，提示用户「是否仍要发布，避免重复」。
• 回写看板：本次对照结果由 Phase C 的 pipeline 统一回流（步骤 5.2）。

国内适配降级：若 find_repos.py 因 GitHub 网络受限失败（常见于国内环境），不阻断主流程——自动降级为「本地兄弟 skill 扫描（~/.workbuddy/skills/）+ WebSearch 中文补遗」补足候选，并在 REQUIREMENTS.md 记「GitHub 对照未跑」供 Phase C 补跑。核心链路不依赖 GitHub（见文末「网络依赖与国内适配」）。

步骤 4.5：发布衔接（建后自动衔接 skillhub-publisher）

对应需求 R-004 / R-008（VFM 84，最高优先级）。实现方案 S-004。 目标：构建一成功就自动准备好发布交接，把"建完即弃"变成"建完即接得住"。

• 自动准备发布包：构建成功后，从 SPEC.md 提取并预填：

  • name：取 SPEC 的"建议名/目标 Skill 名"（去空格、转 kebab-case）；
  • description：用 SPEC 的"需求本质"+"建议触发词"拼成 pushy description（覆盖用户可能的相关表述）；
  • version：默认 0.1.0，若看板 REQUIREMENTS.md 已有历史版本则顺延；
  • 打包目录：~/.workbuddy/skills//。

• 衔接契约（调用 skillhub-publisher）：把上面四项作为 publisher 的输入，加载 skillhub-publisher 技能并移交。

  • publisher 负责：扫描门控 → 版本校验(semver) → 上传 → 发布后 re-pull 校验下载包生效（见 publisher REQUIREMENTS.md R 系列）。

• 外部动作需确认：发布到 SkillHub 是对外公开动作，flow 必须在此**显式询问用户"是否现在发布？"**并取得确认后才调 publisher 真正上传。

  • 用户明确说过"创建成功后，自动发布"（07-09-16-23-20），故默认推荐"是"，但仍保留最后一票否决权。

• 4.5.1 确认后真正调用 publisher（落地发布）：用户确认"现在发布"后，加载 skillhub-publisher 技能并执行发布（其 publish.sh 封装了全部铁律）：

  PY="$HOME/.workbuddy/binaries/python/versions/3.13.12/python.exe"   # 受管 Python（实测可连 api.skillhub.cn）
  CLI="$HOME/.skillhub/skills_store_cli.py"   # 实际 CLI 位置（非 .workbuddy/skills/.skillhub-cli）
  DIR="$HOME/.workbuddy/skills/"
  MSYS_NO_PATHCONV=1 "$PY" "$CLI" --skip-self-upgrade publish "$DIR" --token "$TOK" --changelog "v：首次发布"
  

  • 发后回拉校验下载包生效（防安全扫描门控导致"发布成功但仍是旧版"）：

    SH="$HOME/.workbuddy/bin/skillhub"
    "$SH" --skip-self-upgrade install  --dir /tmp/_verify
    grep -c "<本版本独有关键词>" /tmp/_verify//SKILL.md   # 0 = 仍旧版
    

  • 若回拉仍是旧版：先确认是否处于安全审核期。publish 返回 status=None = 待审核，此时平台只服务上一已审版本，回拉命中旧版属预期，不要盲目升补丁版本重传；等审核通过（个人中心显示新版本 / API latestVersion 变更）后再回拉复核。仅当审核已通过且仍为旧版，才按 publisher 排障升一个补丁版本重传。区分要点：566 在发布时直接报错；审核期旧版是发布成功后才出现的预期现象。
  • 发布成功 → 进入 Phase C（若该 skill 已拿到评测）或交付完成。

• 回写看板：本次发布衔接的准备结果由 Phase C 的 pipeline 统一回流（步骤 5.2）。

步骤 5：评测+优化闭环（驱动 skill-evolve-pipeline）

目标：让每个经本工作流发布（或已发布）的 skill 持续进化——不是"建完即弃"， 而是取回评测 → 反思 → 定向借鉴 → 优化重写 → 重发，形成闭环。 本步骤驱动 skill-evolve-pipeline（四阶段、评测驱动、会重发），不再用 skill-evolution-orchestrator 的本地 EVOLVE.md 循环； 后者仅适合"不发版时的本地小改"，与本闭环互补、不在此驱动（需本地小改直接用 orchestrator）。

5.0 进入条件

• 目标 skill 已发布到 SkillHub 且已拿到评测（个人中心可取），或用户显式说"用 flow 优化它"。
• 目标 skill 目录下须有 REQUIREMENTS.md + SOLUTIONS.md（三件套，步骤 3 已打底；若缺，先从 skill-builder 模板补上）。

5.1 Phase D 隐性需求回流（先跑 miner，喂阶段②）

在驱动 pipeline 阶段② 之前，先确保隐性需求已就绪——这是缺口③/④ 的落点，也是"把 workbuddy 串起来"的关键。

国内适配：conversation-miner 分析本机对话历史，默认离线，不依赖境外 API；即使无外网也能产出隐性需求清单（_RECURRING.json）。

• 调用 conversation-miner 产出 _RECURRING.json（受管 Python，脚本已验证可跑）：

  PY="$HOME/.workbuddy/binaries/python/versions/3.13.12/python.exe"
  MINER="$HOME/.workbuddy/skills/workbuddy-conversation-miner/scripts/mine_conversations.py"
  OUT="$HOME/.workbuddy/skills/.miner-latest"
  "$PY" "$MINER" "$(date -d '21 days ago' +%Y-%m-%d)" "$(date +%Y-%m-%d)" --out "$OUT" --json
  

• 产出：$OUT/transcripts/_RECURRING.json（类型化结构化清单，每条带 frequency/recency_weight/vfm_hint/confidence）+ _DIGEST.json。
• 移交：加载 skill-evolve-pipeline，其阶段② 会优先消费 _RECURRING.json 作为 Stream C 第 4 需求源（省掉 flow 二次提炼）。

5.2 驱动 skill-evolve-pipeline 四阶段

加载 skill-evolve-pipeline 技能，按其四阶段执行（flow 作为编排者传入目标 skill 目录，pipeline 自行跑完）：

1. 阶段① 取回评测基线：install 拉线上版内容 + 记录 slug / ownerId；AI 评分（TRACE 五维）走 API 取，install 不含分数： GET https://api.skillhub.cn/api/v1/skills//evaluation（Bearer token 来自 credentials.json）→ 返回 dimensions.{trust|reliability|adaptability|convention|effectiveness}.items.{项}.score（1-5）+ summary/userSummary；无 overallScore，需自算各维均分。安全结论与 latestVersion 走 GET /api/v1/skills/（securityReports.keen/sanbu.status、latestVersion.version）。
2. 阶段② 认知放大器反思（含 Stream C）：四问 + Seal 分级；自动摄入 5.1 的 _RECURRING.json 并入 VFM 评分。
3. 阶段③ 定向借鉴循环：对 VFM≥60 需求抽"借用查询" → 本地兄弟 skill 扫描 + GitHub 定向搜 → 借鉴候选（复利索引 BORROW_INDEX.md）。
4. 阶段④ 优化重写 + 发布：综合 ①②③ 重写 SKILL.md/脚本；回流两块看板；重发到 SkillHub（含 dry-run 预检 + auto-retry + 发后回拉校验，同 Phase B 纪律）。

pipeline 内部已含"回流看板（REQUIREMENTS/SOLUTIONS）"与"发布铁律"，flow 无需重复； flow 只负责把五个 skill 串成一条链，并在关键决策点（选项 / 发布）把最后一票交给你。

步骤 6：闭环回启（可选持续进化）

• Phase C 重发后拿到新评测，可再次进入 步骤 5（5.1 miner → 5.2 pipeline 四阶段），形成"评测 → 优化 → 再评测"回路。
• 每轮"改什么"由 pipeline 阶段② 的 VFM 排序决定，"发不发"由发布门控决定——决策权始终在你。
• 若希望零手动：把"用 need-to-skill-flow 优化 "注册为 recurring automation（见进阶），按周 / 按评测触发。

交接契约（多 skill 的接口）

本工作流靠落盘契约解耦五个 skill，互不硬依赖：

• SPEC.md（decoder 产出 / builder 消费）：包含 需求本质 + 最小可行解假设、选定/候选实现路径、可借鉴项目清单、对比结论、约束与边界、建议触发词。builder 据其构建。
• 两块看板 REQUIREMENTS.md + SOLUTIONS.md（builder 打底 / pipeline 回流）：需求看板按 Stream A(用户) / B(评测+GitHub) / C(miner 隐性) 三分，方案看板记实现 + ADR + 墓地。pipeline 阶段④ 统一回流，是闭环的持久记忆。
• _RECURRING.json（miner 产出 / pipeline 阶段② 消费）：类型化结构化 recurring 清单，作为 Stream C 第 4 需求源直接并入 VFM，省 AI 二次提炼。

只要这三份契约结构稳定，五个 skill 可各自独立迭代、互不影响——这就是契约解耦的价值，也是 flow 能把整条生命周期串起来的根本原因。

质量纪律

高频问答、错误用法示例、真实端到端案例见 references/faq.md。

1. 步骤 1 不可跳过"需求本质"，否则整条链路退化成"找轮子工具"。
2. 选项阶段决策权归用户；工作流只呈现证据，不替选。
3. 三份契约（SPEC.md / 两块看板 / _RECURRING.json）必须落盘——它们是五个 skill 唯一的协作通道，也是可审计的痕迹。
4. builder 产出的 skill 必须过步骤 3.5 验证循环（install 可装 + dry-run 过门控 + 出口闸门两问可答），不接受"看起来能用"或 AI 自评质量。
5. 发布与重发是对外公开动作：Phase B / Phase C 的发布步骤必须显式取得用户确认后才执行，不静默发布。

故障应对与降级（依赖多工具时的兜底）

评测指出：错误提示有时偏模糊，且依赖多个外部工具时一旦出问题可能静默中断（errorHandling 4.3 / stability 4.3）。这一节把"怎么办"说人话。

总原则：流程在关键决策点（选项 / 发布）都显式等你确认，不会自作主张往前冲；任一外部依赖缺失都停下来告诉你，而非静默中断或假成功。

网络依赖与国内适配

本工作流对境外网络（GitHub）的依赖是可选增强，非核心链路硬依赖：

核心结论：解码 → 构建 → 发布 → 评测优化全链路在国内环境可独立完成；GitHub 仅用于"找参考"，缺失时自动降级，不影响交付。

进阶：注册为自动化（Automation）

若希望"给定需求文本即自动跑完整链路"，可把本工作流的提示词注册成 WorkBuddy Automation （mode=recurring 或 once），prompt 固定为"用 need-to-skill-flow 处理：<需求>"。 注意：因决策权在用户，全自动模式建议设为"跑到选项即暂停等确认"；Phase B/C 的发布步骤 涉及对外公开动作，自动化中必须保留人工确认门控，绝不静默发布。

附录 A：内嵌 Loop Engineering 验证纪律（自包含副本）

完整版见 loop-engineering skill（已发布 chenlin-loop-engineering）。此处为 flow 自包含兜底的精简副本，确保未安装 loop-engineering 时仍可执行步骤 3.5。

主循环 4 步

1. 定标：完成 = X 为真（可验证），不写"让它工作"
2. 最小：想清再写、最少改动、不投机加功能
3. 验证：用外部信号（跑测试 / 实际运行 / 独立来源交叉 / 对抗证伪），不用"我觉得"
4. 循环：不过回 2，记录为什么不过；收敛 = 标准达成或连续 2 轮无新洞察；僵局 = 连续 3 轮无进展则缩范围

防自欺铁律

• 禁止 AI 自评置信度，由验证结果反推
• 每结论写反证 + 失效条件
• 条件变了有效会变无效
• 证据不足 → 输出"证据不足"，不输出低置信度假结论

出口闸门（Rigor Gate） 宣布完成前书面答两问，任一答不出 → 降级不封顶：

1. 最强反证是什么？
2. 结论在什么条件下会崩？

极简三问（动手前自查）

1. 成功标准可验证吗？
2. 这是最少实现吗？
3. 我验证过还是我以为对了？