steelan9199/skill-laws

Skill Laws（设计法则）

核心理念：Skill 是给 AI 用的，文档是让人帮 AI 写的。

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

---

功能概述

本 Skill 是 Skill 设计的通用法则框架，用于规范所有 Skill 的创建、优化与评估流程。它定义了"用户说、AI 做"和"AI 优先"两大核心法则，并提供可操作的执行步骤、统一检查表与报告模板，确保 Skill 文档对 AI 友好、对人类可读。

环境说明

• 本 Skill 为通用框架，适用于任何类型 Skill 的创建、优化与评估，不绑定特定技术栈或目录结构。
• 执行时以目标 Skill 的SKILL.md 为核心操作对象，工具调用以目标 Skill 所在路径为上下文。
• 下文出现的 {skill-name}、{skill-path} 等变量，均需根据实际目标 Skill 替换为真实值。
• 不同软件的 Skill 存放目录不同（如 .skills/、.trae/skills/ 等），创建时以当前环境的实际路径为准。

$SKILL_DIR（Skill 目录变量）

$SKILL_DIR 指当前 Skill 所在的绝对目录，即 SKILL.md 文件所在的文件夹。若 Skill 包含脚本/代码，必须在【环境说明】中定义此变量和脚本执行路径。详见 skill-dir-guide.md。

---

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

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

---

统一检查表

创建、优化、评估三种模式共用此表。核心法则（⭐⭐⭐）为必要条件，文档规范为充分条件。

| # | 类别 | 检查项 | 符合标准 | | --- | --------------- | ------------ | ------------------------------------------------------------------------------------------------------- | | 1 | ⭐⭐⭐ 核心法则 | 用户说，AI做 | 用户说自然语言，AI 执行所有操作（不包含需要用户手动操作文件或运行命令的步骤） | | 2 | ⭐⭐⭐ 核心法则 | AI 优先 | 使用祈使句指令（运行/检查/调用/执行），表格展示决策逻辑 | | 3 | 文档规范 | description | 包含"何时使用：当用户说/需要/遇到..." | | 4 | 文档规范 | 功能概述 | 正文包含【功能概述】段落，说明核心功能与适用范围 | | 5 | 文档规范 | 环境说明 | 包含【环境说明】段落。若含脚本/代码，必须包含 $SKILL_DIR 和脚本路径定义；若无脚本，描述运行上下文即可 | | 6 | 文档规范 | 指令语气 | 使用祈使句（运行/检查/调用/执行），避免"你可以"、"建议"等弱化语气 | | 7 | 文档规范 | 决策逻辑 | 复杂任务使用表格展示条件分支 | | 8 | 文档规范 | 输出格式 | 明确说明执行后输出什么、如何展示 | | 9 | 文档规范 | 错误处理 | 包含错误场景和处理方式表格 | | 10 | 文档规范 | 文件引用 | 使用 Markdown 链接格式 [名](路径) | | 11 | 文档规范 | 渐进披露 | 核心指令 < 500 行；按功能模块拆分到不同文件，按需加载；通用信息放主文件，不重复写在子文档 |

不通过时的修复操作

| # | 修复操作 | | --- | ---------------------------------------------------------- | | 1 | 添加 AI 执行步骤，删除用户手动操作 | | 2 | 将"你可以..."改为"运行..."，长段落改为表格 | | 3 | SearchReplace 添加"何时使用：当用户..."触发条件 | | 4 | Write 或 SearchReplace 添加【功能概述】段落 | | 5 | 按是否含脚本补充 $SKILL_DIR 和脚本路径，或描述运行上下文 | | 6 | SearchReplace 将"你可以"/"建议"改为祈使句 | | 7 | 将长段落改为条件表格 | | 8 | 添加输出示例代码块或输出步骤 | | 9 | 添加错误场景和处理方式表格 | | 10 | SearchReplace 改为可点击链接格式 | | 11 | 将详细内容移到 references/，按功能拆分为独立文件 |

---

