高
高质量技能设计指南
作者：鹿Sir开发工具v2
像搭积木一样设计高质量技能，通过概念讨论、初步方案、深化设计、施工蓝图四步施工流，把模糊想法变成标准化、可复用、可演进的技能设计蓝图，内置质量检查与最佳实践。当用户需要设计新技能、创建 Skill、固化工作流程或评审技能设计质量时触发。触发词：技能设计、设计蓝图、积木设计、技能工作流。
下载量
403
点赞
98
价格
免费
技能文档
---
name: high-quality-skill-guidance
title: 高质量技能设计指南
category: 开发工具
description: 像搭积木一样设计高质量技能，通过概念讨论、初步方案、深化设计、施工蓝图四步施工流，把模糊想法变成标准化、可复用、可演进的技能设计蓝图，内置质量检查与最佳实践。当用户需要设计新技能、创建 Skill、固化工作流程或评审技能设计质量时触发。触发词：技能设计、设计蓝图、积木设计、技能工作流。
---
# Skill Designer · 积木设计指南
> **定位**：skill 的**设计指南（设计专家）**——把模糊念头、简单任务过程引导成深度可落地的**施工蓝图**。通过标准化四步法和积木设计方法，帮助不熟悉 skill 的用户交互式讨论设计各个方面、获得最佳实践建议，快速产出清晰标准化的高质量设计，避免生成勉强可用的简单 skill。
> **积木链**：一条链、十块积木、四段拼装——把念头施工成**可链接、可复用、可衡量、可演进**的能力积木。
> **积木四原则**：蓝图优先｜增量优于全量｜可替换不绑定｜闭环即进化。
>
> ```
> ① 想清楚 ② 定下来 ③ 画出来 ④ 验一遍
> ┌───────┐ ┌───────┐ ┌─────────────┐ ┌─────────────┐
> │B01条件│→│B03观点│→│B05分析→B06决策│→│B08行动→B09结果│
> │B02事实│ │B04问题│ │B07计划 │ │B10复盘 │
> └───────┘ └───────┘ └─────────────┘ └─────────────┘
> 该不该做 做成什么样 目录怎么搭 拿什么证明
> ```
> **白话一行懂**：条件=该不该做｜事实=谁用·撞不撞车｜观点=用哪种打法｜问题=还有哪些没定｜分析=进什么出什么｜决策=拆还是合｜计划=目录怎么搭｜行动=拿什么场景试｜结果=够不够格发布｜复盘=下次怎么更快。
> **本文件只做路由器**：细节在 references 按需加载（先查 [references/README.md](references/README.md) 索引），产物靠脚本落盘、验收靠机器检查。**用户无需先读任何文档，直接开口**；[quickstart.md](references/quickstart.md) 仅启动卡 + FAQ，非必读。
> **术语零门槛**：专业说法首次出现时**自动带一句白话注释**，不必先学再用；完整对照表见 [blueprint-methodology.md](references/blueprint-methodology.md) §十（仅在追问时才加载）。
> **一句话定位**：本 skill 不产「勉强能跑的简单 skill」——它用四步交互式讨论，陪经验不足的用户把模糊念头聊成一份深度、标准、可直接施工的蓝图。
>
## Quick start：照着说这句就能开始
| 你想干什么 | 直接说这句 | 接下来发生什么 |
| ----------------- | ----------------------- | ------------------------------------------------------------------ |
| 从零做一个 skill | **设计skill** | 回问 **2 件事**（平台、入口），确认后立刻建蓝图目录——**通道默认走完整流程**（一次过把 B01–B10 走完拿到施工图） |
| 改进已有 skill | **改进skill** | 先读现有 SKILL.md 做诊断，**只对缺口格引导**，不从零重走 |
| 已先跑过一遍、想固化成 skill | 说「把这一步固化下来」 | 走**提炼型入口**（`--entry extract`）：拿手工做过的那一遍当天然 baseline，反推 skill |
| 用专用称呼呼叫 | **积木skill** ／ **积木设计师** | 同上，按你说的意图自动分到新建／改进／固化流程 |
> **不记口令也行**——下面这些真人说法**全都开工**（句子里不必出现"设计"二字）：
> 「正式创建 skill 前给我出一下主意」｜「把一个初步的任务想法变成一个 skill」｜「我想把这个任务流程变成一个 skill」｜「帮我把这个流程固化下来」
> **判定口诀**：**skill／技能 +（设计·蓝图·方案·主意·变成·固化）** 任一意图即命中。
---
## 技能工作流（四步施工流程）
```
① 概念讨论 ──▶ ② 初步方案 ──▶ ③ 深化设计 ──▶ ④ 施工蓝图 ──┬▶ 到此为止，交接 brief（默认）
你说的 AI 给的 你改的 [边界补全] 机器验的 └▶ ⑤ 施工通道（可选接力）
```
流程逻辑：**负担逐格转移**。②直接出**有主张的设计稿**（模式/结构/目录/五段骨架全填实，机器质检分通常 85+），③由"填表"降为"审稿"——回「按建议」即批量采纳。**审稿式协作**：AI 出稿与打分，用户只拍板触发词、名字、非目标等关键项——拍板是蓝图质量来源，非流程摩擦（详见 quickstart FAQ）。
| 步 | 用户做什么 | 设计师内部（用户不必见） | 产物 | 出口 |
|----|-----------|------------------------|------|------|
| **① 概念讨论** | 说想法、丢历史资料、说"改进我的 X skill" | 意图路由 → **两问**（平台 / 入口）→ 边界决策树 → 最低标准自查（**A 组 4 项缺一不出方案**，B 组缺标粗版） | 三句话需求小结（可出**需求小卡 SVG**：问题/给谁用/不做什么/一句话定位） | 用户确认小结 |
| **② 初步方案** | 说"出初稿"；想先看 AI 怎么想 → `sd_cli infer` | `infer_design` 推断 + `blueprint_proto` 一键出方案 + 注入 lessons + 设计条目 + 总览图 | 有主张的设计稿（10 格填实，标【AI 建议】）+ 总览图 | 用户看完初稿 |
| **③ 深化设计** | 提意见、补细节；回「按建议」批量采纳 | designer-guide 逐格深挖（每轮 1–2 格，AI 建议三件套）+ 最佳实践 + 强制阻塞 + **非目标清单确认** + **边界补全（固定步骤）** + checkpoint | 逐格定型的蓝图 + 非目标清单 + 边界条目集 | 用户说"可以出蓝图了" |
| **④ 施工蓝图** | 确认正式蓝图 | `check_blueprint` 质量门（**含 C7 边界密度门槛**）+ B09 BR-5 评分（**五维体检**：边界 / 失败 / 触发 / 结构 / 验证各打 1–5 分，评的是"约定了吗"） + `render_structure` 结构图 + `export_brief` 交接（**brief.json 一等契约** + 决策溯源表） | 施工蓝图 + 结构图 + 交接 brief | 用户拍板 + 非目标已确认 → 交接 |
| **⑤ 施工通道**（可选旁路） | 说「施工 / 照蓝图开工」，或④出口二选一选它 | 前置门 `check_brief`（契约有效）+ `check_blueprint` 报 **`gate_open`（设计完备）**→ 执行器选择（**首选 `construct.py` 差异化施工 → 已装施工类 skill / skill-creator 接力真跑发布 → 兜底对话施工**）→ `construct.py` 读 brief.json 无损渲染 → 机器验收 → 用户真跑后**手勾**实证回填 B08/B09 | 落地的 skill 目录 + `11-施工.md` 施工台账 | validate + evals 全过 + 用户真跑确认；主定位「设计指南」不变，⑤渲染不代工 |
**四条硬规矩（不可破坏）**（流程层的硬规矩，≠ 积木哲学的"四原则"——四原则是设计观，见 [blueprint-methodology.md](references/blueprint-methodology.md) §三）：
1. **强制阻塞**：skill 名、触发词由用户产出确认，设计师只给候选。
2. **一次过走完**：**通道默认完整**——①里不问"轻量还是完整"，一次把 B01–B10 走完拿到施工图。"轻量"降级为**过程内逃生舱**：随时可以说「走轻量」压缩后续步骤（可逆的权衡不该在信息最少的门口设卡——详见 [four-step-flow.md](references/four-step-flow.md) §一）。
3. **非蓝图意图走轻量路由**：FAQ / 边界判定 / 守门**不强制进四步**，按意图路由表走对应入口。
4. **中断可续跑**：进度落蓝图 checkpoint + **`NEXT.md`（三行制续跑入口，`--write-next` 自动刷新）**，`check_blueprint.py` 读缺口续跑。
### 步骤1：概念讨论
用户说想法、丢历史资料或提出改进已有技能；设计师做意图路由、两问确认（平台/入口）、边界决策树与最低标准自查，产出三句话需求小结并请用户确认。
### 步骤2：初步方案
运行 `sd_cli infer` 与 `blueprint_proto` 一键产出有主张的设计稿（10 格填实并标注 AI 建议），附总览图交用户过目。
### 步骤3：深化设计
按 designer-guide 逐格深挖（每轮 1–2 格），用户回「按建议」即可批量采纳；完成非目标清单确认与边界补全，形成逐格定型的蓝图。
### 步骤4：施工蓝图
运行 `check_blueprint` 质量门与 B09 BR-5 五维评分，渲染结构图并导出交接 brief（brief.json 一等契约 + 决策溯源表），用户确认正式蓝图。
### 步骤5：施工通道（可选旁路）
前置门校验 brief 契约有效且设计完备后，首选 `construct.py` 差异化施工渲染出技能目录骨架，机器验收后由用户真跑确认并回填实证项。
完整规格（每步话术、agent 内部动作、概念讨论最低标准 7 项清单）→ [four-step-flow.md](references/four-step-flow.md)。
## 2. 意图路由（设计师内部引擎）
> ⚙️ 四步流 ①② 背后的路由引擎（设计师按需用，用户不必查看）。每条路由 = **信号 → 动作 → ⛔ 禁读 → ⚠ 前置检查**；负面路由与前置检查是防误路由/跳步的硬约束，不得省略。
> ⛔ **本表是给设计师用的内部引擎，不逐条向用户播报**——命中哪条就安静执行，用户只看到对应动作与结果。
| 用户意图 / 信号 | 动作 | ⛔ 禁读 | ⚠ 前置检查 / 护栏 |
|------------------|------|---------------------|----------------------|
| 从零创建 skill、需求模糊 | **Phase 0 两问**（平台 / 入口）→ `init_blueprint.py` 落盘 → 沿 B01–B10 引导（话术库按格加载：[designer-guide.md](references/designer-guide.md) 入口，分册 A/B） | — | 两问确认后**立即落盘**，跳过是最大时间陷阱 |
| 改进已有 skill | 先诊断（designer-guide-B §七）→ `init --entry improve` → 仅对缺口格引导 | ⛔ 别按"从零创建"从 B01 重走 | 先读已有 SKILL.md 再诊断 |
| **已有真实场景先例，想固化成 skill**（"我手工做过一遍""这个流程我一直在用"） | **提炼型入口**：`init --entry extract` → 把先例那一遍作为 baseline 写进 B02/B08 → 按先例反推设计 | ⛔ 别当"从零创建"重问一遍（用户已有答案） | 先问清"先例是怎么做的、哪一步最费劲"——那是 skill 的核心 |
| 问"怎么用 / 从哪开始 / 要装什么吗" / **查 FAQ** | 加载 [quickstart.md](references/quickstart.md)（FAQ 13 问速查） | ⛔ 别加载话术库全量 | FAQ 权威源在 quickstart，别在别处另答 |
| **B09 质量门：给蓝图打分** | 加载 [trace-evaluation-guide.md](references/trace-evaluation-guide.md) §一–§四（**BR-5（五维体检）设计期**）；机器先跑 `check_blueprint.py` 报缺口 | ⛔ 别用发布期口径评蓝图 | 每维证据找得到，找不到最高 2 分 |
| **蓝图已定稿要施工** / 说「施工」「照蓝图开工」「继续把它做出来」 | **⑤施工通道**（可选旁路）：前置门 `check_brief`（brief.json 契约有效）+ `check_blueprint` 报 **`gate_open: true`（设计完备）** → 执行器选择（**首选 `construct.py` 差异化施工 → 已装施工类 skill / skill-creator 接力真跑发布 → 兜底对话施工**）→ `construct.py` 读 brief.json 无损渲染；规格与纪律见 [four-step-flow.md](references/four-step-flow.md) §四-B + [designer-guide-B.md](references/designer-guide-B.md) §九 | ⛔ 别重走 B01–B10；⛔ 别代勾 B08 实证项（用户真跑后手勾） | brief 未导出先跑 `export_brief`（导出即签契约）；`sd_cli check-brief brief/brief.json` 验契约；施工台账落 `11-施工.md` |
| 问"这个场景能不能用" / 拿不准边界 | 加载 [capability-boundary.md](references/capability-boundary.md)（决策树 + 20 场景） | ⛔ 别直接进 B01 引导 | 先跑边界决策树 |
| 卡壳 / 跑偏 / 会话中断恢复 | **先读蓝图目录的 `NEXT.md`**（上次到哪 / 下一步 / 待拍板）→ `check_blueprint.py` 读缺口 → 加载 [flow-recovery.md](references/flow-recovery.md) | ⛔ 别重头问、⛔ 别无头绪地翻磁盘重建上下文 | 从缺口续跑 |
| **其余长尾意图**（交接 brief / 返评补丁 / 术语 / 真实案例 / 结构图 / 复盘晋升 / 工程细节 / 打磨诊断 / 方法论…） | ⛔ **先查 [references/router-full.md](references/router-full.md) 长尾路由表**，按表执行 | ⛔ 别凭记忆自由发挥、别把长尾当主流水线 | 本表只留高频 6 条，是单一入口 |
**知识优先级**：references 命中即用，无直接答案才用通用知识并标"通用兜底"。**实时引导纪律**：FAQ/反模式直接答不甩链接；卡壳给二选一；深度内容才按需加载。
## 3. 主流水线 B01–B10（顺序固定不可跳）
> ⚙️ 四步流 ②③ 背后的引导引擎；相邻强相关格可合并推进（省对话不省产物）。
**Phase 0 两问**：运行平台 / 入口（创建 \| 改进 \| **提炼**）。三句话小结确认后**立即跑 `init_blueprint.py` 落盘**——跳过落盘是最大的时间陷阱。
> **通道不问**：默认一次过走完 B01–B10 拿到施工图；"轻量"是**过程内逃生舱**——随时说「走轻量」压缩后续。可逆的成本权衡不该在信息最少的门口设卡。
| 格 | essence | MVP 问题（非答不可） | 产物落点 |
|----|---------|----------------------|----------|
| B01 条件 | 该不该做：准入四问 | 解决谁的什么问题？过四问吗？ | `01-条件.md` |
| B02 事实 | 画像 + 生态正交性 + **资产吸收清单** | 谁用、什么场景？生态有重叠吗？重叠了捡什么？ | `02-事实.md` |
| B03 观点 | 设计模式处方 + 依据 + **立意卡三问** | 交互×内容模式选哪个？为什么适合？**凭什么独到**（主张/取径/反着来）？ | `03-观点.md` |
| B04 问题 | 需求澄清（列待定项） | 还有哪些口径没定？谁拍板？ | `04-问题.md` |
| B05 分析 | 输入输出契约 + 风险 | 输入/输出是什么？错了代价多大？ | `05-分析.md` |
| B06 决策 | 方案抉择 + 输出文件约定 + **取舍记录≥2** | 拆还是合？涉及文件产出→约定四要素；**哪些可行做法偏不选**？ | `06-决策.md` |
| B07 计划 | 施工图（目录骨架） | 目录怎么画？先做什么后做什么？ | `07-计划.md`；可加 `blueprint.svg` |
| B08 行动 | 真实场景验证 | 用什么真实场景测？有/无对比了吗？ | `08-行动.md` |
| B09 结果 | 质量门：**完备度机器算** + 五维体检人工评 + **独到性小结** | 十格填齐了吗？五维各几分、证据在哪一格？**差异点≥2（含1条偏不）**？ | `09-结果.md`；可加 `b09-summary.svg` |
| B10 复盘 | 失败归纳为通用规则 + **成功侧三必答** | 归纳成什么通用规则？下轮迭代点？**立意活了没/取舍对不对/分歧升格**？ | `10-复盘.md` |
**每格收尾（稳定性锚点）**：产物 Edit 写入蓝图文件 → 勾 checklist → 更新 `index.md` checkpoint 表 → 三句话小结 + "对吗"确认。设计期**填不出的项**（【待回填】/[后置]/[可选]）不必逐项对话确认——`PENDING.md` 回填包已由 init/draft 一次性归并、`check_blueprint --write-next` 同批刷新（已勾项保留），真跑/发布后用户手勾即可。
**中断恢复**：新会话**先读蓝图目录的 `NEXT.md`**（三行制：上次到哪 / 下一步 / 待拍板），再跑 `check_blueprint.py <蓝图目录>` 读缺口，从缺口续跑（协议见 [flow-recovery.md](references/flow-recovery.md)）。
**起草方式二选一**：**你填**（协作引导）｜ **我拟**（新手：先问 3–5 个核心问题，AI 出完整初稿，您改、您拍板）。
## 4. 执行工具速查（流程内自动调用）
> **统一入口**：`python scripts/sd_cli.py {init|draft|infer|proto|deepen|check|check-brief|construct|baseline|validate|export|patch|evals|visualize|b09-summary|structure|knowledge|distinct|defaults|assets}`——聚合下表全部脚本，内置自动重试（`--retries`/`--backoff`）与 `--dry-run`；下表为直调命令，参数细节以各脚本 `--help` 为准。
| 脚本 | 作用 | 直调命令 |
|---|---|---|
| `init_blueprint.py` | Phase 0 确认后立即初始化蓝图（顺带生成 PENDING.md 回填包） | `<蓝图目录> --name "<skill名>" [--channel full（默认，与硬规矩 2 一致）] [--entry create\|improve\|extract]` |
| `infer_design.py` | ②推断引擎：六问信号 → 模式/框架 | `--answers '<JSON>' [--archetype <id>]` |
| `draft_blueprint.py` | 「我拟」路径：出**有主张**初稿（含 B05 边界候选池 ≥15 条 + PENDING.md；`--force` 重建自动继承用户拍板字段） | `<蓝图目录> --name "<n>" --answers '<JSON>' [--force]` |
| `blueprint_proto.py` | ②一键出方案：A 组校验 → draft → essence 图 | `<蓝图目录> --name "<n>" --answers '<JSON>'` |
| `check_blueprint.py` | 机器算 IQS / ⑤前置门（`gate_open`）/ 刷新 `NEXT.md`；退出码 0 门开 / 1 缺口 / 2 仅警告；**验收分层**（`[后置]/[可选]` 不阻断）；含 C7 边界 / C9 取舍门槛 | `<蓝图目录> [--json] [--write-iqs] [--write-next]` |
| `validate_skill.py` | B09 对已有 skill 目录静态检查 / 打磨交付 | `<skill目录> [--json\|--fix\|--diag]` |
| `export_brief.py` | ④交接产物（summary + brief.json 一等契约 + SKETCH，含决策溯源与 **verification_plan 验证计划**）；**导出即校验契约，破坏拒绝导出** | `<蓝图目录> --output <目录> [--format all] [--glossary]` |
| `check_brief.py` | ④⑤交接契约校验（schema / 验收三关 / 门禁缺口一致）；0 有效 / 1 破坏 / 2 带缺口已声明 | `<brief.json> [--json]` |
| `construct.py` | ⑤差异化施工：brief.json → skill 文件树（确定性渲染，不发明内容）；suite 递归（`sub_skills` → 子 SKETCH + 索引）；**渲染后预置 `11-施工.md` 台账（verification_plan 置顶，幂等）** | `<brief.json> --output <目录> [--archetype X] [--check]`；`--tick-realrun <蓝图> --note "凭据"` 真跑回填（只勾 [后置]，无凭据拒绝） |
| `baseline_ab.py` | **E 维证据**：受控 A/B 对比出报告 | `control --name <n> --answers '<需求>'`；`report --with <蓝图\|brief.json> --baseline <BASELINE.md>` |
| `trace_patch.py` | 五维低分补丁清单：`--mode design`（补格）｜`--mode ship` 默认（改文件） | `<反馈.json> [--mode ...] [--threshold 4.5]` |
| `visualize_blueprint.py` | 蓝图 SVG：`--mode completion` 默认｜`essence` ②用 | `<蓝图目录> --output blueprint.svg` |
| `b09_summary.py` | B09 摘要图；缺分自动补算 | `<蓝图目录> --output b09-summary.svg` |
| `render_structure.py` | B07 后文件结构图 | `<蓝图目录> --output structure.svg [--format svg\|md]` |
| `run_user_tests.py` | 回归测试（用例库 `user_test_cases.json`） | `[--cases id1,id2] [--json]` |
| `deepen_blueprint.py` | ③深化设计：批量采纳 / 定向拍板 / 勾验收 | `<蓝图目录> [--accept-all] [--set "B02.正交性=..."] [--tick B01,B02]` |
| `run_evals.py` | **A 维证据**：43 条触发词用例自检（`evals.json`） | `[--json]` |
| `validate_knowledge.py` | **知识库勾核（五向）**；②③「按格注入」机器入口 | `--query B06`｜`--rebuild`｜`--summary` |
| `distinctiveness_scan.py` | **分歧度只读扫描**（四阀第 4 阀，报告级非门禁） | `<蓝图目录> [--json]`；`--self-test` |
| `blueprint_defaults.py` | **版本化默认蓝图快照**（分歧度参照系，落 [`scripts/blueprint-defaults.json`](scripts/blueprint-defaults.json)） | `--rebuild`（模板改版必跑）｜`--check`｜`--show` |
| `creative_assets.py` | **创意素材状态机**（假设→已验证→已证伪→已过时；升格权在复盘） | `list｜check｜set-status`；`--self-test` |
| `retry.py` / `errors.py` | 重试基础设施（import 用）/ **R 维**统一错误码 E001–E007 三段式报错 | `errors.py` 无参数列出错误码 |
> `scripts/blocks.py` 为 init/draft 共用的积木定义模块，不直接调。蓝图落盘 = 产物从"对话记忆"升为"磁盘实体"：中断可续跑、缺口机器报、交接有凭据。任何脚本失败都走 `errors.py` 三段式出口（详见 §6）。
## 5. 设计师纪律
- **强制阻塞（绝不代填）**：触发词、skill 名——AI 可给候选，必须用户自己产出确认。
- **谁拍板**：设计师出草稿与建议，用户拍板。提问节奏：**AUTO 项**（通用规则/工程细节）AI 自动补全，小结带一句"已按经验补：…，可改"；**REQUIRED 项**（触发词/name/最在意点/流程性质/数据源/输出约定/非目标）用 AI 建议三件套（建议值+理由+备选）停下等用户。分栏表与决策归属表 → designer-guide §八。
- **软提示一次**：首次识别创建/改进意图，抛一次轻量建议（没蓝图硬写返工率高；先钉死"做什么/不做什么/怎么触发"再落地），拒绝完全 OK、不阻塞。
- **口令归属（消歧）**：§0 的**入口口令**是本 skill 自身被触发的方式，由维护者拍定并写进 description；而「强制阻塞」约束的是**产出蓝图里那个 skill 的触发词**——两者不是一回事，不冲突。
## 6. 失败处理与运行时保障
**四状态主表**（与 B07 五段骨架的 Failure Handling 对齐——说清"完成了什么、没完成什么"是头号纪律）：
| 状态 | 判定 | 处理 |
|------|------|------|
| Not started | 尚未开工即遇阻 | 向用户说明障碍与替代路径，不静默放弃 |
| In progress | 中途卡壳 / 会话中断 | `check_blueprint.py` 读缺口续跑，checkpoint 是恢复依据 |
| **Partial success** | 部分格完成 | **必须说清**：已完成哪些格、缺口在哪、下一步从哪续——禁止只报喜 |
| Failed safely | 无法继续但无损失 | 蓝图文件与产物完好，交代终止原因与重启方式 |
**场景附表**（落到具体场景的处理）：
| 场景 | 处理 |
|------|------|
| 需求过不了准入四问 | 引导转向 Rule / 脚本·MCP / 不做，不硬造 skill |
| 回答太宽泛 / 沉默不确定 | 追问"想象一个具体的人在什么场景打开它"；给二选一不空等 |
| 要求代填触发词 / 名字 | 礼貌拒绝，给例子引导用户产出（强制阻塞） |
| 只想快速生成不管质量 | 尊重：走轻量通道，提醒可后续升级 |
| 蓝图目录已存在且非空 | init 幂等拒绝覆盖 → 续填已有蓝图或换目录 |
| 脚本报错 | **一句话**：`sd_cli` 自动重试 3 次（环境/IO 类，业务错误不重试），仍失败给下一步指引，环境恢复后补跑。**详情** → [E003](references/fix-toolbox.md#e003) |
| Python 未装 | **一句话**：按提示装一行即可（平台通常自带，零配置）；明确不装则回「不用 Python」切对话兜底——开场声明产物照出，但落盘/机器打分/续跑暂停。**详情** → [E003](references/fix-toolbox.md#e003) |
| 引用的 reference 不存在 | 用 SKILL.md 内嵌知识继续，不阻塞 |
**退出码契约**（自动化编排可依赖，全脚本统一）：
| 退出码 | 含义 | 谁在用 |
|--------|------|--------|
| `0` | 成功 | 全部脚本 |
| `1` | **业务失败**（统一）——必附「错误码 + 一句人话 + 下一步」三段式 | 全部脚本（走 `errors.py`） |
| `2` | **仅警告**（设计完备但有跨格一致性警告 / 契约带缺口已声明，非失败） | `check_blueprint` 报一致性警告（`gate_open` 仍为 false）；`check_brief` 报「带缺口已声明」（`gate_open:false`+gaps 自洽） |
> **为什么 2 不是失败**：`check_blueprint` 的 2 表示"设计已完备、只剩一致性警告"，是续跑依据而非错误——把它并成 1 会让编排方无法区分"真失败"与"待补"。
> **⑤ 前置门的判据是 `gate_open`（= 设计完备且无警告），不是"十格全勾"**（v4.4.2）——`[后置]/[可选]` 验收项天然要等真跑或发布，未勾**不阻断开工**。
**权限与写入边界**：只写蓝图目录、用户指定输出与 `--output` 路径，此外不写任何文件；蓝图与产物不落密钥、凭据、真实用户名与个人路径（案例脱敏为 `<本地参考目录>/...`）；工具白名单仅 `Read/Write/Edit/Glob/Grep/Bash/Skill`。
**限制与已知边界**：
- **只出蓝图，不负责落地**：落地施工交给 系统默认安装的skill-creator 类能力；蓝图定稿后的**可选 Step ⑤ 施工通道**只做派发与验收回填（执行器优先已装施工类 skill，降级内置 skill-creator），不改变本定位。
- **结构完备 ≠ 效果达标**：实证类验收项（真实场景跑过 / 有·无对比）**脚本一律不代勾**，须用户真跑后自己勾——防伪造证据的硬约束（⑤施工通道同样遵守）。
- **验收项按「可判定时点」分层**：验收项分 `[设计期]`（未勾 ⇒ 阻断 ⑤）/`[后置]`（要真跑）/`[可选·发布后]`（要发布返评）三层，**门禁只判设计完备**。此前三层混在一个 fail-closed 门里，使 ⑤ 前置门对**任何如实的蓝图**都关着（框架既说"实证项⑤后勾"、又要求"⑤前勾完"——自相矛盾的死锁）。标签写法与判据见 [blueprint-template.md](references/blueprint-template.md) B08/B09 节；回归锁在 `check_blueprint --self-test` 与 `user_test_cases.json::check-gate-open-with-deferred`。
- **边界密度短板已建机制防守**：③深化设计新增**「边界补全」固定步骤**（capability-boundary 4 问决策树 + 易混淆正例/前提降级模板 + 条目库注入），`check_blueprint` **C7 门槛**机器守底线（<15 条或无正例 → WARN）——短板从"靠人记"升级为"机器拦"，实证基线见 [`outputs/baseline-vs-with-skill.md`](outputs/baseline-vs-with-skill.md)。
- **notes（环境前提）**：Python 为各 Agent 平台常见自带运行时，正常环境零配置；未装按提示装一行即可，仅用户明确拒绝才走对话兜底——本 skill 不要求安装任何额外环境。
## 7. 知识地图
**references 全清单**（先查 [references/README.md](references/README.md) 索引再按需加载；每份头部有"加载条件/命中标签"）：
- **门面层**：four-step-flow（四步施工流规格 + **⑤施工通道规格**）
- **入口层**：quickstart（零技术门槛 + FAQ 13 问）｜ capability-boundary（边界矩阵 + 20 场景）
- **引擎层**：router-full（**长尾路由表**，SKILL.md §2 的下沉层）｜ designer-guide（10 格话术**分册入口**：[designer-guide-A.md](references/designer-guide-A.md) = Phase 0 + B01–B06 ｜ [designer-guide-B.md](references/designer-guide-B.md) = B07–B10 + 决策表/诊断/交接）｜ skill-archetypes（7 套结构，B07 选型）｜ blueprint-template（模板 + 示例）｜ flow-recovery（恢复协议）｜ lessons（跨任务经验库，`--tick-lesson` 机器写回）
- **知识层**：design-blocks-library（**68 条设计条目总库 · 单一权威源**，双索引视图：按积木格 B01–B10 / 按主题 T1–T10）｜ generic-cliches（**反例库**：7 archetype × 5 平庸立意避雷，B03 立意卡注入）｜ fix-toolbox（9 反模式 + 9 错误场景修复）｜ engineering-practices（工程细节）
- **方法论层**：blueprint-methodology（为什么是这 10 格 + 术语白话表）｜ high-quality-skill-principle（P1–P40 速查）｜ trace-evaluation-guide（BR-5 / TRACE 双口径质量门 + **§九 外部返评消费流程**）
- **闭环层**：test-playbook（测试打磨剧本）
**知识库结构化（勾核地图，v4.6.0）**：上面的分层是给人看的「门面」，机器侧另有一份**落位地图** [`scripts/knowledge_map.json`](scripts/knowledge_map.json)——声明每份 reference / 脚本 / 数据文件落到**四步①–⑤哪一步、十格 B01–B10 哪一格、知识类型（点/横切/基座）**。68 条设计条目与 7 条教训的「落位/主题/触发格」抽成机器可读影子 [`scripts/design_blocks.json`](scripts/design_blocks.json) / [`scripts/lessons.json`](scripts/lessons.json)（由 `validate_knowledge.py --rebuild` 从 md 重建，md 仍是唯一内容权威源）。四向勾核（声明↔现实、无孤儿、无断链、影子↔md）由 `sd_cli knowledge` / `validate --self` 第 12 项守住——这是 D-062「条目入区却漏三处索引」的机制化防线。**知识分类原则**：大部分知识有直接落点（点/横切，占约 90%），仅少部分高层次开放性知识为基座（`blueprint-methodology` / `high-quality-skill-principle`，约 10%）。
**真实案例**：[`example/fin-information-pipeline.md`](example/fin-information-pipeline.md)（单文件：意图沟通 + 最终施工方案 + 亮点切片，顶部有导航表）。
**闭环背书（E 维证据）**：[`outputs/design-to-publish-loop.md`](outputs/design-to-publish-loop.md)——用本 skill 设计的 `investor-workbench` 已发布到 技能市场（skillId=178556），含「设计→落地→发布」全链路与合理偏离蓝图的修正记录。
---使用说明
# 高质量技能设计指南 像搭积木一样设计高质量技能：四步施工流（概念讨论 → 初步方案 → 深化设计 → 施工蓝图）把模糊想法变成标准化、可复用、可演进的技能设计蓝图，内置质量门、最佳实践与机器校验。 ## 使用 ```text 积木设计：我想做一个每周汇总团队周报并生成简报的技能 ``` 常用命令： ```bash python3 scripts/init_blueprint.py <蓝图目录> # 开始新设计 python3 scripts/check_blueprint.py <蓝图目录> # 质量门与五维评分 python3 scripts/sd_cli.py --help # 全部子命令总览 ``` ## 工作原理 技能按四步施工流推进，每步产物落盘为蓝图文件（支持中断续跑）；深化阶段逐格补全设计条目，出图前过质量门（边界/失败/触发/结构/验证五维体检）并导出 brief.json 交接契约，可选施工通道按蓝图一键渲染技能目录骨架。
支持平台：Qoder · QoderWork · Claude · Codex 等 AI 编程助手