skill-creator-yashu

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

🎯 触发映射

🎯 Trigger Mapping

用户输入触发词	AI 执行动作
"创建 skill" / "新建 skill" / "添加 skill" / "初始化 skill"	按【创建模式】执行

User Input Trigger Phrases	AI Action to Perform
"create skill" / "new skill" / "add skill" / "initialize skill"	Execute in [Creation Mode]

创建模式

Creation Mode

执行步骤

Execution Steps

步骤	执行动作	具体命令/操作
1	询问需求	运行 `AskUserQuestion` 询问用户 skill 功能、使用场景和触发条件
2	初始化目录	运行 `RunCommand` 执行 `python scripts/init_skill.py <skill-name> --path <output-dir>`
3	读取并编辑 SKILL	运行 `Read` 读取生成的 SKILL.md，运行 `SearchReplace` 填写功能描述和触发条件
4	验证结构	运行 `RunCommand` 执行 `python scripts/quick_validate.py <skill-directory>`

Step	Action	Specific Command/Operation
1	Ask for Requirements	Run `AskUserQuestion` to inquire about the skill's function, usage scenarios and trigger conditions
2	Initialize Directory	Run `RunCommand` to execute `python scripts/init_skill.py <skill-name> --path <output-dir>`
3	Read and Edit SKILL	Run `Read` to read the generated SKILL.md, then run `SearchReplace` to fill in the function description and trigger conditions
4	Validate Structure	Run `RunCommand` to execute `python scripts/quick_validate.py <skill-directory>`

输出结果

Output Results

成功时输出示例：

✅ Skill '{skill-name}' 创建成功

📁 目录结构：
.trae/skills/{skill-name}/
├── SKILL.md          # 技能文档（已填充模板）
├── scripts/          # 脚本目录
│   └── example.py    # 示例脚本
└── references/       # 参考文档目录
    └── README.md     # 参考说明

📝 下一步：
运行 `Read` 读取 SKILL.md，根据用户需求编辑功能描述和触发条件

失败时输出示例：

❌ Skill 创建失败

错误原因：{具体错误信息}
解决建议：{针对性解决方案}

Example Output on Success:

✅ Skill '{skill-name}' created successfully

📁 Directory Structure:
.trae/skills/{skill-name}/
├── SKILL.md          # Skill documentation (template filled)
├── scripts/          # Script directory
│   └── example.py    # Sample script
└── references/       # Reference documentation directory
    └── README.md     # Reference instructions

📝 Next Steps:
Run `Read` to open SKILL.md, then edit the function description and trigger conditions based on user requirements

Example Output on Failure:

❌ Skill creation failed

Error Reason: {specific error message}
Suggested Solution: {targeted solution}

错误处理

Error Handling

错误场景	错误表现	处理方式
目录已存在	`mkdir` 报错目录已存在	运行 `LS` 检查目录内容，如为空则继续，如有内容则询问用户是否覆盖
脚本执行失败	Python 返回非零退出码	检查 Python 版本、依赖安装情况，重试执行
权限不足	文件写入被拒绝	检查目录权限，建议用户更换输出目录
skill 名称无效	含大写或特殊字符	提示用户修改为 kebab-case 格式（如 `my-skill` ）

Error Scenario	Error Manifestation	Handling Method
Directory Already Exists	`mkdir` reports directory exists error	Run `LS` to check directory content; proceed if empty, ask user whether to overwrite if there is content
Script Execution Failure	Python returns non-zero exit code	Check Python version and dependency installation, retry execution
Insufficient Permissions	File write access denied	Check directory permissions, suggest user to change output directory
Invalid Skill Name	Contains uppercase letters or special characters	Prompt user to modify to kebab-case format (e.g., `my-skill` )

核心原则

Core Principles

简洁至上 (Concise is Key)

Concise is Key

上下文窗口是公共资源。Skill 与系统提示词、对话历史、其他 Skill 的元数据以及用户请求共享上下文窗口。

默认假设：AI 已经很聪明了。 只添加 AI 没有的信息。质疑每一条信息："AI 真的需要这个解释吗？" "这段文字值得它的 token 成本吗？"

优先使用简洁的例子而非冗长的解释。

The context window is a shared resource. Skills share the context window with system prompts, conversation history, metadata of other skills, and user requests.