创建模式

触发：用户要创建新 Skill

执行步骤

| 步骤 | 执行动作 | 具体命令/操作 | | ---- | ----------------- | --------------------------------------------------------------------------------------------- | | 1 | 确定 skill 目录名 | 使用格式 skill-{功能名}，全小写，连字符分隔 | | 2 | 创建目录结构 | 运行 mkdir 创建 {skill-path}/{skill-name}/{references,scripts} | | 3 | 创建 SKILL.md | 运行 Write 工具创建文件，路径：{skill-path}/{skill-name}/SKILL.md | | 4 | 写入 frontmatter | 复制下方模板，替换变量：{skill-name} {功能描述} {触发条件} | | 5 | 添加功能概述 | 在正文开头添加【功能概述】段落，说明 Skill 的核心功能与适用范围 | | 6 | 添加环境说明 | 若 Skill 包含脚本/代码，定义 $SKILL_DIR 和脚本执行路径；若 Skill 无代码，描述运行上下文即可 | | 7 | 添加执行步骤 | 用表格列出步骤、动作、具体命令 | | 8 | 添加输出格式 | 明确说明每步执行后输出什么、最终输出什么格式 | | 9 | 检查统一检查表 | 对照【统一检查表】逐项验证，全部通过才算完成 | | 10 | 创建 references | 如内容 > 500 行，将详细内容移到 references/ 目录 |

Frontmatter 模板

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

错误处理

| 错误场景 | 错误表现 | 处理方式 | | ---------- | ----------------------------------- | ---------------------------------------------------------------- | | 目录已存在 | mkdir 报错目录已存在 | 运行 LS 检查目录内容，如为空则继续，如有内容则询问用户是否覆盖 | | 变量未替换 | SKILL.md 含 {skill-name} 等占位符 | 运行 SearchReplace 替换所有占位符为实际值 |

---

优化模式

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

执行步骤

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

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

| ❌ 错误示例 | ✅ 正确示例 | | -------------------- | ------------------------------- | | "你可以运行..." | "运行..." | | "建议检查..." | "检查..." | | "如果需要可以..." | 改为条件表格："如果 X 则执行 Y" | | "请参考文档了解详情" | "参考 文件名 执行..." | | "确保 xxx" | "运行 命令 检查 xxx" | | 长段落描述 | 表格/列表 + 具体命令 |

错误处理

| 错误场景 | 错误表现 | 处理方式 | | ---------------- | ---------------------- | -------------------------------------- | | 无问题可优化 | 所有检查项都是 ✅ | 按【评估模式】输出评估报告 | | 修复后引入新问题 | 修复 A 问题导致 B 问题 | 回滚更改，分步修复，每步修复后重新检查 | | 用户不认可修复 | 用户说"不要改这个" | 记录用户反馈，跳过该项，继续优化其他项 |

优化报告模板

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

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

### 主要问题

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

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

### 已修复

- {修复内容}

### 后续建议

- {建议内容}

---

评估模式

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

执行步骤

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

评估标准

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

错误处理

| 错误场景 | 错误表现 | 处理方式 | | ------------- | -------------------------------- | --------------------------------------------------------- | | 非 Skill 文件 | 文件不含 SKILL.md 结构 | 输出"该文件不是 Skill，无法评估"，说明 Skill 文件结构要求 | | 评分边界 | 得分恰好在边界（如 5 分或 8 分） | 向下取整，按较低等级评定，鼓励继续优化 |

评估报告模板

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

### 总体评分

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

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

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

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

### 建议操作

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

---

通用错误处理

以下错误在所有模式中均可能发生，统一在此处理。

| 错误场景 | 错误表现 | 处理方式 | | ---------- | --------------------- | ---------------------------------------------------- | | 文件不存在 | Read 报错文件不存在 | 检查路径是否正确，如 skill-name 拼写错误，询问用户 | | 写入失败 | Write 返回错误 | 检查路径是否正确，如路径含空格需用引号包裹，重试写入 |