skill-laws

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Laws（设计法则）

Skill Laws (Design Principles)

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

Supreme Law: All Skills are instruction sets for AI. Humans only speak natural language, and AI parses intentions, calls Skills, and completes operations.

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

🎯 Trigger Mapping: User Says → AI Does

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

User Input Trigger Phrases	AI Execution Action
"Create skill" / "New skill" / "Add skill" / "Initialize skill"	Execute in [Creation Mode]
"Optimize skill" / "Skill has issues" / "Check skill" / "Review skill" / "Diagnose skill"	Execute in [Optimization Mode]
"How is this skill?" / "Evaluate skill" / "Is the skill well-designed?"	Execute in [Evaluation Mode]

创建模式

Creation Mode

触发：用户要创建新 Skill

Trigger: User wants to create a new Skill

执行步骤

Execution Steps

步骤	执行动作	具体命令/操作
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/` 目录

Step	Execution Action	Specific Command/Operation
1	Determine Skill Directory Name	Use the format `skill-{function-name}` , all lowercase, separated by hyphens
2	Create Directory Structure	Run `mkdir -p .skills/{skill-name}/{references,scripts}`
3	Create SKILL.md	Run the `Write` tool to create the file, path: `.skills/{skill-name}/SKILL.md`
4	Write Frontmatter	Copy the template below and replace variables: `{skill-name}` `{function description}` `{trigger conditions}`
5	Add Trigger Mapping Section	Add the "Trigger Mapping" section after the frontmatter
6	Add Execution Steps	List steps, actions, and specific commands in a table
7	Check Core Principles	Verify item by item against the [Core Principles Checklist]; creation is only complete when all items pass
8	Create references	If content > 500 lines, move detailed content to the `references/` directory

Frontmatter 模板

Frontmatter Template

yaml

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

yaml

---
name: {skill-name}
description: {function description}. When to use: When users {say/need/encounter} {trigger conditions}.
metadata:
  author: "{author-name}"
  updated: "{YYYY-MM-DD HH:MM:SS}"
  version: "1.0.0"
---

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

Core Principles Checklist (Must Pass All During Creation)

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

Principle	Inspection Standard	Pass?	If Not Passing
⭐⭐⭐ Human-Centric	Users only need to speak natural language; no manual file operations or command execution required	⬜	Add AI execution steps and remove manual user operations
⭐⭐⭐ AI-First	Use imperative instructions (run/check/call/execute) and present decision logic in tables	⬜	Change "You can..." to "Run..." and convert long paragraphs to tables
⭐⭐⭐ Ready-to-Use	Has a "Trigger Mapping" section at the top, with one-to-one correspondence between user input and AI actions	⬜	Add trigger mapping table
Progressive Disclosure	Core content < 500 lines; detailed content stored in `references/`	⬜	Move content exceeding 500 lines to references
Error Handling	Includes a table of common error scenarios and handling methods	⬜	Add error handling table

错误处理

Error Handling

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

Error Scenario	Error Performance	Handling Method
Directory Already Exists	`mkdir` reports error that directory already exists	Run `LS` to check directory content; continue if empty, ask user whether to overwrite if there is content
File Write Failure	`Write` returns an error	Check if the path is correct; if the path contains spaces, wrap it in quotes, then retry writing
Variables Not Replaced	SKILL.md contains placeholders like `{skill-name}`	Run `SearchReplace` to replace all placeholders with actual values
Content Exceeds 500 Lines	SKILL.md has > 500 lines	Move detailed content to the `references/` directory and keep a streamlined version of the core content

优化模式

Optimization Mode

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

Trigger: User wants to optimize an existing Skill or points out issues with a Skill

执行步骤

Execution Steps

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

Step	Execution Action	Specific Command
1	Read Target Skill	Run the `Read` tool to read `{skill-path}/SKILL.md`
2	Item-by-Item Inspection	Mark ✅/❌ item by item against the [Core Principles Checklist] and [Documentation Specification Checklist]
3	Count Issues	Count the number of ❌ items and sort by priority (core principles first)
4	Execute Fixes	Run `SearchReplace` or `Write` to fix issues, refer to [Positive and Negative Comparisons]
5	Output Report	Output results according to the [Optimization Report Template]

文档规范检查表

Documentation Specification Checklist

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

Inspection Item	Compliance Standard	Current Status	Fix Command
description	Includes "When to use: When users say/need/encounter..."	⬜	`SearchReplace` to add trigger conditions
Instruction Tone	Uses imperative sentences (run/check/call/execute)	⬜	`SearchReplace` to change "You can" to "Run"
Decision Logic	Use tables to display conditional branches for complex tasks	⬜	Convert long paragraphs to conditional tables
Output Format	Clearly states what to output after execution and how to display it	⬜	Add output example code blocks
Error Handling	Includes a table of error scenarios and handling methods	⬜	Add error handling table
File References	Uses Markdown link format `[name](path)`	⬜	`SearchReplace` to convert to clickable links
Progressive Disclosure	Core instructions < 500 lines	⬜	Move detailed content to `references/`
Trigger Mapping	Has a "User Says → AI Does" mapping table at the top	⬜	Add trigger mapping section

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

Positive and Negative Comparisons (Quick Fix Reference)

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

❌ Incorrect Example	✅ Correct Example	Fix Operation
"You can run..."	"Run..."	`SearchReplace` to remove "You can"
"It is recommended to check..."	"Check..."	`SearchReplace` to remove "It is recommended to"
"You can... if needed"	"If X, execute Y"	Convert to conditional table
"Please refer to the documentation for details"	"Refer to File Name to execute..."	`SearchReplace` to add links
Long paragraph description	Table/list + specific commands	Restructure into table format
"Ensure xxx"	"Run `command` to check xxx"	Add specific check commands

错误处理

Error Handling

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

Error Scenario	Error Performance	Handling Method
File Does Not Exist	`Read` reports error that file does not exist	Check if the path is correct; if the skill-name is misspelled, ask the user for the correct name
No Issues to Optimize	All inspection items are ✅	Output "This Skill complies with all principles and does not need optimization" and output an evaluation report according to [Evaluation Mode]
New Issues Introduced After Fix	Fixing issue A causes issue B	Roll back changes, fix step by step, and recheck after each fix
User Disapproves of Fix	User says "Don't change this"	Record user feedback, skip this item, and continue optimizing other items

优化报告模板

Optimization Report Template

undefined

undefined

优化报告：{skill-name}

Optimization Report: {skill-name}

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

Score: {Number of Passed Items}/13 Items Complied (5 Core Principles + 8 Documentation Specifications)

主要问题

Key Issues

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

{Issue Description}
- Fix Operation: {Specific Operation}
- Tools Used: {Read/SearchReplace/Write}
{Issue Description}
- Fix Operation: {Specific Operation}
- Tools Used: {Read/SearchReplace/Write}

已修复

Fixed Issues

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

{Fixed Content}
{Fixed Content}

后续建议

Follow-Up Suggestions

{建议内容}

---

{Suggestion Content}

---

评估模式

Evaluation Mode

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

Trigger: User asks how well a skill is designed or requests a Skill quality evaluation

执行步骤

Execution Steps

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

Step	Execution Action	Specific Command
1	Read Target Skill	Run the `Read` tool to read `{skill-path}/SKILL.md`
2	Core Principles Evaluation	Check compliance with the 5 principles in the [Core Principles Checklist]
3	Documentation Specification Evaluation	Check compliance with the 8 specifications in the [Documentation Specification Checklist]
4	Calculate Score	Count the number of compliant items and determine the rating
5	Output Evaluation	Output results according to the [Evaluation Report Template]

评估标准

Evaluation Criteria

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

Rating	Score	Description
🏆 Perfect	13/13	Fully complies with Skill Laws and can be used directly
✅ Excellent	11-12/13	Basically compliant; minor details can be optimized
⚠️ Good	8-10/13	Has obvious room for improvement
❌ Needs Optimization	< 8/13	Requires major restructuring

错误处理

Error Handling

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

Error Scenario	Error Performance	Handling Method
File Does Not Exist	`Read` reports error that file does not exist	Ask the user for the correct skill name or path
Non-Skill File	File does not have SKILL.md structure	Output "This file is not a Skill and cannot be evaluated" and explain the Skill file structure requirements
Score Boundary	Score is exactly at the boundary (e.g., 10 points or 12 points)	Round down and rate at the lower level to encourage further optimization

评估报告模板

Evaluation Report Template

undefined

undefined

Skill 质量评估：{skill-name}

Skill Quality Evaluation: {skill-name}

总体评分

Overall Score

符合度：{X}/13 项 ✅

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

Compliance: {X}/13 Items ✅

Rating: {🏆/✅/⚠️/❌}

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

Key Issues (If Rating is Not 🏆)

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

{Issue Description} → {Improvement Suggestion}
{Issue Description} → {Improvement Suggestion}

建议操作

Recommended Actions

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

undefined

If rating is ❌ Needs Optimization: Perform full optimization according to [Optimization Mode]
If rating is ⚠️ Good: Fix core issues one by one
If rating is ✅ Excellent: Fine-tune details to reach 🏆 Perfect

undefined