Default Assumption: AI is already intelligent. Only add information that the AI doesn't have. Question every piece of information: "Does the AI really need this explanation?" "Is this text worth its token cost?"

Prioritize concise examples over lengthy explanations.

设置适当的自由度

Set Appropriate Flexibility

根据任务的脆弱性和可变性匹配合适的详细程度：

自由度	适用场景	形式
高自由度	多种方法都有效、决策依赖上下文、启发式指导方法	基于文本的指令
中自由度	存在首选模式、允许一定变化、配置影响行为	伪代码或带参数的脚本
低自由度	操作脆弱且容易出错、一致性至关重要、必须遵循特定序列	特定脚本、少量参数

Match the level of detail to the fragility and variability of the task:

Flexibility Level	Applicable Scenarios	Form
High Flexibility	Multiple valid approaches exist, decisions depend on context, heuristic guidance is needed	Text-based instructions
Medium Flexibility	Preferred patterns exist, some variations are allowed, configurations affect behavior	Pseudocode or scripts with parameters
Low Flexibility	Operations are fragile and error-prone, consistency is critical, specific sequences must be followed	Specific scripts with few parameters

AI 友好性 (AI-Friendly)

AI-Friendly

Skill 是给 AI 使用的，必须确保 AI 能够准确理解和执行。创建的 skill 必须符合以下 AI 友好性标准：

检查项	要求	说明
清晰的 description	必须	frontmatter 中的 description 必须包含功能和触发条件
明确的指令	必须	使用祈使句（运行、执行、调用等）而非模糊建议
具体的示例	必须	提供代码示例或用户请求示例，AI 需要知道具体怎么做
决策逻辑	推荐	复杂任务提供条件判断或决策树，帮助 AI 做出正确选择
输出格式	必须	明确说明 skill 应该输出什么内容
错误处理	推荐	说明异常情况和边界处理
避免长段落	推荐	超过 500 字符的段落难以提取关键信息，使用列表或表格
文件引用说明	必须	引用的文件必须有 Markdown 链接说明

优化技巧：

想象你是 AI，阅读 skill 后能否知道：什么时候用？怎么用？输出什么？
使用具体而非抽象的词汇
提供明确的操作步骤而非模糊的指导
为复杂场景提供决策流程

Skills are for AI use - ensure that AI can accurately understand and execute them. Created skills must meet the following AI-friendly standards:

Check Item	Requirement	Description
Clear description	Mandatory	The description in frontmatter must include function and trigger conditions
Clear Instructions	Mandatory	Use imperative sentences (run, execute, call, etc.) instead of vague suggestions
Specific Examples	Mandatory	Provide code examples or user request examples, AI needs to know how to do it specifically
Decision Logic	Recommended	For complex tasks, provide conditional judgments or decision trees to help AI make correct choices
Output Format	Mandatory	Clearly specify what content the skill should output
Error Handling	Recommended	Explain abnormal situations and boundary handling
Avoid Long Paragraphs	Recommended	Paragraphs over 500 characters make it difficult to extract key information; use lists or tables
File Reference Explanation	Mandatory	Referenced files must have Markdown link descriptions

Optimization Tips:

Imagine you are the AI; after reading the skill, can you answer: When to use it? How to use it? What to output?
Use specific rather than abstract vocabulary
Provide clear operation steps instead of vague guidance
Provide decision processes for complex scenarios

Agent Skills 规范要点

Key Specifications for Agent Skills

目录结构

Directory Structure

skill-name/
├── SKILL.md          # 必需：技能文档
├── scripts/          # 可选：可执行代码
├── references/       # 可选：参考文档
└── assets/           # 可选：模板、资源

不应包含的文件： README.md、INSTALLATION_GUIDE.md、CHANGELOG.md 等辅助文档。

skill-name/
├── SKILL.md          # Required: Skill documentation
├── scripts/          # Optional: Executable code
├── references/       # Optional: Reference documentation
└── assets/           # Optional: Templates, resources

Files that should not be included: Auxiliary documents such as README.md, INSTALLATION_GUIDE.md, CHANGELOG.md.

SKILL.md 格式

SKILL.md Format

必需的前置元数据：

yaml

