---
name: skill-laws
description: 定义所有 Skill 必须遵循的设计法则（Skill Laws），包括 AI 优先、人类中心、即调即用等核心法则。何时使用：当用户创建新 Skill、优化现有 Skill、询问 Skill 设计规范、或需要评估 Skill 质量时。
metadata:
  author: "牙叔教程"
  updated: "2026-02-24 21:30:00"
  version: "1.0.2"
---

# Skill Laws（设计法则）

**最高法则**：所有 Skill 是 AI 的指令集，人类只说自然语言，AI 解析意图、调用 Skill、完成操作。

---

## 🎯 触发映射：用户说 → AI 做

| 用户输入触发词                                                               | AI 执行动作        |
| ---------------------------------------------------------------------------- | ------------------ |
| "创建 skill" / "新建 skill" / "添加 skill" / "初始化 skill"                  | 按【创建模式】执行 |
| "优化 skill" / "skill 有问题" / "检查 skill" / "review skill" / "诊断 skill" | 按【优化模式】执行 |
| "这个 skill 怎么样" / "评估 skill" / "skill 设计得好吗"                      | 按【评估模式】执行 |

---

## 创建模式

**触发**：用户要创建新 Skill

### 执行步骤

| 步骤 | 执行动作          | 具体命令/操作                                                    |
| ---- | ----------------- | ---------------------------------------------------------------- |
| 1    | 确定 skill 目录名 | 使用格式 `skill-{功能名}`，全小写，连字符分隔                    |
| 2    | 创建目录结构      | 运行 `mkdir -p .skills/{skill-name}/{references,scripts}`        |
| 3    | 创建 SKILL.md     | 运行 `Write` 工具创建文件，路径：`.skills/{skill-name}/SKILL.md` |
| 4    | 写入 frontmatter  | 复制下方模板，替换变量：`{skill-name}` `{功能描述}` `{触发条件}` |
| 5    | 添加触发映射表    | 在 frontmatter 后添加"触发映射"区块                              |
| 6    | 添加执行步骤      | 用表格列出步骤、动作、具体命令                                   |
| 7    | 检查核心法则      | 对照【核心法则检查表】逐项验证，全部通过才算完成                 |
| 8    | 创建 references   | 如内容 > 500 行，将详细内容移到 `references/` 目录               |

### Frontmatter 模板

```yaml
---
name: {skill-name}
description: {功能描述}。何时使用：当用户{说/需要/遇到}{触发条件}时。
metadata:
  author: "{作者名}"
  updated: "{YYYY-MM-DD HH:MM:SS}"
  version: "1.0.0"
---
```

### 核心法则检查表（创建时必须全部通过）

| 法则            | 检查标准                                                | 通过？ | 如果不通过                                 |
| --------------- | ------------------------------------------------------- | ------ | ------------------------------------------ |
| ⭐⭐⭐ 人类中心 | 用户只需说自然语言，不需要手动操作文件或运行命令        | ⬜     | 添加 AI 执行步骤，删除用户手动操作         |
| ⭐⭐⭐ AI 优先  | 使用祈使句指令（运行/检查/调用/执行），表格展示决策逻辑 | ⬜     | 将"你可以..."改为"运行..."，长段落改为表格 |
| ⭐⭐⭐ 即调即用 | 顶部有"触发映射"区块，用户输入 → AI 动作一一对应        | ⬜     | 添加触发映射表                             |
| 渐进披露        | 核心内容 < 500 行，详细内容放 `references/`             | ⬜     | 将超过 500 行的内容移到 references         |
| 错误处理        | 包含常见错误场景和处理方式表格                          | ⬜     | 添加错误处理表格                           |

### 错误处理

| 错误场景        | 错误表现                            | 处理方式                                                         |
| --------------- | ----------------------------------- | ---------------------------------------------------------------- |
| 目录已存在      | `mkdir` 报错目录已存在              | 运行 `LS` 检查目录内容，如为空则继续，如有内容则询问用户是否覆盖 |
| 文件写入失败    | `Write` 返回错误                    | 检查路径是否正确，如路径含空格需用引号包裹，重试写入             |
| 变量未替换      | SKILL.md 含 `{skill-name}` 等占位符 | 运行 `SearchReplace` 替换所有占位符为实际值                      |
| 内容超过 500 行 | SKILL.md 行数 > 500                 | 将详细内容移到 `references/` 目录，核心内容保留精简版            |

---

## 优化模式

**触发**：用户要优化现有 Skill 或指出 Skill 有问题

### 执行步骤

| 步骤 | 执行动作       | 具体命令                                                   |
| ---- | -------------- | ---------------------------------------------------------- |
| 1    | 读取目标 Skill | 运行 `Read` 工具读取 `{skill-path}/SKILL.md`               |
| 2    | 逐项检查       | 对照【核心法则检查表】和【文档规范检查表】逐项标记 ✅/❌   |
| 3    | 统计问题       | 统计 ❌ 项数量，按优先级排序（核心法则优先）               |
| 4    | 执行修复       | 运行 `SearchReplace` 或 `Write` 修复问题，参考【正反对照】 |
| 5    | 输出报告       | 按【优化报告模板】输出结果                                 |

### 文档规范检查表

