diff --git a/docs/design/12-l2-l3-skill-system.md b/docs/design/12-l2-l3-skill-system.md
new file mode 100644
index 0000000..f0d2e31
--- /dev/null
+++ b/docs/design/12-l2-l3-skill-system.md
@@ -0,0 +1,595 @@
+# #12 L2 瘦身 + L3 Skill 体系详细设计
+
+> 版本: v1.0  
+> 日期: 2026-06-04  
+> 作者: 庞统（副军师）  
+> 状态: **待确认**  
+> 前置: #11 上下文四层架构重新定位方案（已完成）
+
+---
+
+## 一、总体架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ L0 铁律（OpenClaw 注入，不改）                            │
+│ gate-rules + delegation-rule                             │
+├─────────────────────────────────────────────────────────┤
+│ L1 认知操作系统（每次必看）                                │
+│ SOUL.md / AGENTS / TOOLS / IDENTITY / USER               │
+│ ← 含"执行任务前，先读 skill-router 选取最合适的 Skill"     │
+├─────────────────────────────────────────────────────────┤
+│ L2 引擎注入（BootstrapBuilder，spawn 时注入）             │
+│                                                          │
+│ ① 任务上下文（task_id/title/desc/must_haves）~150 tokens │
+│ ② 前序产出（depends_on 摘要）              ~50 tokens    │
+│ ③ A 类操作规范全文（按角色精确注入）       ~300 tokens    │
+│ ④ 硬约束（通用流转规则）                   ~100 tokens   │
+│                                          总计: ~600 tokens│
+├─────────────────────────────────────────────────────────┤
+│ L3 被动参考（OpenClaw extraDirs，Agent 按需 read）        │
+│                                                          │
+│ skill-router（路由速查表）                                │
+│ A 类: blackboard-executor/reviewer/...（引擎注入时全文）   │
+│ B 类: metacognition/scope-reduction/...（Description触发）│
+│ C 类: review-quality（Description触发）                   │
+│ D 类: trial-and-error/proven-practices/...（Description）│
+│ 现有: 42 个 Skill 保留不动                                │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 二、L2 BootstrapBuilder 新版设计
+
+### 2.1 输出结构
+
+```markdown
+# 任务指令
+
+## 任务上下文
+任务ID: {task_id}
+标题: {title}
+描述: {description}
+必须完成: {must_haves}
+风险级别: {risk_level}
+
+## 前序产出
+{depends_on_summary}
+
+## 角色操作规范
+{role_skill_content}
+
+## 流转约束
+- 产出物必须有实际内容，不能空提交
+- 失败标 failed 并写明原因
+{role_specific_constraints}
+```
+
+### 2.2 角色操作规范注入逻辑
+
+```python
+# BootstrapBuilder.build() 核心逻辑
+
+ROLE_SKILL_MAP = {
+    "executor": "blackboard-executor",
+    "reviewer": "blackboard-reviewer",
+    "reviewer-simayi": "blackboard-reviewer-simayi",
+    "reviewer-pangtong": "blackboard-reviewer-pangtong",
+    "planner": "blackboard-planner",
+    "claim": "blackboard-claim",
+}
+
+def build(self, role, task_context, depends_on_outputs):
+    parts = []
+    
+    # ① 任务上下文
+    parts.append(self._format_task_context(task_context))
+    
+    # ② 前序产出（有依赖时）
+    if depends_on_outputs:
+        parts.append(self._format_depends_on(depends_on_outputs))
+    
+    # ③ A 类操作规范全文（按角色精确注入）
+    skill_name = ROLE_SKILL_MAP.get(role, "blackboard-executor")
+    skill_content = self._read_skill(skill_name)
+    parts.append(f"## 角色操作规范\n{skill_content}")
+    
+    # ④ 硬约束
+    parts.append(self._format_constraints(role))
+    
+    return "\n\n".join(parts)
+
+def _read_skill(self, skill_name):
+    """读取 L3 Skill 全文注入 L2"""
+    skill_path = SKILLS_DIR / skill_name / "SKILL.md"
+    content = skill_path.read_text()
+    # 去掉 YAML frontmatter（已在 description 中可见）
+    return strip_frontmatter(content)
+
+def _format_constraints(self, role):
+    """按角色附加额外约束"""
+    COMMON = "产出物必须有实际内容，不能空提交。失败标 failed 并写明原因。"
+    if role == "executor":
+        return f"- handoff comment ≥ 50 字符：写决策、踩坑、建议\n- 需求不清时 @pangtong-fujunshi 提问\n{COMMON}"
+    elif role == "reviewer":
+        return f"- verdict: approved / rejected / needs_revision\n- rejected 必须给具体改进方向\n{COMMON}"
+    elif role == "planner":
+        return f"- 需求不清在黑板 comment 提问\n- 每个子任务有明确终态\n{COMMON}"
+    else:
+        return COMMON
+```
+
+### 2.3 与旧版对比
+
+| 维度 | 旧版 BootstrapBuilder | 新版 |
+|------|----------------------|------|
+| 操作规范来源 | `prompt_templates/` 目录读文件 | 读 L3 Skill 文件 |
+| 注入内容 | 角色模板全文（含操作规范+经验） | 纯数据 + Skill 全文 + 硬约束 |
+| 硬约束位置 | 散在模板里 | 统一在"流转约束"段 |
+| token 量 | ~1200 | ~600 |
+| 扩展性 | 改 prompt_templates/ | 改 L3 Skill 文件 |
+
+### 2.4 需要改的代码文件
+
+| 文件 | 改动 |
+|------|------|
+| `src/daemon/bootstrap.py` | 重写 `BootstrapBuilder`：去掉 template_dir，改为读 Skill 文件 |
+| `src/daemon/spawner.py` | 适配新 `BootstrapBuilder` 接口：传入 role + task_context |
+| `prompt_templates/*.md`（5个） | 迁移到 L3 Skill 后删除 |
+
+---
+
+## 三、L3 Skill 清单
+
+### 3.1 A 类：操作规范型（引擎直接注入全文）
+
+从现有 `prompt_templates/` 迁移，加 YAML frontmatter header，砍掉和 L2 硬约束重复的部分。
+
+#### blackboard-executor
+
+```yaml
+---
+name: blackboard-executor
+description: |
+  黑板执行者操作规范。引擎 spawn executor 时注入全文。
+  包含对齐全局→确认设计→实现→交接完整流程。
+  触发词：执行、executor、产出、working、实现。
+  不触发：review、审查、规划、planning。
+---
+```
+
+**内容要点**（从 executor.md 迁移）：
+1. 对齐：读黑板全局计划 → 确认设计文档位置 → 读设计
+2. 执行：确认需求无歧义 → 实现 → 复杂任务参考 `plan-act-verify`
+3. 交接：handoff 写决策/踩坑/建议 → 产出写入黑板 → 标 review
+4. 异常：需求不清 @pangtong → 技术阻塞 @jiangwei → 发现降级参考 `scope-reduction-detection`
+
+**Related Skills**: `plan-act-verify`, `scope-reduction-detection`, `trial-and-error-patterns`
+
+#### blackboard-reviewer
+
+```yaml
+---
+name: blackboard-reviewer
+description: |
+  黑板审查者通用操作规范。引擎 spawn reviewer 时注入全文。
+  包含审查→verdict→交接完整流程。
+  触发词：review、审查、评审、verdict、approved、rejected。
+  不触发：执行、编码、规划。
+---
+```
+
+**内容要点**（从 reviewer.md 迁移）：
+1. 审查：读黑板全局计划 → 读设计文档 → 读产出 → 对齐检查
+2. Verdict：approved/rejected/needs_revision，rejected 必须给改进方向
+3. Rebuttal：被反驳时重新审视，2轮不一致 → @pangtong 仲裁
+4. 不确定时参考 `metacognition`
+
+**Related Skills**: `review-quality`, `metacognition`, `self-reflection-wisdom`
+
+#### blackboard-reviewer-simayi
+
+```yaml
+---
+name: blackboard-reviewer-simayi
+description: |
+  司马懿特化审查操作规范。引擎 spawn reviewer-simayi 时注入全文。
+  司马懿的审查思维：鹰视狼顾看正文、先扫一致性再评内容、正反两面挑战。
+  触发词：司马懿审查、挑战者、魔鬼代言人、simayi review。
+  不触发：执行、编码、规划。
+---
+```
+
+**内容要点**（从 review_simayi.md 迁移 + 蒸馏教训）：
+1. 审查前：先理解目标和设计者意图
+2. 一致性扫描：先扫内部一致性，再评内容。看到"已修改"→ grep 确认
+3. 证据驱动：每条意见附文件:行号 + 当前值 + 建议值
+4. 挑战者角色：正反两面，找"哪里假设了但没说"
+5. 不确定时参考 `metacognition`，审查标准参考 `review-quality`
+
+**Related Skills**: `review-quality`, `metacognition`, `self-reflection-wisdom`
+
+#### blackboard-reviewer-pangtong
+
+```yaml
+---
+name: blackboard-reviewer-pangtong
+description: |
+  庞统特化审查操作规范。引擎 spawn reviewer-pangtong 时注入全文。
+  庞统的审查思维：方向一致性 > 内容质量 > 细节打磨。
+  触发词：庞统审查、方向检查、目标漂移、仲裁。
+  不触发：执行、编码。
+---
+```
+
+**内容要点**（从 review_pangtong.md 迁移）：
+1. 方向一致性：改动是否偏离原始目标？
+2. 拒绝降级：实现和目标不一致时指出差距
+3. 仲裁：2 轮 rebuttal 不一致时做最终裁决
+
+**Related Skills**: `scope-reduction-detection`, `review-quality`
+
+#### blackboard-planner
+
+```yaml
+---
+name: blackboard-planner
+description: |
+  黑板规划者操作规范。引擎 spawn planner 时注入全文。
+  包含需求澄清→拆解→子任务创建完整流程。
+  触发词：规划、拆解、子任务、planning、需求分析。
+  不触发：执行、review、编码。
+---
+```
+
+**内容要点**（从 planner.md 迁移）：
+1. 需求澄清：苏格拉底式追问，1-2 轮定位
+2. 拆解：每个子任务有明确终态、可验证
+3. 分配：按角色专长分配
+4. 不确定时参考 `team-collaboration`
+
+**Related Skills**: `team-collaboration`, `metacognition`
+
+#### blackboard-claim
+
+```yaml
+---
+name: blackboard-claim
+description: |
+  黑板广播认领操作规范。引擎 spawn claim 时注入全文。
+  收到任务广播时使用，判断是否认领。
+  触发词：认领、claim、broadcast、广播、观察。
+  不触发：执行、review、规划。
+---
+```
+
+**内容要点**（从 spawner.py `_build_claim_prompt` 提取）：
+1. 读广播内容 → 判断是否属于自己专长
+2. 属于 → 认领，不属于 → 跳过
+3. 认领时确认：目标明确、有能力完成、时间允许
+
+### 3.2 B 类：方法论型（Description 自主触发）
+
+#### metacognition
+
+```yaml
+---
+name: metacognition
+description: |
+  元认知评估。对当前判断不确定时使用。评估置信度 → 决定是否升级。
+  触发词：不确定、犹豫、可能、也许、置信度、没把握。
+  不触发：明确判断、高置信度。
+---
+```
+
+**内容**：
+1. 置信度自评：0-100%，低于 70% 标注"待验证"
+2. 不确定时升级：@pangtong-fujunshi 或在黑板 comment 提问
+3. 不编造——不确定的标明是假设
+
+#### scope-reduction-detection
+
+```yaml
+---
+name: scope-reduction-detection
+description: |
+  反静默降级检查。发现自己可能在砍需求/跳步骤/减少交付时使用。
+  触发词：降级、砍需求、跳步骤、简化、减少、来不及。
+  不触发：正常执行。
+---
+```
+
+**内容**：
+1. 检查清单：我在砍需求吗？跳步骤了吗？减少交付了吗？
+2. 降级必须显式声明：在黑板 comment 写明降级内容和原因
+3. 用户/庞统确认后才降级
+
+#### plan-approval-workflow
+
+```yaml
+---
+name: plan-approval-workflow
+description: |
+  复杂任务审批流程。多文件/多模块任务先计划后执行，等异议窗口。
+  触发词：审批、异议、计划确认、多文件、多模块。
+  不触发：单文件小改动。
+---
+```
+
+**内容**：
+1. 复杂任务先在 comment 写计划
+2. 5 分钟无异议再执行（或 @reviewer 确认）
+3. 异议出现 → 修改计划 → 重新等确认
+
+#### team-collaboration
+
+```yaml
+---
+name: team-collaboration
+description: |
+  团队协作规则（Boids 模型）。规划/协调任务时参考。
+  触发词：协作、冲突、边界、团队、分工。
+  不触发：独立执行。
+---
+```
+
+**内容**：Boids 四规则
+1. Separation：不重复别人正在做的事
+2. Alignment：和全局目标对齐
+3. Cohesion：产出物互相衔接
+4. Boundary：只认领自己专长范围内的任务
+
+### 3.3 C 类：审查协议型
+
+#### review-quality
+
+```yaml
+---
+name: review-quality
+description: |
+  审查质量标准。审查/评审时参考的四个质量维度。
+  触发词：审查标准、评审维度、review quality、验收标准。
+  不触发：执行、编码。
+---
+```
+
+**内容**（从 wiki-vault 蒸馏）：
+1. 正确性：逻辑是否正确，边界是否覆盖
+2. 一致性：设计↔实现是否对齐，不同位置描述是否一致
+3. 完整性：是否有遗漏，异常处理是否到位
+4. 可维护性：代码风格、命名、注释
+
+### 3.4 D 类：经验型
+
+#### trial-and-error-patterns
+
+```yaml
+---
+name: trial-and-error-patterns
+description: |
+  常见试错模式。从团队历史教训提炼的 6 个高频错误模式。
+  触发词：踩坑、失败、错误、教训、经验。
+  不触发：正常执行、成功经验。
+---
+```
+
+**内容**（从 wiki-vault practices + JSONL 分析提炼）：
+1. 前端开发完先 E2E 再评审
+2. 跨模块接口必须文档化+测试验证
+3. 测试和开发必须分离
+4. 关键阻塞修根因不手动改 DB
+5. 改了源码忘同步安装目录
+6. 通知渠道必须有冒烟测试
+
+#### proven-practices
+
+```yaml
+---
+name: proven-practices
+description: |
+  成功最佳实践。从 wiki-vault practices 提炼的已验证做法。
+  触发词：最佳实践、成功经验、proven、做法。
+  不触发：踩坑、失败。
+---
+```
+
+**内容**（从 wiki-vault practices 提炼）：
+1. 先两层蒸馏再扩展
+2. Experience → Skill 延迟转化
+3. Skill 自包含原则
+4. 检查点驱动的流程控制
+5. 增量更新而非全量重建
+6. 迭代上限防止无限循环
+
+#### self-reflection-wisdom
+
+```yaml
+---
+name: self-reflection-wisdom
+description: |
+  自我反思模式。审查/复盘时参考的反思方法论。
+  触发词：反思、复盘、教训、改进、自评。
+  不触发：正常执行。
+---
+```
+
+**内容**（从 wiki-vault practices + 蒸馏提炼）：
+1. HOW not WHAT：提炼思维方式而非知识内容
+2. 诚实边界：每个产出声明局限性
+3. 矛盾是特征不是 Bug：记录不调和的矛盾
+
+---
+
+## 四、skill-router 设计
+
+### 4.1 定位
+
+skill-router 是一个 L3 Skill，内容就是一张路由速查表。Agent 从 L1 决策模式得知"执行任务前先读 skill-router"，到 skill-router 中查找当前场景对应的 Skill。
+
+### 4.2 内容结构
+
+```markdown
+---
+name: skill-router
+description: |
+  Skill 路由速查表。Agent 执行任务前查找当前场景该用什么 Skill。
+  触发词：不确定用什么 skill、找 skill、场景匹配、skill 路由。
+  不触发：已知该用什么 skill 的场景。
+---
+
+# Skill Router Map
+
+## 操作规范（引擎按角色自动注入）
+
+| 角色 | Skill | 内容 |
+|------|-------|------|
+| executor | `blackboard-executor` | 对齐→实现→交接 |
+| reviewer（通用） | `blackboard-reviewer` | 审查→verdict |
+| reviewer（司马懿） | `blackboard-reviewer-simayi` | 挑战者审查 |
+| reviewer（庞统） | `blackboard-reviewer-pangtong` | 方向审查 |
+| planner | `blackboard-planner` | 需求→子任务 |
+| 认领者 | `blackboard-claim` | 广播→认领 |
+
+## 方法论（按场景查找）
+
+| 你在做什么 | 推荐Skill | 关键词 |
+|-----------|----------|--------|
+| 复杂任务（多文件/多模块） | `plan-act-verify` | 复杂、多文件、多步骤 |
+| 发现自己在砍需求/跳步骤 | `scope-reduction-detection` | 降级、砍需求、跳步骤 |
+| 对判断不确定（置信度 < 70%） | `metacognition` | 不确定、犹豫、没把握 |
+| 复杂计划需要审批 | `plan-approval-workflow` | 审批、异议、计划确认 |
+| 团队协作规则 | `team-collaboration` | 协作、冲突、分工边界 |
+
+## 经验参考（遇到问题时查找）
+
+| 你遇到什么 | 推荐Skill | 关键词 |
+|-----------|----------|--------|
+| 踩坑了 | `trial-and-error-patterns` | 踩坑、失败、错误 |
+| 想参考成功做法 | `proven-practices` | 最佳实践、成功经验 |
+| 需要自我反思 | `self-reflection-wisdom` | 反思、复盘、教训 |
+| 审查质量标准 | `review-quality` | 审查标准、评审维度 |
+```
+
+### 4.3 维护方式
+
+skill-router 由人工维护（庞统负责）。更新时机：
+
+| 事件 | 操作 |
+|------|------|
+| 新增 Skill | 在对应分类（操作规范/方法论/经验）表格中加一行 |
+| 删除 Skill | 从表格中移除对应行 |
+| 修改 Skill 定位 | 更新 Skill 名称/描述/关键词 |
+
+**更新流程**：
+1. 创建/修改 L3 Skill 文件（加/改/删 SKILL.md）
+2. 同步更新 skill-router 表格
+3. 重启 OpenClaw 生效
+
+---
+
+## 五、Skill 生命周期管理
+
+### 5.1 Skill 目录结构
+
+```
+~/.sanguo_projects/sanguo_mozi/skills/
+├── skill-router/SKILL.md                    # 路由速查表
+├── blackboard-executor/SKILL.md             # A1
+├── blackboard-reviewer/SKILL.md             # A2
+├── blackboard-reviewer-simayi/SKILL.md      # A3
+├── blackboard-reviewer-pangtong/SKILL.md    # A4
+├── blackboard-planner/SKILL.md              # A5
+├── blackboard-claim/SKILL.md                # A6
+├── metacognition/SKILL.md                   # B7
+├── scope-reduction-detection/SKILL.md       # B8
+├── plan-approval-workflow/SKILL.md          # B9
+├── team-collaboration/SKILL.md              # B10
+├── review-quality/SKILL.md                  # C11
+├── trial-and-error-patterns/SKILL.md        # D12
+├── proven-practices/SKILL.md                # D13
+├── self-reflection-wisdom/SKILL.md          # D14
+├── ...（42 个现有 Skill 保留不动）
+```
+
+### 5.2 Skill 新增流程
+
+```
+1. 确定分类：A(操作规范)/B(方法论)/C(审查协议)/D(经验)
+2. 创建目录：~/.sanguo_projects/sanguo_mozi/skills/<skill-name>/
+3. 编写 SKILL.md：
+   - YAML frontmatter（name + description + 触发词）
+   - 正文（How-to 内容）
+   - Related Skills 串联
+4. 更新 skill-router SKILL.md：在对应分类表格中加一行
+5. 如果是 A 类（引擎注入）：同步改 BootstrapBuilder.ROLE_SKILL_MAP
+6. 重启 OpenClaw 生效
+```
+
+### 5.3 Skill 修改流程
+
+```
+1. 修改 SKILL.md 内容
+2. 如果改了 name/description/定位：同步更新 skill-router
+3. 如果是 A 类且改了文件名：同步改 BootstrapBuilder.ROLE_SKILL_MAP
+4. 重启 OpenClaw 生效
+```
+
+### 5.4 Skill 删除流程
+
+```
+1. 从 skill-router 中移除对应行
+2. 如果是 A 类：从 BootstrapBuilder.ROLE_SKILL_MAP 中移除
+3. 删除 Skill 目录
+4. 重启 OpenClaw 生效
+```
+
+### 5.5 Skill Description 编写规范
+
+每个 Skill 的 YAML frontmatter description 必须包含：
+
+```yaml
+---
+name: <skill-name>
+description: |
+  <一句话定位>。<触发场景>。<核心能力>。
+  触发词：<5-8个关键词，逗号分隔>。
+  不触发：<排除词，逗号分隔>。
+---
+```
+
+**质量标准**（来自优秀实践）：
+- Description ≤ 200 字
+- 触发词 5-8 个，覆盖直接型+隐含型+动作型
+- 不触发词明确排除易混淆场景
+- SKILL.md 全文 ≤ 5000 tokens（A 类可放宽，因为引擎注入不受 Description 触发限制）
+
+---
+
+## 六、实施计划
+
+| Step | 内容 | 产出 | 预计工作量 |
+|------|------|------|-----------|
+| 1 | 创建 skill-router Skill | 1 个 SKILL.md | 小 |
+| 2 | 创建 A 类 6 个操作规范 Skill（从 prompt_templates 迁移） | 6 个 SKILL.md | 中 |
+| 3 | 创建 B 类 4 个方法论 Skill | 4 个 SKILL.md | 中 |
+| 4 | 创建 C 类 1 个审查协议 Skill | 1 个 SKILL.md | 小 |
+| 5 | 创建 D 类 3 个经验型 Skill | 3 个 SKILL.md | 中 |
+| 6 | 改 BootstrapBuilder（瘦身 + 读 Skill 文件） | bootstrap.py | 中 |
+| 7 | 改 spawner.py（适配新接口） | spawner.py | 小 |
+| 8 | 清理旧 prompt_templates（迁移后删除） | 删除 5 个 .md | 小 |
+| 9 | 更新设计文档 §11（同步 L1 改动） | 11-context-layers-redesign.md | 小 |
+| 10 | E2E 验证 | 测试通过 | 中 |
+
+**依赖关系**：Step 1-5 可并行 → Step 6-8 依赖 Step 2 → Step 10 依赖全部
+
+---
+
+## 七、风险与缓解
+
+| 风险 | 缓解 |
+|------|------|
+| A 类 Skill 全文注入 token 超标 | 每个 Skill ≤ 500 tokens，6 个共 3000，可接受。实际只注入 1 个 |
+| B/C/D 类 Skill Description 触发不准 | 有 L1 "先读 skill-router"兜底，不纯靠 Description |
+| 迁移 prompt_templates 遗漏内容 | 旧文件保留到 Step 10 E2E 验证通过后再删 |
+| 经验型 Skill 数据源质量 | 从 wiki-vault 已有 practices 提炼，不编造 |