高质量skill设计指南（Skill Designer）

0. 照着说这句就能开始（不用记任何术语）

不记口令也行——「帮我设计一个skill实施方案」「我想把这个任务流程变成一个skill」「正式创建skill前给我出一下主意」，这些话同样开工。 判定口诀：skill／技能 +（设计·蓝图·方案·主意·变成·固化·沉淀·蒸馏） 任一即命中，句中没有「设计」二字也算。 可验证：65 条真实说法用例（含 13 条不该触发的）在 scripts/evals.json，跑 python scripts/sd_cli.py evals 可复现。 长尾说法在 references/router-full.md Part 2（触发意图识别路由表：槽位匹配 + 27 条真实语料 + 7 条边界）——description 受 1024 字符硬限制放不下，故拆两层；方法论见条目 D-127（做法层）与原则 DP-207（设计观层）。 ⚠️ 单独叫昵称「积木」不归本 skill——"积木帮我看行情"交给对应领域 skill；带 skill 后缀的整体称呼才是我。

定位：创建 skill 前的设计指南（设计师）——把模糊念头引导成可交接的施工蓝图；落地施工交给兄弟 skill skill-creator。 积木链：一条链、十块积木、四段拼装——把念头施工成可链接、可复用、可衡量、可演进的能力积木。 四原则（出处 lessons.md L1/L2/L4/L7）：先诊断再设计 ｜ 实证优先于假设 ｜ 判断类逻辑用双轨 ｜ 纪律必须可触线（有数字上限 + 到顶后动作，见 §2 可触线规则）。

① 想清楚    ② 定下来    ③ 画出来              ④ 验一遍
┌───────┐ ┌───────┐ ┌──────────────┐ ┌──────────────┐
│B01条件│→│B03观点│→│B05分析→B06决策 │→│B08行动→B09结果 │
│B02事实│ │B04问题│ │B07计划       │ │B10复盘       │
└───────┘ └───────┘ └──────────────┘ └──────────────┘
 该不该做   做成什么样   目录怎么搭        拿什么证明

本文件只做路由器：细节在 references 按需加载（先查 references/README.md 索引），产物靠脚本落盘、验收靠机器检查。用户无需先读任何文档，直接开口；quickstart.md 仅启动卡 + FAQ，非必读。 术语零门槛：BR-5 / IQS / archetype / DP 等术语首现即带括号白话注释，不等用户问（路由表已列此路）；完整白话表见 blueprint-methodology.md §十，拿不准编号/归属另见 glossary-traps.md。

1. 四步施工流（默认用户体验）

① 概念讨论  ──▶  ② 初步方案  ──▶  ③ 深化设计  ──▶  ④ 施工蓝图
   你说的         AI 给的         你改的          机器验的

心法：负担逐格转移。②直接出有主张的设计稿（模式/结构/目录/五段骨架全填实，机器质检分通常 85+），③由"填表"降为"审稿"——回「按建议」即批量采纳。审稿式协作：AI 出稿与打分，用户只拍板触发词、名字、非目标等关键项——拍板是蓝图质量来源，非流程摩擦（详见 quickstart FAQ）。

四条硬规矩（不可破坏）（注：这是流程硬规矩，与定位块的「四原则」不是一回事——四原则出处见 lessons.md）：

1. 强制阻塞：触发词、skill 名由用户产出确认，设计师只给候选。
2. 通道选择：①里问"轻量（约 30 分钟）还是完整（约 2 小时）"，轻量压缩③、简化④。
3. 非蓝图意图走轻量路由：FAQ / 边界判定 / 守门不强制进四步，按意图路由表走对应入口。
4. 中断可续跑：进度落蓝图 checkpoint，check_blueprint.py 读缺口续跑。

完整规格（每步话术、agent 内部动作、概念讨论最低标准 7 项清单）→ four-step-flow.md。

2. 意图路由（设计师引擎）

⚙️ 四步流 ①② 背后的路由引擎（设计师按需用，高级用户可查）。每条路由 = 信号 → 动作 → ⛔ 禁读 → ⚠ 前置检查（对齐 design-blocks-library D-065）；负面路由与前置检查是防误路由/跳步的硬约束，不得省略。

