skill-creator-yashu

🎯 Trigger Mapping

User input trigger word	AI execution action
"create skill" / "new skill" / "add skill" / "initialize skill"	Execute according to [Creation Mode]

---

Creation Mode

Execution Steps

Step	Execution action	Specific command/operation
1	Ask for requirements	Run AskUserQuestion to ask the user about the skill's functionality, use cases, and trigger conditions
2	Initialize directory	Run RunCommand execute python scripts/init_skill.py <skill-name> --path <output-dir>
3	Read and edit SKILL	Run Read read the generated SKILL.md, run SearchReplace fill in the functionality description and trigger conditions
4	Validate structure	Run RunCommand execute python scripts/quick_validate.py <skill-directory>

Output Result

Example output on success:

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

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

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

Example output on failure:

❌ Skill 创建失败

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

Error Handling

Error scenario	Error manifestation	Handling method
Directory already exists	mkdir reports that the directory already exists	Run LS check the directory contents; if empty, continue; if it has contents, ask the user whether to overwrite
Script execution failed	Python returns a non-zero exit code	Check the Python version and dependency installation status, and retry execution
Insufficient permissions	File write is denied	Check directory permissions and suggest the user change the output directory
Invalid skill name	Contains uppercase letters or special characters	Prompt the user to change it to kebab-case format (e.g. my-skill）

Core Principles

Concise is Key

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

Default assumption: AI is already very smart. Only add information that AI does not have. Question every piece of information: "Does AI really need this explanation?" "Is this text worth its token cost?"

Prefer concise examples over lengthy explanations.

Set an appropriate degree of freedom

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

Degree of freedom	Applicable scenario	Form
High degree of freedom	Multiple methods are effective, decisions depend on context, heuristic guidance methods	Text-based instructions
Medium degree of freedom	A preferred pattern exists, some variation is allowed, configuration affects behavior	Pseudocode or scripts with parameters
Low degree of freedom	Operations are fragile and error-prone, consistency is critical, a specific sequence must be followed	Specific scripts, few parameters

AI-Friendly

Skills are for AI use, it must be ensured that the AI can accurately understand and execute it. The created skill must meet the following AI-friendliness standards:

Check item	Requirement	Description
Clear description	Must	The description in frontmatter must include the function and trigger conditions
Explicit instructions	Must	Use imperative sentences (run, execute, call, etc.) rather than vague suggestions
Concrete examples	Must	Provide code examples or user request examples; the AI needs to know exactly how to do it
Decision logic	Recommended	For complex tasks, provide conditional judgments or a decision tree to help the AI make the correct choice
Output format	Must	Clearly state what content the skill should output
Error handling	Recommended	Explain exceptional situations and boundary handling
Avoid long paragraphs	Recommended	Paragraphs over 500 characters are difficult to extract key information from; use lists or tables
File reference description	Must	Referenced files must have Markdown link descriptions

Optimization tips:

• Imagine you are the AI: after reading the skill, can you know: when to use it? How to use it? What to output?
• Use concrete rather than abstract vocabulary
• Provide clear operational steps rather than vague guidance
• Provide a decision process for complex scenarios

Key points of the Agent Skills specification

Directory structure

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

Files that should not be included: README.md, INSTALLATION_GUIDE.md, CHANGELOG.md, and other auxiliary documents.

SKILL.md format

Required frontmatter metadata:

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

Rules for the name field

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

Rules for the description field

• 1-1024 characters
• Must contain two parts, separated by 何时使用： :
  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 body

Good example:

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

Bad example:

# ❌ 缺少"何时使用"部分
description: 分析并优化 Skill 的文档质量问题

# ❌ 使用"触发条件"而非"何时使用"
description: 分析 Skill 质量问题。触发条件：用户说优化 skill 时

Progressive disclosure design

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

1. Metadata(name + description) - always in context (about 100 words)
2. SKILL.md body - loaded when the skill is triggered (recommended < 5000 words, < 500 lines)
3. Bundled resources - loaded by the AI on demand

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

Progressive disclosure pattern

Pattern 1: Advanced Guide + Reference

## 快速开始

[核心代码示例]

## 高级功能

- **表单填写**：参见 [FORMS.md](references/FORMS.md) 完整指南
- **API 参考**：参见 [REFERENCE.md](references/REFERENCE.md)

Pattern 2: Organized by Domain

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

Important Guidelines:

• Avoid deeply nested references; keep referenced files within the first-level subdirectory of SKILL.md
• Avoid duplication: information should exist only in SKILL.md or a reference file, not both

SKILL.md Structure Patterns

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

Pattern	Applicable Scenario	Structure
Workflow-based	Sequential process	## 概览 → ## 工作流程决策树 → ## 步骤 1...
Task-based	Tool collection	## 概览 → ## 快速开始 → ## 任务类别 1...
Reference/Guide	Standards or specifications	## 概览 → ## 指南 → ## 规范
Capability-based	Integrated systems	## 概览 → ## 核心能力 → ### 1. 功能...

Patterns can be mixed and matched.

Skill Creation Process

Perform the following steps in order:

Skill Creation Process

Perform the following steps in order:

Step	Action	Specific Command/Operation
1	Ask about functional requirements	Run AskUserQuestion Ask about the skill's functionality, usage examples, and trigger conditions
2	Plan reusable resources	Analyze requirements and determine the needed scripts, references, and assets
3	Initialize Skill directory	Run RunCommand Execute python scripts/init_skill.py <skill-name> --path <output-directory>
4	Read SKILL.md	Run Read Read the generated .trae/skills/{skill-name}/SKILL.md
5	Edit functional description	Run SearchReplace Fill in the description, trigger conditions, and execution steps
6	Create scripts	If scripts are needed, run Write Create to scripts/ directory
7	Create reference documents	If reference documents are needed, run Write Create to references/ directory
8	Validate structure	Run RunCommand Execute python scripts/quick_validate.py <skill-directory>
9	Test and iterate	Based on the validation results, run SearchReplace Fix issues

Workflow Patterns

For detailed workflow patterns (sequential, conditional, decision tree, loop, error handling), see Workflow Patterns Document。

Output Patterns

For detailed output patterns (templates, examples, checklists), see Output Patterns Document。

Bundled Resources

scripts/

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

• When to include: When the same code is repeatedly rewritten or deterministic reliability is required
• Benefits: Token-efficient, deterministic, can be executed without loading into context
• AI-friendly principles: Code input and output should be AI-friendly
  • Input: Support command-line arguments, environment variables, or structured data (JSON/YAML); avoid interactive prompts
  • Output: Use structured formats (JSON/YAML/tables) with explicit field names; avoid natural language descriptions that require parsing
  • Error handling: return standard exit codes, output error messages to stderr, and output successful results to stdout

references/

Documentation and reference materials, intended to be loaded into context as needed.

• When to include: Detailed documentation that the AI should refer to while working
• Benefit: Keep SKILL.md concise and load only when needed

assets/

Files that are not intended to be loaded into context, but rather used in the output produced by the AI.

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

Utility scripts

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

Create example

User input: "Create a skill for processing PDFs"

Execution steps:

Step	Action	Specific command/operation
1	Ask about the scenario	Run AskUserQuestion to ask about the specific use scenario (extracting text, filling forms, merging, etc.)
2	Plan the content	Analyze the requirements and determine that a Python script is needed to process PDFs
3	Initialize the directory	Run RunCommand execute python scripts/init_skill.py pdf-processor --path ./skills
4	Read SKILL.md	Run Read read ./skills/pdf-processor/SKILL.md
5	Edit the description	Run SearchReplace set description to "Process PDF files. When to use: when the user says to process a PDF"
6	Create the processing script	Run Write create scripts/pdf_extractor.py
7	Validate the structure	Run RunCommand execute python scripts/quick_validate.py ./skills/pdf-processor