# Skill Designer

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

- Skill: `tashangkd/skill-designer` (Agent Skill, multi-file: 32 files)
- Install (CLI): `npx skillmds@latest add tashangkd/skill-designer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tashangkd/skill-designer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: TashanGKD (https://skillmd.com/u/tashangkd)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tashangkd/skill-designer

---


# 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执行者），需要同时为两层设计。现有「修改规范三问」是代码审查级别的控制，缺失产品级别的完整开发流程。

**验证状态**：🔵 待验证