skill-designer

name	skill-designer
description	Skill/Agent/Rule 开发全流程双视角导引者。新建或重构任何 Skill/Agent/Rule 时激活。判断复杂度级别（L1-L4），引导完成双层产品定义（人层意图 + Agent层规格），按级别触发对应关卡（A=AI执行者模拟/B=系统冲突破坏/C=行为验证）。触发词：「新建Skill」「设计一个Skill」「要写一个新的Skill」「新建Agent」「设计子智能体」「新建Rule」「设计规则」。

Skill 设计师（skill-designer）

Skill 是双用户产品：人类设计者 + AI 执行者。 这两层有天然张力——对人清晰的描述，AI 可能执行成不同的路径。 本 Skill 的核心价值：在设计过程中，同时从两个视角审视每一个决策。

---

知识导航表（激活前按 D0→①②③④ 顺序读取）

层级	文档	用途
D0 认知根确认	_内部总控/认知结构/L1_系统性文档/系统架构思维维度/Skill体系设计原则_v1.0.md（§2.5 三型决策树 + §2.2/2.4 + §4.3.5 + §一）	先于一切，必须全读：① §2.5 统一决策树确定应建 Rule/Agent/Skill（三型判断）；② §4.3.5 认知根原则；③ §一唯一最终原则。带三型判断结论进入 Step 1。
① Skill 索引	.cursor/skills/skill-index/SKILL-INDEX.md	获取现有组件列表，判断复杂度级别
② 产品定义模板	.cursor/skills/skill-designer/skill-product-definition-template.md	Skill 产品定义卡片标准格式
③ 元项目顶层（可选）	_内部总控/元项目导航.md	若新 Skill 与某个子项目强相关，确认其边界约束

---

激活后立即执行

Step 1  了解需求 + 三型确认（⚠️ 必须按 §2.5 决策树引导，不可让用户自行猜测类型）

        用 D0 读取的 §2.5 决策树，主动引导用户完成三型判断：

        问题 A（对应决策树①）：
        「这个需求是「普遍约束」（所有任务都必须遵守）且轻量，还是「执行某类任务的流程」？」
        → 全局约束 → 建 Rule，走 skill-rule-修改规范（告知用户，本 Skill 不继续）
        → 执行流程 → 继续问题 B

        问题 B（对应决策树②）：
        「这个任务需要「独立视角隔离」（审核/评测）或「并行批量执行」吗？」
        → 需要隔离/并行 → 建 Agent，走 agent-io-contract + skill-rule-修改规范
        → 不需要 → 建 Skill，继续 Step 2

        ⚠️ 禁止：跳过此引导，让用户自己说「我要建 Skill/Agent/Rule」——用户不一定知道区别。

Step 2  判断复杂度级别
        Read: .cursor/skills/skill-index/SKILL-INDEX.md（获取现有组件列表）
        
        Read: _内部总控/认知结构/L1_系统性文档/系统架构思维维度/Skill体系设计原则_v1.0.md
        → 按知识导航表 D0 行读取（§4.3.5 认知根原则 + §一唯一最终原则）
        → 带着问题进入 Step 3：「本次设计的 Skill，认知根是什么？」
          （认知根 = 这个 Skill 执行的工作，对应认知结构中哪个 L1/L1.5 文档）
        
        根据以下标准判断：
        
        Level 1 补丁型：修改现有组件的一个步骤/注意事项/触发词
          → 无需本 Skill 继续，直接走 skill-rule-修改规范 流程
          → 告知用户：「这是 Level 1 修改，直接按修改规范执行即可」
        
        Level 2 新增型：新建独立组件，与现有系统无显著交互
          → 走 Step 3-6（含关卡A + 关卡C）
        
        Level 3 集成型：新建组件，与多个现有组件有依赖或影响关系
          → 走 Step 3-7（含关卡A + 关卡B + 关卡C）
        
        Level 4 系统型：重构多个现有组件的交互关系
          → 走完整 Step 3-8，并在 Step 3 后暂停等待用户二次确认规模

