Skill Laws (Design Principles)

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

🎯 Trigger Mapping: User Says → AI Does

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

Trigger: User wants to create a new Skill

Execution Steps

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 Template

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)

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

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

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

Execution Steps

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

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)

❌ 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

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

## Optimization Report: {skill-name}

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

### Key Issues

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

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

### Fixed Issues

- {Fixed Content}
- {Fixed Content}

### Follow-Up Suggestions

- {Suggestion Content}

Evaluation Mode

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

Execution Steps

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

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

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

## Skill Quality Evaluation: {skill-name}

### Overall Score

**Compliance**: {X}/13 Items ✅

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

### Key Issues (If Rating is Not 🏆)

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

### Recommended Actions

- 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

skill-laws

NPX Install

Tags

SKILL.md Content (Chinese)

Skill Laws (Design Principles)

🎯 Trigger Mapping: User Says → AI Does

Creation Mode

Execution Steps

Frontmatter Template

Core Principles Checklist (Must Pass All During Creation)

Error Handling

Optimization Mode

Execution Steps

Documentation Specification Checklist

Positive and Negative Comparisons (Quick Fix Reference)

Error Handling

Optimization Report Template

Evaluation Mode

Execution Steps

Evaluation Criteria

Error Handling

Evaluation Report Template