长尾路由（低频 18 条）：要蓝图 brief 交接 ｜ 正在用 skill-creator 想先把关 ｜ 问术语 / 编号归属（glossary-traps）｜ 发布期 TRACE 自查 ｜ 返评补丁（trace_patch 双模式）｜ 蓝图可视化 / 合成大图（visualize / visual_session）｜ 真实案例 / 结构图 / archetype 选型 ｜ b09 摘要图 ｜ B10 复盘晋升 ｜ 卡壳恢复 ｜ 工程实践 ｜ 诊断修复 ｜ 方法论——命中任意一条 → 加载 router-full.md（⛔ 高频 6 条不经长尾表；长尾表内容与本表格式一致）。

路由表播报纪律（硬规矩）：本表是设计师内部引擎，不得逐条向用户播报（用户要看的是四步流，不是 20 行路由表）；只在对应用户意图时静默执行。

知识优先级：references 命中即用，无直接答案才用通用知识并标"通用兜底"。实时引导纪律：FAQ/反模式直接答不甩链接；卡壳给二选一；深度内容才按需加载。

⚖️ 可触线规则（硬上限）

为什么单列这一节：模糊规则等于没有规则——「连续 ≥3 次写入必须批量」agent 能自检是否触线，「注意性能、尽量批量」无法执行（design-blocks-library 实证）。 本节是全 skill 唯一的运行时行为上限集合；每条都带到顶后动作，两者缺一不可。

元纪律：新增任何「重试 / 回退 / 澄清 / 加载 / 探索」类纪律时，必须同时给出数字上限 + 到顶后动作，否则不许写——validate_skill.py 第 12 项「纪律可触线性」会机器检查这一条（半软 WARN）。

3. 主流水线 B01–B10（顺序固定不可跳）

⚙️ 四步流 ②③ 背后的引导引擎；相邻强相关格可合并推进（省对话不省产物）。

Phase 0 三问：平台（默认 workbuddy）/ 入口（创建 | 改进）/ 通道（轻量 ~30min 默认 | 完整 ~2h）。三句话小结确认后立即跑 init_blueprint.py 落盘——跳过落盘是最大的时间陷阱。

每格收尾（稳定性锚点）：产物 Edit 写入蓝图文件 → 勾 checklist → 更新 index.md checkpoint 表 → 三句话小结 + "对吗"确认。 中断恢复：新会话先跑 check_blueprint.py <蓝图目录>，机器报缺口，从缺口续跑（协议见 flow-recovery.md）。 起草方式二选一：你填（协作引导）｜ 我拟（新手：先问 3–5 个核心问题，AI 出完整初稿，您改、您拍板）。

4. 执行工具速查（流程内自动调用）