---
name: skill-name
description: 功能描述。何时使用：当用户说/需要/遇到...时
---

Required Frontmatter Metadata:

yaml

---
name: skill-name
description: Function description. When to use: When the user says/needs/encounters...
---

name 字段规则

Rules for name Field

1-64 字符，只能包含小写字母、数字和连字符
不能以连字符开头或结尾，不能包含连续连字符
```
--
```
必须与父目录名匹配

1-64 characters, can only contain lowercase letters, numbers and hyphens
Cannot start or end with a hyphen, cannot contain consecutive hyphens
```
--
```
Must match the parent directory name

description 字段规则

Rules for description Field

1-1024 字符
必须包含两部分内容，用
何时使用：
分隔：
1. 功能描述 - 这个 skill 是做什么的
2. 何时使用 - 用户说什么话时触发这个 skill
所有触发条件信息都应放在 description 中 - 不要放在正文

好的示例：

yaml

description: 分析并优化其他 Skill 的文档质量问题，包括 frontmatter 格式、渐进式披露结构等检查。何时使用：当用户说"优化这个 skill"、"检查 skill 质量"、"review skill"时。

不好的示例：

yaml

undefined

1-1024 characters
Must include two parts separated by
When to use:
:
1. Function Description - What this skill does
2. When to Use - What the user says to trigger this skill
All trigger condition information should be placed in the description - Do not put it in the main body

Good Example:

yaml

description: Analyze and optimize documentation quality issues of other Skills, including checks for frontmatter format, progressive disclosure structure, etc. When to use: When the user says "optimize this skill", "check skill quality", "review skill".

Bad Examples:

yaml

undefined

❌ 缺少"何时使用"部分

❌ Missing "When to use" section

description: 分析并优化 Skill 的文档质量问题

description: Analyze and optimize documentation quality issues of Skills

❌ 使用"触发条件"而非"何时使用"

❌ Uses "Trigger Conditions" instead of "When to use"

description: 分析 Skill 质量问题。触发条件：用户说优化 skill 时

undefined

description: Analyze Skill quality issues. Trigger Conditions: When the user says to optimize skill

undefined

渐进式披露设计

Progressive Disclosure Design

Skills 使用三级加载系统高效管理上下文：

元数据（name + description）- 始终在上下文中（约 100 词）
SKILL.md 正文 - skill 触发时加载（建议 < 5000 词，< 500 行）
捆绑资源 - AI 按需加载

关键原则： 当 skill 支持多种变体、框架或选项时，只在 SKILL.md 中保留核心工作流程和选择指导。将变体特定的细节移到单独的参考文件中。

Skills use a three-level loading system to efficiently manage context:

Metadata (name + description) - Always in context (approx. 100 words)
SKILL.md Main Body - Loaded when the skill is triggered (recommended < 5000 words, < 500 lines)
Bundled Resources - Loaded by AI on demand

Key Principle: When a skill supports multiple variants, frameworks or options, only retain the core workflow and selection guidance in SKILL.md. Move variant-specific details to separate reference files.

渐进式披露模式

Progressive Disclosure Patterns

模式 1：高级指南 + 参考

markdown

undefined

Pattern 1: Advanced Guide + References

markdown

undefined

快速开始

Quick Start

[核心代码示例]

[Core Code Example]

高级功能

Advanced Features

表单填写：参见 FORMS.md 完整指南
API 参考：参见 REFERENCE.md


**模式 2：按领域组织**

skill-name/ ├── SKILL.md (概览和导航) └── references/ ├── finance.md ├── sales.md └── product.md


**重要指南：**

- 避免深层嵌套引用，保持引用文件在 SKILL.md 的一级子目录内
- 避免重复：信息应该只在 SKILL.md 或参考文件中存在，不要两者都有

Form Filling: See complete guide in FORMS.md
API Reference: See REFERENCE.md


**Pattern 2: Organized by Domain**

skill-name/ ├── SKILL.md (Overview and Navigation) └── references/ ├── finance.md ├── sales.md └── product.md


**Important Guidelines:**

- Avoid deeply nested references; keep reference files in the first-level subdirectory of SKILL.md
- Avoid duplication: Information should exist only in SKILL.md or reference files, not both

SKILL.md 结构模式

SKILL.md Structure Patterns