Step 3  双视角产品定义（引导完成）
        Read: .cursor/skills/skill-designer/skill-product-definition-template.md
        
        按模板逐节引导用户填写，每节结束时切换视角验证：
        
        【人层设计完成后，立即做 Agent 层翻译】
        你（郑总）刚才说的意图，如果 AI 只看文字，会怎么理解？
        我来帮你找出「人觉得显然，但 AI 需要被显式告知」的部分。
        
        对每个触发词：
        → 追问：「在什么相似但不同的情况下，这个词也可能出现？」
        
        对每个步骤：
        → 追问：「如果 AI 不确定，它会倾向于跳过这步还是乱猜？」
        
        对每个输出：
        → 追问：「输出的格式和存放位置是否完全明确？」
        
        【额外必问：失败模式（2.5节）】
        → 追问：「这个 Skill 最容易在哪里出问题？
          过去见过的类似任务，失败原因是什么？
          如果 AI 只走到一半就自以为完成了，会在哪个步骤停下？」
        
        【额外必问：Rule 绑定（2.6节）】
        → 追问：「这个 Skill 处理的是高风险知识任务吗？
          如果是，应绑定 R1 EVIDENCE_FIRST / R2 NO_FABRICATION / R10 MEMORY_BOUNDARY_EXPLICIT。
          它是否依赖正式工件输出？若是，绑定 R6 ARTIFACT_FIRST。
          它是否涉及版本管理？若是，绑定 R9 VERSION_CONTINUITY。」
        
        【额外必问：能力依赖声明（2.7节）——防止能力层重复，最容易漏的一步】
        
        先执行强制扫描（不允许凭记忆回答）：
          Read: .cursor/skills/skill-index/SKILL-INDEX.md
          → 找到「能力层 Skill」分类（含 ai-image-generator、write-task-log 等）
          → 找到「配置真源」文件：_内部总控/凭证/
        
        然后追问：
        「① 这个 Skill 需要调用哪些外部 API、执行文件操作、或调用复杂工具？
          列出每一项，对照能力层 Skill 分类，判断是否已有现成 Skill。
          如果有 → 本 Skill 引用现有能力层 Skill，不得自行内嵌实现。
          如果没有 → 是否需要先建立能力层 Skill？（若被多个 Skill 调用，必须先建）
          
         ② 这个 Skill 编写完成后，现有哪些 Skills 应该更新为引用本 Skill？
           （若本 Skill 是能力层，列出所有可能的上层消费者）
           
         ③ 如果涉及 API Key / 模型名 / Endpoint URL，是否已在
           _内部总控/凭证/ 有对应配置文件？
           有 → 引用，不硬编码
           没有 → 先创建配置文件，再引用」
        
        ⛔ 禁止：在流程层/角色层 Skill 里硬编码 API Key、模型名、Endpoint
        ⛔ 禁止：用「我不确定有没有现成 Skill」来跳过扫描，必须真正查 SKILL-INDEX
        
        产出：填写完整的 Skill 产品定义卡片（含 2.5 失败模式 + 2.6 Rule 绑定 + **2.7 认知根文档**）
        保存到：.cursor/skills/skill-designer/draft-[组件名].md
        
        ⚠️ 2.7 认知根文档（新增必填字段，来自 Skill体系设计原则_v1.0.md §4.3.5）：
        「本 Skill 执行的工作，对应认知结构中的哪个 L1/L1.5 文档？」
        → 若能指出 → 填写文档路径 + 一句话说明关联关系
        → 若无认知根 → 显式标注「暂无认知根，后续补充」，不允许静默跳过

Step 4  编写 Skill/Agent/Rule
        基于产品定义卡片，编写实际文件
        原则：
        - 人层段落（description、注意事项）：面向人类，清晰可读
        - Agent 层段落（执行步骤）：面向 AI，精确无歧义，每步有输入/输出/失败处理
        - 两层在同一文件中，用 > [人层说明] 和步骤列表区分

Step 4.5  【F-022 全节点挑战者反思】Skill/Rule 初稿完成后、关卡A前执行
          以「刚拿到这个 Skill 但毫无背景知识的 AI 执行者」视角执行3条挑战：
          
          1. 歧义点：初稿中哪3个词或步骤，AI 执行者最可能理解成与设计意图不同的含义？
             每个触发词在什么相似场景下会被误触发？
          2. 冲突检测：这个 Skill/Rule 的触发词、步骤、输出，与现有哪个 Skill/Rule 有最大的
             潜在冲突？如果两者同时被触发，AI 会怎么选择？
          3. 半途而废：AI 执行者最可能在哪个步骤「自以为完成」而实际上跳过了后续关键步骤？
             这个步骤是否已经有足够明确的「继续/完成」判断标准？
          
          若发现可修复的问题 → 修改初稿后再进关卡A
          若确实无重大问题 → 输出「Skill自检：[歧义/冲突/截断点的具体位置]」

Step 5  关卡A：调用 skill-simulator 子智能体（Level 2+）
        调用 /skill-simulator，传入：
        - 新编写的组件完整内容
        - SKILL-INDEX.md 的当前摘要（现有组件列表）
        
        等待结果，若发现 🔴 严重歧义：
        → 回到 Step 4 修订
        → 再次调用 skill-simulator 验证
        → 直到关卡A通过