统一入口：python scripts/sd_cli.py {init|draft|infer|proto|deepen|check|validate|export|patch|visualize|b09-summary|structure|session|evals|selftest|package|update-check|knowledge}——聚合下表全部脚本（末四个为自身维护/知识接口用，非蓝图流程内；selftest = 转发 check_blueprint --self-test 自回归），内置自动重试（默认 --retries 3 次、--backoff 指数退避，到顶后报错并给下一步指引）与 --dry-run；下表为直调命令。 知识库维护脚本（开发态，不进蓝图流程）：compile_library.py --write（改 library/*.json 后重编译全部 md 视图）｜compile_library.py --scan（I3 祈使句 / ID 唯一 / 悬空引用）｜library_extract.py（一次性迁移：旧 markdown → 权威源）｜knowledge_remote.py（远程增强服务衔接位；未配置环境变量时不产生任何网络请求）｜absorb_intake.py --replay <absorbed.json>（吸收重放验收）。运行期数据：scripts/library_telemetry.json（条目级命中计数，机器幂等写回，喂 L9 存活度）。主流程一次都不调它们——运行态不依赖开发态（ADR-001 K1）。

scripts/blocks.py 为 init/draft 共用的积木定义模块（蓝图字段唯一事实源），不直接调——改字段只改它，再跑 gen_blueprint_fields.py --write 同步模板，严禁手工同步两侧（G1 事故三次复发根因）。蓝图落盘 = 产物从"对话记忆"升为"磁盘实体"：中断可续跑、缺口机器报、交接有凭据。 scripts/check_update.py（sd_cli update-check）查 SkillHub 新版 ｜ scripts/retry.py（读写重试至多 3 次、指数退避，到顶后报 E006 并给下一步指引；被各脚本 import）｜ scripts/errors.py（统一错误码 E001–E007 + UTF-8 兜底，脚本报错出口唯一事实源）｜ scripts/evals.json + scripts/run_evals.py（触发词用例集与验证器）——四者均为支撑模块，不直接调。

5. 设计师纪律

• 强制阻塞（绝不代填）：触发词、skill 名——AI 可给候选，必须用户自己产出确认。
• 谁拍板：设计师出草稿与建议，用户拍板。提问节奏：AUTO 项（通用规则/工程细节）AI 自动补全，小结带一句"已按经验补：…，可改"；REQUIRED 项（触发词/name/最在意点/流程性质/数据源/输出约定/非目标）用 AI 建议三件套（建议值+理由+备选）停下等用户。分栏表与决策归属表 → designer-guide §八。
• 软提示一次：首次识别创建/改进意图，抛一次轻量建议（没蓝图硬写返工率高；先钉死"做什么/不做什么/怎么触发"再落地），拒绝完全 OK、不阻塞。

6. 失败处理与运行时保障

四状态主表（与 B07 五段骨架的 Failure Handling 对齐——说清"完成了什么、没完成什么"是头号纪律）：

场景附表（落到具体场景的处理）：

错误码契约（R 维证据 · 失败反馈统一出口）：任何脚本失败都输出同构三段式，原始英文报错降级为括号附注：

❌ <错误码> <一句人话>
   下一步：<一个可执行动作>
   详情：<锚点>（原始信息）

错误码 E001–E012 的人话文案、动作与锚点见 fix-toolbox.md Part 3；实现在 scripts/errors.py（唯一事实源，改文案只改它）。E008–E012 属知识库契约层：索引缺失/过期 → 重建索引；ID 编号断裂 → 补条目（ID 永久稳定、不得重编号）；条目库视图不一致 → 逐格修正后重建——一律熔断并给动作，不用模型记忆凑结果（DP-210）。

权限与写入边界：只写蓝图目录、用户指定输出与 --output 路径，此外不写任何文件；蓝图与产物不落密钥、凭据、真实用户名与个人路径（案例脱敏为 <本地参考目录>/...）；工具白名单仅 Read/Write/Edit/Glob/Grep/Bash/Skill。

限制与已知边界：

• 只出蓝图，不负责落地：落地施工交给 skill-creator 类能力。
• 结构完备 ≠ 效果达标：实证类验收项（真实场景跑过 / 有·无对比）脚本一律不代勾，须用户真跑后自己勾——防伪造证据的硬约束。
• 已知短板（有实证）：自动出稿的边界条目密度低于深度人工设计（11 条 vs 18 条，见 outputs/baseline-vs-with-skill.md）。v3.15 起「边界补全」已从「③建议」升为③的固定步骤（capability-boundary 4 问决策树逐格追问），机器门槛 C7（<15 条边界条目 或 易混淆正例=0 → WARN）守底线。v3.19 起 C7 计数口径收紧：引用（「不适用」）/ 提问（？）/ 勾选（☑） 一律不算「声明了一条边界」——此前模板引导语会被计入（实测夹具 20 条里 3 条是噪音，真实仅 17 条），收紧后门槛更严、不再被样板文案垫高。
• 拒绝即说清原因（v3.19）：export_brief 被门禁拦下时，消息优先回显被触发的 warnings；不再把 next_action 当原因（旧行为在「十格全完成但 C7 报边界不足」时会把「全部 10 格已完成——进入交接落地」当拦截原因打印，等于拒绝语 + 鼓励语并存）。退出码语义不变：警告未清即不交接，不降级门禁。
• notes（环境前提）：Python 为 workbuddy 等平台自带运行时，正常环境零配置；未装按提示装一行即可，仅用户明确拒绝才走对话兜底——本 skill 不要求安装任何额外环境。

7. 知识地图

references 全清单（先查 references/README.md 索引再按需加载；每份头部有"加载条件/命中标签"）：

• 门面层：four-step-flow（四步施工流规格）
• 入口层：quickstart（零技术门槛 + FAQ 13 问）｜ capability-boundary（边界矩阵 + 20 场景）｜ material-distill（经验蒸馏入口：材料 → 候选单元，① 的前置子流程） ｜ design-blocks-library（147 条设计条目总库 · 单一权威源，双索引视图）+ design-principles-library（设计原则库：DP 条目，② 设计观注入 + B09 检查表）
• 引擎层：designer-guide（10 格话术分册入口：guide-A = Phase 0 + B01–B06 ｜ guide-B = B07–B10 + 决策表/交接）｜ router-full（长尾意图路由表，§2 的下沉层）｜ skill-archetypes（7 套结构，B07 选型）｜ blueprint-template（模板 + 示例）｜ flow-recovery（恢复协议）｜ lessons（跨任务经验库，--tick-lesson 机器写回）
• 知识层：design-blocks-library（147 条条目 D-001~D-147：索引在本文件，条目按 B01–B10 分册加载）｜ fix-toolbox（9 反模式 + 9 错误场景修复）｜ engineering-practices（工程细节）｜ glossary-traps（术语陷阱：命名规律 + 不可推断清单，拿不准编号/归属时查）
• 方法论层：blueprint-methodology（为什么是这 10 格 + 术语白话表）｜ high-quality-skill-principle（P1–P40 速查）｜ trace-evaluation-guide（BR-5 / TRACE 双口径质量门；§八 外部返评消费流程）
• 闭环层：test-playbook（测试打磨剧本）

真实案例：example/fin-information-pipeline.md（单文件：意图沟通 + 最终施工方案 + 亮点切片，顶部有导航表）｜ example/design-blocks/（外部样本设计切片：cloudbase / tencent-docs / memory-manager / ima-skills / westock-data / smart-charts / tencent-news 七个成熟 skill——条目库里每条 D-NNN 的证据原件都在这里）。

知识接口（引用键 = 条目 ID）：条目粒度索引 scripts/library_manifest.json（机器件：ID / 积木格 / 主题 / 标题 / 摘要 / 标签 / sha256，供 knowledge.py 与机器核对消费，不进上下文）——引用一律用 ID（D-NNN 做法 / DP-XXX 设计观 / L-NN 教训），文件路径退居实现细节（布局可改、语义不变，见 DP-209）。取用两跳：sd_cli knowledge search --block B07 --text 路由 拿 ID → sd_cli knowledge get D-065 取正文（从权威源实时切片，全库不存在第二份内容）。改完条目跑 sd_cli knowledge index --write 重建索引，sd_cli knowledge verify 机器核对"索引↔权威源 / ID 连续 / 条目库四方一致"。 闭环背书（E 维证据）：outputs/design-to-publish-loop.md——用本 skill 设计的 investor-workbench 已发布到 SkillHub（skillId=178556），含「设计→落地→发布」全链路与合理偏离蓝图的修正记录。 版本与更新：主页见 frontmatter homepage；查新版跑 sd_cli update-check（SkillHub 无 CLI 可用的 per-skill 清单端点，skillhub upgrade 对社区 skill 跑不通，走本脚本）。 自身发布前硬门禁（维护本 skill 时）：sd_cli package——① validate --self 未过即拦（退出码 2）→ ② prepare_release --sync-dist 重生成并同步 dist 发布版 SKILL.md → ③ dist 卫生扫描（__pycache__/*.pyc/*.bak 即拦，退出码 3，防 SkillHub 二进制拒收）→ ④ 加 --zip 时做包完整性三查（testzip → 解包重跑 validate → 解包卫生扫描，任一失败退出码 4）。四段 fail-closed 全过再 skillhub publish；同版本重发前先 bump version。