选择最适合 skill 目的的结构：

模式	适用场景	结构
基于工作流程	顺序流程	`## 概览` → `## 工作流程决策树` → `## 步骤 1` ...
基于任务	工具集合	`## 概览` → `## 快速开始` → `## 任务类别 1` ...
参考/指南	标准或规范	`## 概览` → `## 指南` → `## 规范`
基于能力	集成系统	`## 概览` → `## 核心能力` → `### 1. 功能` ...

模式可以混合搭配。

Choose the structure that best fits the skill's purpose:

Pattern	Applicable Scenarios	Structure
Workflow-Based	Sequential processes	`## Overview` → `## Workflow Decision Tree` → `## Step 1` ...
Task-Based	Tool collections	`## Overview` → `## Quick Start` → `## Task Category 1` ...
Reference/Guide	Standards or specifications	`## Overview` → `## Guide` → `## Specifications`
Capability-Based	Integrated systems	`## Overview` → `## Core Capabilities` → `### 1. Feature` ...

Patterns can be mixed and matched.

Skill 创建流程

Skill Creation Process

按顺序执行以下步骤：

Execute the following steps in order:

Skill 创建流程

Skill Creation Process

按顺序执行以下步骤：


AskUserQuestion

RunCommand
Read
SearchReplace
Write
Write
RunCommand
SearchReplace

步骤	执行动作	具体命令/操作
1	询问功能需求	运行 `AskUserQuestion` 询问 skill 功能、使用示例、触发条件
2	规划可复用资源	分析需求，确定需要的 scripts、references、assets
3	初始化 Skill 目录	运行 `RunCommand` 执行 `python scripts/init_skill.py <skill-name> --path <output-directory>`
4	读取 SKILL.md	运行 `Read` 读取生成的 `.trae/skills/{skill-name}/SKILL.md`
5	编辑功能描述	运行 `SearchReplace` 填写 description、触发条件、执行步骤
6	创建脚本	如需脚本，运行 `Write` 创建到 `scripts/` 目录
7	创建参考文档	如需参考文档，运行 `Write` 创建到 `references/` 目录
8	验证结构	运行 `RunCommand` 执行 `python scripts/quick_validate.py <skill-directory>`
9	测试迭代	根据验证结果，运行 `SearchReplace` 修复问题

Execute the following steps in order:


AskUserQuestion

RunCommand
Read
SearchReplace
Write
Write
RunCommand
SearchReplace

Step	Action	Specific Command/Operation
1	Ask for Functional Requirements	Run `AskUserQuestion` to inquire about skill function, usage examples and trigger conditions
2	Plan Reusable Resources	Analyze requirements, determine required scripts, references, assets
3	Initialize Skill Directory	Run `RunCommand` to execute `python scripts/init_skill.py <skill-name> --path <output-directory>`
4	Read SKILL.md	Run `Read` to read the generated `.trae/skills/{skill-name}/SKILL.md`
5	Edit Function Description	Run `SearchReplace` to fill in description, trigger conditions and execution steps
6	Create Scripts	If scripts are needed, run `Write` to create them in the `scripts/` directory
7	Create Reference Documents	If reference documents are needed, run `Write` to create them in the `references/` directory
8	Validate Structure	Run `RunCommand` to execute `python scripts/quick_validate.py <skill-directory>`
9	Test and Iterate	Based on validation results, run `SearchReplace` to fix issues

工作流程模式

Workflow Patterns

详细的工作流程模式（顺序、条件、决策树、循环、错误处理）参见工作流程模式文档。

Detailed workflow patterns (sequence, condition, decision tree, loop, error handling) can be found in Workflow Patterns Documentation.

输出模式

Output Patterns

详细的输出模式（模板、示例、检查清单）参见输出模式文档。

Detailed output patterns (templates, examples, checklists) can be found in Output Patterns Documentation.

捆绑资源

Bundled Resources

scripts/

可执行代码（Python/Bash/等）用于需要确定性可靠性或重复重写的任务。

何时包含：相同的代码被重复重写或需要确定性可靠性时
好处：Token 高效、确定性、可以在不加载到上下文的情况下执行
AI 友好原则：代码的输入和输出应当是对 AI 友好的
- 输入：支持命令行参数、环境变量或结构化数据（JSON/YAML），避免交互式提示
- 输出：使用结构化格式（JSON/YAML/表格），包含明确的字段名，避免需要解析的自然语言描述
- 错误处理：返回标准退出码，错误信息输出到 stderr，成功结果输出到 stdout