| 检查项      | 符合标准                              | 当前状态 | 修复命令                        |
| ----------- | ------------------------------------- | -------- | ------------------------------- |
| description | 包含"何时使用：当用户说/需要/遇到..." | ⬜       | `SearchReplace` 添加触发条件    |
| 指令语气    | 使用祈使句（运行/检查/调用/执行）     | ⬜       | `SearchReplace` "你可以"→"运行" |
| 决策逻辑    | 复杂任务使用表格展示条件分支          | ⬜       | 将长段落改为条件表格            |
| 输出格式    | 明确说明执行后输出什么、如何展示      | ⬜       | 添加输出示例代码块              |
| 错误处理    | 包含错误场景和处理方式表格            | ⬜       | 添加错误处理表格                |
| 文件引用    | 使用 Markdown 链接格式 `[名](路径)`   | ⬜       | `SearchReplace` 改为可点击链接  |
| 渐进披露    | 核心指令 < 500 行                     | ⬜       | 将详细内容移到 `references/`    |
| 触发映射    | 顶部有"用户说 → AI 做"映射表          | ⬜       | 添加触发映射区块                |

### 正反对照（快速修复参考）

| ❌ 错误示例          | ✅ 正确示例                   | 修复操作                     |
| -------------------- | ----------------------------- | ---------------------------- |
| "你可以运行..."      | "运行..."                     | `SearchReplace` 删除"你可以" |
| "建议检查..."        | "检查..."                     | `SearchReplace` 删除"建议"   |
| "如果需要可以..."    | "如果 X 则执行 Y"             | 改为条件表格                 |
| "请参考文档了解详情" | "参考 [文件名](路径) 执行..." | `SearchReplace` 添加链接     |
| 长段落描述           | 表格/列表 + 具体命令          | 重构为表格格式               |
| "确保 xxx"           | "运行 `命令` 检查 xxx"        | 添加具体检查命令             |

### 错误处理

| 错误场景         | 错误表现               | 处理方式                                                            |
| ---------------- | ---------------------- | ------------------------------------------------------------------- |
| 文件不存在       | `Read` 报错文件不存在  | 检查路径是否正确，如 skill-name 拼写错误，询问用户正确名称          |
| 无问题可优化     | 所有检查项都是 ✅      | 输出"该 Skill 已符合所有法则，无需优化"，按【评估模式】输出评估报告 |
| 修复后引入新问题 | 修复 A 问题导致 B 问题 | 回滚更改，分步修复，每步修复后重新检查                              |
| 用户不认可修复   | 用户说"不要改这个"     | 记录用户反馈，跳过该项，继续优化其他项                              |

### 优化报告模板

```
## 优化报告：{skill-name}

**评分**：{通过数}/13 项符合（核心法则 5 项 + 文档规范 8 项）

### 主要问题

1. {问题描述}
   - 修复操作：{具体操作}
   - 使用工具：{Read/SearchReplace/Write}

2. {问题描述}
   - 修复操作：{具体操作}
   - 使用工具：{Read/SearchReplace/Write}

### 已修复

- {修复内容}
- {修复内容}

### 后续建议

- {建议内容}
```

---

## 评估模式

**触发**：用户问 skill 设计得怎么样或要求评估 Skill 质量

### 执行步骤

| 步骤 | 执行动作       | 具体命令                                     |
| ---- | -------------- | -------------------------------------------- |
| 1    | 读取目标 Skill | 运行 `Read` 工具读取 `{skill-path}/SKILL.md` |
| 2    | 核心法则评估   | 检查是否符合【核心法则检查表】5 条法则       |
| 3    | 文档规范评估   | 检查是否符合【文档规范检查表】8 项规范       |
| 4    | 计算评分       | 统计符合项数，确定等级                       |
| 5    | 输出评估       | 按【评估报告模板】输出结果                   |

### 评估标准

| 等级      | 分数     | 说明                            |
| --------- | -------- | ------------------------------- |
| 🏆 完美   | 13/13    | 完全符合 Skill Laws，可直接使用 |
| ✅ 优秀   | 11-12/13 | 基本符合，少量细节可优化        |
| ⚠️ 良好   | 8-10/13  | 有明显改进空间                  |
| ❌ 需优化 | < 8/13   | 需要大幅重构                    |

### 错误处理

| 错误场景      | 错误表现                           | 处理方式                                                  |
| ------------- | ---------------------------------- | --------------------------------------------------------- |
| 文件不存在    | `Read` 报错文件不存在              | 询问用户正确的 skill 名称或路径                           |
| 非 Skill 文件 | 文件不含 SKILL.md 结构             | 输出"该文件不是 Skill，无法评估"，说明 Skill 文件结构要求 |
| 评分边界      | 得分恰好在边界（如 10 分或 12 分） | 向下取整，按较低等级评定，鼓励继续优化                    |

### 评估报告模板

```
## Skill 质量评估：{skill-name}

### 总体评分

**符合度**：{X}/13 项 ✅

**等级**：{🏆/✅/⚠️/❌}

### 核心问题（如等级不为 🏆）

- {问题描述} → {改进建议}
- {问题描述} → {改进建议}

### 建议操作

- 如等级为 ❌ 需优化：按【优化模式】执行全面优化
- 如等级为 ⚠️ 良好：针对核心问题逐一修复
- 如等级为 ✅ 优秀：微调细节即可达到 🏆 完美
```