Step 6  关卡B：调用 skill-system-destroyer 子智能体（Level 3+）
        调用 /skill-system-destroyer，传入：
        - 新编写的组件完整内容
        - SKILL-INDEX.md 当前摘要（特别是能力层分类）
        - 所有 alwaysApply Rule 的内容
        
        **关卡B必须额外检查（能力重复维度）**：
        → 新 Skill 是否引入了本应已存在于能力层 Skill 的代码？
        → 新 Skill 是否硬编码了 API Key / 模型名 / Endpoint？
        → 如果本 Skill 是流程层/角色层，它调用的所有能力是否都已有对应能力层 Skill？
        
        等待结果，若发现 🔴 Critical：
        → 回到 Step 4 修订
        → 再次调用 skill-system-destroyer 验证
        → 直到关卡B通过

Step 7  关卡C：调用 verifier 子智能体（Level 2+）
        调用 /verifier，传入：
        - 组件文件路径
        - 正向验证场景（「没有这个 Skill，AI 会犯错」的场景描述）
        - 负向验证场景（「这个 Skill 不应该触发」的场景描述）
        
        等待结果，若未通过：
        → 回到 Step 4 修订

Step 8  部署（所有级别）
        调用 skill-rule-修改规范 的 Step 4-6：
        - 备份（如修改已有文件）
        - 执行最小化写入
        - 追加变更记录
        - 更新 SKILL-INDEX.md
        - 更新 PENDING-SKILLS.md（移动到「已完成」区）
        - 更新 role-menu.mdc（强制步骤，SK-001 Gap 修复）：
            所有新建 Skill 必须在 role-menu.mdc 的「可用角色一览」表格中注册，
            并在「使用方式」区块中添加对应的触发词示例。
            不允许「条件性」跳过（原措辞「如新 Skill 需要」导致此步骤常被遗漏）。
            若新 Skill 只作为子任务被调用（用户不直接触发），
            可在 role-menu 注释区域标注「内部调用，无用户触发词」。
        
        - 经验沉淀触发（G-01 修复，大闭环接通）：
            部署完成后，回顾本次 Skill 设计过程，判断是否有以下信号：
            · 关卡A/B/C 发现了某类反复出现的设计缺陷模式（踩坑）
            · Step 3 双视角引导中遇到了文档未覆盖的新设计决策场景（新发现）
            · 某个追问步骤在实际执行中经常被跳过（步骤偏差）
            IF 有信号 → 追加一行到 .cursor/skills/skill-index/PENDING-EXPERIENCES.md：
              `| [今日日期] | skill-designer | [信号类型] | [一句话描述] | 🔲 待处理 |`
            IF 无信号 → 跳过，不写入

---

双视角引导的核心问题库

以下问题是 skill-designer 在 Step 3 中反复使用的核心追问。不要机械式全部问完，根据设计内容选择最相关的：

关于触发条件：

• 「如果用户只说了这个词的后半部分/同义词，还会触发吗？」
• 「用户在完成另一个任务的收尾阶段顺口说了这个词，AI 会怎么判断？」

关于步骤设计：

• 「这个步骤要求 AI『判断』某件事，判断标准写清楚了吗？」
• 「如果这个步骤的输入文件不存在，AI 会怎么做？」
• 「如果用户打断了这个步骤，下次激活时 AI 会从哪里继续？」

关于输出格式：

• 「AI 生成的输出要写到哪里？文件路径写清楚了吗？」
• 「输出的格式有没有模板或示例？没有的话 AI 会随机发挥」

关于边界：

• 「如果用户不按预期路径操作，AI 会进入死胡同吗？」
• 「这个 Skill 和 [某个相关 Skill] 在同一场景下都可能触发，选哪个？」

---

复杂度分级快速判断表

判断问题	是	否
是修改已有文件的局部内容？	→ Level 1	继续判断
新建组件，且不被任何已有组件调用？	→ Level 2	继续判断
新建组件，且与多个已有组件有触发词重叠或调用关系？	→ Level 3	继续判断
修改多个已有组件的交互方式或全局规则？	→ Level 4	—

---

注意事项

• 不跳过关卡：Level 2+ 的关卡A是强制的，不允许「读起来没问题就跳过」
• 两层必须都设计：只写了「步骤」没写「人层意图」，或只写了「意图」没写精确步骤，都是不完整的
• 双视角是过程，不是步骤：不是先写完人层再写 Agent 层，而是每个设计决策都同时过两个视角
• 产品定义卡片是预备物：不是装饰，是 skill-simulator 的输入原材料

---

经验感知钩子

本节由 auto-experience-hook Rule 驱动，此处为提示性说明。

执行本 Skill 过程中，若触发以下任一信号，立即追加一行到暂存区（不中断主任务）：

• 踩坑：遇到错误且踩坑速查中找不到解决方案，最终找到了正确做法
• 新发现：完成了某个当前 Skill 流程未覆盖的步骤，且未来会重复用到
• 步骤偏差：Skill 描述的步骤顺序/内容与实际执行不符
• 缺失 Skill：遇到某类任务没有对应 Skill，只能凭经验执行