Executable code (Python/Bash/etc.) used for tasks requiring deterministic reliability or repeated rewriting.

When to include: When the same code is repeatedly rewritten or requires deterministic reliability
Benefits: Token-efficient, deterministic, can be executed without loading into context
AI-Friendly Principles: The input and output of the code should be AI-friendly
- Input: Support command-line parameters, environment variables or structured data (JSON/YAML), avoid interactive prompts
- Output: Use structured formats (JSON/YAML/table), include clear field names, avoid natural language descriptions that need parsing
- Error Handling: Return standard exit codes, output error messages to stderr, output successful results to stdout

references/

文档和参考材料，旨在根据需要加载到上下文中。

何时包含：AI 工作时应该参考的详细文档
好处：保持 SKILL.md 精简，只在需要时加载

Documents and reference materials designed to be loaded into context on demand.

When to include: Detailed documents that AI should reference when working
Benefits: Keep SKILL.md concise, only load when needed

assets/

不打算加载到上下文中，而是在 AI 产生的输出中使用的文件。

何时包含：skill 需要在最终输出中使用的文件（模板、图片等）
好处：将输出资源与文档分离

Files not intended to be loaded into context, but used in the output generated by AI.

When to include: Files that the skill needs to use in the final output (templates, images, etc.)
Benefits: Separate output resources from documentation

实用脚本

Utility Scripts

脚本	用途	命令
init_skill.py	初始化新 skill	`python scripts/init_skill.py <skill-name> --path <output-dir>`
skill_templates.py	模板定义模块	被 init_skill.py 调用，包含 SKILL.md 和示例文件模板
quick_validate.py	快速验证	`python scripts/quick_validate.py <skill-directory>`
create-skill.py	创建完整 skill	`python scripts/create-skill.py <skill-name>`

Script	Purpose	Command
init_skill.py	Initialize new skill	`python scripts/init_skill.py <skill-name> --path <output-dir>`
skill_templates.py	Template definition module	Called by init_skill.py, contains templates for SKILL.md and sample files
quick_validate.py	Quick validation	`python scripts/quick_validate.py <skill-directory>`
create-skill.py	Create complete skill	`python scripts/create-skill.py <skill-name>`

创建示例

Creation Example

用户输入： "创建一个处理 PDF 的 skill"

执行步骤：

步骤	执行动作	具体命令/操作
1	询问场景	运行 `AskUserQuestion` 询问具体使用场景（提取文本、填写表单、合并等）
2	规划内容	分析需求，确定需要 Python 脚本处理 PDF
3	初始化目录	运行 `RunCommand` 执行 `python scripts/init_skill.py pdf-processor --path ./skills`
4	读取 SKILL.md	运行 `Read` 读取 `./skills/pdf-processor/SKILL.md`
5	编辑描述	运行 `SearchReplace` 填写 description 为"处理 PDF 文件。何时使用：当用户说处理 PDF 时"
6	创建处理脚本	运行 `Write` 创建 `scripts/pdf_extractor.py`
7	验证结构	运行 `RunCommand` 执行 `python scripts/quick_validate.py ./skills/pdf-processor`

User Input: "Create a skill to process PDFs"

Execution Steps:

Step	Action	Specific Command/Operation
1	Ask for Scenarios	Run `AskUserQuestion` to inquire about specific usage scenarios (text extraction, form filling, merging, etc.)
2	Plan Content	Analyze requirements, determine that Python scripts are needed to process PDFs
3	Initialize Directory	Run `RunCommand` to execute `python scripts/init_skill.py pdf-processor --path ./skills`
4	Read SKILL.md	Run `Read` to read `./skills/pdf-processor/SKILL.md`
5	Edit Description	Run `SearchReplace` to fill in description as "Process PDF files. When to use: When the user says to process PDFs"
6	Create Processing Script	Run `Write` to create `scripts/pdf_extractor.py`
7	Validate Structure	Run `RunCommand` to execute `python scripts/quick_validate.py ./skills/pdf-processor`