skill-laws

Skill Laws (Design Laws)

Core idea: Skills are for AI to use; documentation is for people to help AI write.

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

---

Feature Overview

This Skill is a general framework of laws for Skill design, used to standardize the creation, optimization, and evaluation process of all Skills. It defines the two core laws of "the user speaks, the AI acts" and "AI-first", and provides actionable execution steps, a unified checklist, and a report template to ensure Skill documentation is AI-friendly and human-readable.

Environment Description

• This Skill is a general framework, applicable to the creation, optimization, and evaluation of any type of Skill, and is not bound to a specific tech stack or directory structure.
• During execution, use the target Skill'sSKILL.md as the core operation object, and use the path where the target Skill is located as the context for tool calls.
• The {skill-name}、{skill-path} and other variables appearing below must all be replaced with real values according to the actual target Skill.
• Different software has different Skill storage directories (such as .skills/、.trae/skills/ , etc.); when creating, use the actual path of the current environment as the standard.

$SKILL_DIR (Skill directory variable)

$SKILL_DIR refers to the absolute directory where the current Skill is located, that is, the folder where the SKILL.md file is located. If the Skill contains scripts/code, this variable and the script execution path must be defined in [Environment Description]. See skill-dir-guide.md。

---

🎯 Trigger Mapping: User says → AI does

User input trigger word	AI execution 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 well designed"	Execute according to [Evaluation Mode]

---

Unified Checklist

The three modes of creation, optimization, and evaluation share this table. Core laws (⭐⭐⭐) are necessary conditions, and documentation standards are sufficient conditions.

#	Category	Check item	Compliance standard
1	⭐⭐⭐ Core law	The user speaks, the AI acts	The user speaks natural language, and the AI performs all operations (excluding steps that require the user to manually operate files or run commands)
2	⭐⭐⭐ Core law	AI-first	Use imperative instructions (run/check/invoke/execute), and use tables to present decision logic
3	Documentation standard	description	Include "When to use: when the user says/needs/encounters..."
4	Documentation standard	Feature Overview	The main text includes a [Feature Overview] paragraph explaining the core functions and scope of application
5	Documentation standard	Environment Description	Include an [Environment Description] paragraph. If it contains scripts/code, it must include $SKILL_DIR and script path definitions; if there is no script, just describe the runtime context
6	Documentation Standards	Instruction Tone	Use imperative sentences (run/check/call/execute), avoid weakening tones such as "you can" and "suggest"
7	Documentation Standards	Decision Logic	Use tables to present conditional branches for complex tasks
8	Documentation Standards	Output Format	Clearly state what is output after execution and how it is displayed
9	Documentation Standards	Error Handling	Include a table of error scenarios and handling methods
10	Documentation Standards	File References	Use Markdown link format [名](路径)
11	Documentation Standards	Progressive Disclosure	Core instructions < 500 lines; split into different files by functional module and load on demand; put general information in the main file and do not repeat it in subdocuments

Repair actions when not passed

#	Repair Actions
1	Add AI execution steps and remove manual user operations
2	Change "you can..." to "run...", and change long paragraphs to tables
3	SearchReplace Add "When to use: when the user..." trigger conditions
4	Write or SearchReplace Add a [Feature Overview] paragraph
5	Supplement according to whether scripts are included $SKILL_DIR and script paths, or describe the runtime context
6	SearchReplace Change "you can"/"suggest" to imperative sentences
7	Change long paragraphs to conditional tables
8	Add output example code blocks or output steps
9	Add a table of error scenarios and handling methods
10	SearchReplace Change to clickable link format
11	Move detailed content to references/, and split it into independent files by function

---

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 format skill-{功能名}, all lowercase, hyphen-separated
2	Create directory structure	Run mkdir create {skill-path}/{skill-name}/{references,scripts}
3	Create SKILL.md	Run Write tool to create the file, path:{skill-path}/{skill-name}/SKILL.md
4	Write frontmatter	Copy the template below and replace the variables:{skill-name} {功能描述} {触发条件}
5	Add feature overview	Add a [Feature Overview] paragraph at the beginning of the body, explaining the Skill's core functions and scope of application
6	Add environment description	If the Skill contains scripts/code, define $SKILL_DIR and the script execution path; if the Skill has no code, just describe the runtime context
7	Add execution steps	Use a table to list steps, actions, and specific commands
8	Add output format	Clearly state what is output after each step and what format the final output is in
9	Check the unified checklist	Verify item by item against the [Unified Checklist]; completion counts only when all pass
10	Create references	If the content is > 500 lines, move the 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"
---

Error Handling

Error Scenario	Error Symptom	Handling Method
Directory already exists	mkdir Reports directory already exists	Run LS to Check Directory Contents; if empty, continue; if there is content, ask the user whether to overwrite
Variables not replaced	SKILL.md contains {skill-name} and other placeholders	Run SearchReplace to replace all placeholders with actual values

---

Optimization Mode

Trigger: The user wants to optimize an existing Skill or points out that a Skill has issues

Execution Steps

Step	Execution Action	Specific Command
1	Read the target Skill	Run the Read tool to read {skill-path}/SKILL.md
2	Check item by item	Mark each item ✅/❌ against the [Unified Checklist]
3	Tally 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 [Fix Operations]
5	Verify fixes	Check again against the [Unified Checklist] to confirm the fixes did not introduce new issues
6	Output report	Output the result according to the [Optimization Report Template]

Correct vs. Incorrect Comparison (Quick Fix Reference)

❌ Incorrect Example	✅ Correct Example
"You can run..."	"Run..."
"It is recommended to check..."	"Check..."
"If needed, you can..."	Change to a conditional table: "If X, then execute Y"
"Please refer to the documentation for details"	"Refer to Filename to execute..."
"Ensure xxx"	"Run 命令 to check xxx"
Long paragraph description	Table/list + specific commands

Error Handling

Error Scenario	Error Symptom	Handling Method
No issues to optimize	All check items are ✅	Output an evaluation report according to [Evaluation Mode]
Fixes introduce new issues	Fixing issue A causes issue B	Roll back the changes, fix step by step, and re-check after each fix
User does not approve of the fix	The user says "do not change this"	Record the user's feedback, skip this item, and continue optimizing other items

Optimization Report Template

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

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

### 主要问题

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

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

### 已修复

- {修复内容}

### 后续建议

- {建议内容}

---

Evaluation Mode

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

Execution Steps

Step	Execution Action	Specific Command
1	Read the target Skill	Run Read Tool reading {skill-path}/SKILL.md
2	Core Laws Assessment	Check whether items 1-2 of the [Unified Checklist] are met
3	Documentation Standards Assessment	Check whether items 3-11 of the [Unified Checklist] are met
4	Calculate Score	Count the number of met items and determine the grade
5	Output Assessment Report	Output results according to the [Assessment Report Template]

Assessment Standards

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

Error Handling

Error Scenario	Error Manifestation	Handling Method
Non-Skill File	The file does not contain the SKILL.md structure	Output "This file is not a Skill and cannot be assessed" and explain the Skill file structure requirements
Score Boundary	The score is exactly at the boundary (such as 5 points or 8 points)	Round down and assign the lower grade to encourage continued optimization

Assessment Report Template

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

### 总体评分

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

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

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

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

### 建议操作

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

---

General Error Handling

The following errors may occur in all modes and are handled uniformly here.

Error Scenario	Error Manifestation	Handling Method
File Does Not Exist	Read Error: file does not exist	Check whether the path is correct, such as a misspelling of skill-name, and ask the user
Write Failure	Write Returns an error	Check whether the path is correct; if the path contains spaces, wrap it in quotes and retry the write