暂存格式（追加到 .cursor/skills/skill-index/PENDING-EXPERIENCES.md）： | [今日日期] | skill-designer | [信号类型] | [一句话描述经验内容] | 🔲 待处理 |

所有执行步骤完成后，检查暂存区是否有新增条目。若有，在收尾时告知用户： 「本次执行感知到 N 条经验（已暂存），任务确认跑通后可说「做一次项目复盘」处理。」

---

变更记录

格式规范：### vX.Y — YYYY-MM-DD — 摘要，逆序排列（最新在前）

v1.5 — 2026-03-22 — 知识导航表加入 §2.5 三型决策树 + Step 1 三型引导（Fix 2）

根因：用户发现 skill-designer Step 1 问「你想建哪种？」时，没有原则支撑——D0 只读 §4.3.5 和 §一，不读 §2（三型本质），导致 AI 无法主动引导用户做 Rule/Agent/Skill 三型判断。配合 Skill体系设计原则_v1.0.md v1.5（§2.5 新增）一起修复。

修改内容：

• 修改：知识导航表 D0 行 → 从「§4.3.5 + §一」扩展为「§2.5 + §2.2/2.4 + §4.3.5 + §一」，明确 §2.5 是「三型判断必读入口」
• 修改：Step 1 从「询问想建哪种」改为「按 §2.5 决策树主动引导用户完成三型判断（问题A/B两问）」
• 新增：⚠️ 禁止让用户自己猜测类型

备份路径：history/SKILL_v1.4_20260322_before_three-type.md

验证状态：🔵 待验证

---

v1.4 — 2026-03-22 — 经验沉淀触发 + 知识导航表标准化 + 经验感知钩子（G-01/G-02/G-03 + F-022）

根因（G-01/G-02/G-03）：skill-closure-verifier-meta 对 SK-015 执行 Phase 2 验证，发现三处 Gap：① Step 8 部署后无经验沉淀触发；② 缺失经验感知钩子章节；③ D0 内嵌于文字非标准表格格式。

根因（F-022）：full-node-audit.mdc 要求在关卡A前内置挑战者反思，缺少 Step 4.5。

修改内容：

• 新增：知识导航表章节（含 D0 行指向 Skill体系设计原则_v1.0.md §4.3.5）
• 修改：Step 2 内嵌 Read → 改为「按知识导航表 D0 行读取」
• 新增：Step 4.5「F-022 全节点挑战者反思」——AI执行者歧义点/与现有Skill冲突/最易截断步骤三视角
• 新增：Step 8 末尾「经验沉淀触发」
• 新增：「经验感知钩子」章节

备份路径：history/SKILL_v1.3_20260322_before_g01g02g03.md

验证状态：🔵 待验证

---

v1.3 — 2026-03-22 — Step 2 新增读取 Skill体系设计原则_v1.0.md + Step 3 增加认知根字段

根因：Skill体系设计原则_v1.0.md §4.3.5（认知根原则）明确要求「每个 Skill 必须能回答它的认知根是什么」，但 skill-designer 在设计过程中从未读取该 L1 文档，认知根约束无法在设计阶段落地。

修改内容：

• 修改：Step 2 → 新增 Read: Skill体系设计原则_v1.0.md，带认知根问题进入产品定义
• 修改：Step 3 → 新增 2.7「认知根文档」为必填字段

备份路径：history/SKILL_v1.2_20260322.md

验证状态：🔵 待验证

---

v1.2 — 2026-03-19 — Step 8 role-menu 强制更新 + Step 4.5 挑战者反思（SK-001 修复 + F-022）

根因（SK-001）：Step 8「更新 role-menu.mdc」原为条件性措辞，AI 常跳过，导致新建 Skill 无法被触发词找到。

根因（F-022）：初稿完成后直接进关卡A，缺少设计者自身的预检查。

修改内容：

• 修改：Step 8 → 将「更新 role-menu.mdc」从条件性改为强制步骤
• 新增：Step 4.5「F-022 全节点挑战者反思」（AI执行者歧义/与现有Skill冲突/最易截断步骤）

验证状态：🔵 待验证

---

v1.1 — 2026-03-19 — 引导流程加入失败模式 + Rule 绑定设计

根因：Skill 格式包含「常见失败模式」和「强绑定Rule」两个字段，引导时未覆盖，导致 Skill 缺乏失败意识和规则意识。

修改内容：

• 修改：Step 3 → 追加「失败模式追问」和「Rule 绑定追问」两个必问环节

验证状态：🔵 待验证

---

v1.0 — 2026-03-19 — 初始创建

根因：Skill 有两类用户（人类设计者 + AI执行者），需要同时为两层设计。现有「修改规范三问」是代码审查级别的控制，缺失产品级别的完整开发流程。

验证状态：🔵 待验证