skill-laws

Skill Laws (Design Laws)

Supreme Law: All Skills are instruction sets for AI; humans only speak natural language, and AI parses intent, invokes Skills, and completes operations.

---

🎯 Trigger mapping: user says → AI does

User input trigger words	AI executes action
"create skill" / "new skill" / "add skill" / "initialize skill"	Execute according to [Creation Mode]
"optimize skill" / "skill has a problem" / "check skill" / "review skill" / "diagnose skill"	Execute according to [Optimization Mode]
"how is this skill" / "evaluate skill" / "is the skill designed well"	Execute according to [Evaluation Mode]

---

Creation Mode

Trigger: The user wants to create a new Skill

Execution steps

Step	Execution action	Specific command/operation
1	Determine the skill directory name	Use the format skill-{功能名}, all lowercase, hyphen-separated
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 the variables:{skill-name} {功能描述} {触发条件}
5	Add trigger mapping table	Add a "trigger mapping" block after the frontmatter
6	Add execution steps	Use a table to list steps, actions, and specific commands
7	Check core laws	Verify item by item against the [Core Laws Checklist]; only consider it complete when all pass
8	Create references	If content > 500 lines, move detailed content to the references/ directory

Frontmatter template

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

Core Laws Checklist (must all pass during creation)

Law	Check standard	Pass?	If not passed
⭐⭐⭐ Human-centered	The user only needs to speak natural language and does not need to manually operate files or run commands	⬜	Add AI execution steps and remove manual user operations
⭐⭐⭐ AI-first	Use imperative instructions (run/check/call/execute) and display decision logic in tables	⬜	Change "you can..." to "run..." and change long paragraphs into tables
⭐⭐⭐ Ready-to-use	There is a "trigger mapping" block at the top, with user input → AI action in one-to-one correspondence	⬜	Add trigger mapping table
Progressive disclosure	Core content < 500 lines, detailed content placed in references/	⬜	Move content exceeding 500 lines to references
Error handling	Include a table of common error scenarios and handling methods	⬜	Add error handling table

Error handling

Error scenario	Error manifestation	Handling method
Directory already exists	mkdir Error: directory already exists	Run LS to check directory contents; if empty, continue; if it has contents, ask the user whether to overwrite
File write failed	Write Return error	Check whether the path is correct; if the path contains spaces, wrap it in quotes, and retry writing
Variables not replaced	SKILL.md contains {skill-name} and other placeholders	Run SearchReplace to replace all placeholders with actual values
Content exceeds 500 lines	SKILL.md line count > 500	Move detailed content to the references/ directory; keep a simplified version of the core content

---

Optimization mode

Trigger: the user wants to optimize an existing Skill or points out that the Skill has problems

Execution steps

Step	Execution action	Specific command
1	Read target Skill	Run the Read tool to read {skill-path}/SKILL.md
2	Check item by item	Mark each item ✅/❌ against the [Core Rule Checklist] and [Documentation Specification Checklist]
3	Count issues	Count the number of ❌ items and sort by priority (core rules first)
4	Perform fixes	Run SearchReplace or Write to fix issues; refer to [Correct vs Incorrect Comparison]
5	Output report	Output results according to [Optimization Report Template]

Documentation Specification Checklist

Check item	Compliance standard	Current status	Fix command
description	Includes "When to use: when the user says/needs/encounters..."	⬜	SearchReplace Add trigger conditions
Instruction tone	Use imperative sentences (run/check/call/execute)	⬜	SearchReplace "You can" → "Run"
Decision logic	Use tables for complex tasks to show conditional branches	⬜	Change long paragraphs into a conditional table
Output format	Clearly state what is output after execution and how it is displayed	⬜	Add output example code block
Error handling	Includes a table of error scenarios and handling methods	⬜	Add error handling table
File references	Use Markdown link format [名](路径)	⬜	SearchReplace change to a clickable link
Progressive disclosure	Core instructions < 500 lines	⬜	Move detailed content to the references/
Trigger mapping	There is a "User says → AI does" mapping table at the top	⬜	Add trigger mapping section

Correct vs Incorrect Comparison (Quick Fix Reference)

❌ Incorrect example	✅ Correct example	Fix operation
"You can run..."	"Run..."	SearchReplace Remove "You can"
"It is recommended to check..."	"Check..."	SearchReplace Delete "suggestion"
"If needed..."	"If X then execute Y"	Change to conditional table
"Please refer to the documentation for details"	"Refer to filename execute..."	SearchReplace Add link
Long paragraph description	Table/list + specific commands	Refactor into table format
"Ensure xxx"	"Run 命令 check xxx"	Add specific check command

Error handling

Error scenario	Error manifestation	Handling method
File does not exist	Read Reports error file does not exist	Check whether the path is correct, such as a spelling error in skill-name, ask the user for the correct name
No issues, can be optimized	All check items are ✅	Output "This Skill complies with all laws, no optimization needed", and output the evaluation report according to [Evaluation Mode]
New issues introduced after fixing	Fixing issue A causes issue B	Roll back changes, fix step by step, re-check after each step
User does not approve of the fix	User says "do not change this"	Record user feedback, skip this item, continue optimizing other items

Optimization report template

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

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

### 主要问题

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

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

### 已修复

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

### 后续建议

- {建议内容}

---

Evaluation mode

Trigger: The user asks how well the skill is designed or requests an evaluation of the Skill quality

Execution steps

Step	Execution action	Specific command
1	Read the target Skill	Run Read tool to read {skill-path}/SKILL.md
2	Core laws evaluation	Check whether it complies with the 5 laws in [Core Laws Checklist]
3	Documentation standards evaluation	Check whether it complies with the 8 standards in [Documentation Standards Checklist]
4	Calculate score	Count the number of compliant items and determine the grade
5	Output evaluation	Output the result according to [Evaluation Report Template]

Evaluation criteria

Grade	Score	Description
🏆 Perfect	13/13	Fully complies with Skill Laws and can be used directly
✅ Excellent	11-12/13	Basically compliant, a few details can be optimized
⚠️ Good	8-10/13	There is obvious room for improvement
❌ Needs optimization	< 8/13	Requires major refactoring

Error handling

Error scenario	Error manifestation	Handling method
File does not exist	Read Reports error file does not exist	Ask the user for the correct skill name or path
Not a Skill file	The file does not contain the SKILL.md structure	Output "This file is not a Skill and cannot be evaluated", and explain the Skill file structure requirements
Score boundaries	Score exactly at the boundary (e.g., 10 points or 12 points)	Round down and rate at the lower level, encouraging continued optimization

Evaluation report template

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

### 总体评分

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

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

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

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

### 建议操作

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