🎯 Trigger Mapping
| User input trigger words | AI action |
|---|---|
| "create skill" / "new skill" / "add skill" / "initialize skill" | Execute according to [Create Mode] |
Create Mode
Execution steps
| Step | 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 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, run SearchReplace to fill in the functionality description and trigger conditions |
| 4 | Validate structure | Run RunCommand to 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 error: directory already exists |
Run LS to 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, and retry execution |
| Insufficient permissions | File write 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 the user request.
Default assumption: the AI is already very smart. Only add information the AI does not have. Question every piece of information: "Does the AI really need this explanation?" "Is this text worth its token cost?"
Prefer concise examples over lengthy explanations.
Set the 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 valid, decisions depend on context, heuristic guidance method | 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 AI can accurately understand and execute them. The created skill must meet the following AI-friendliness standards:
| Check item | Requirement | Description |
|---|---|---|
| Clear description | Must | The description in frontmatter must include the functionality and trigger conditions |
| Explicit instructions | Must | Use imperative sentences (run, execute, call, etc.) rather than vague suggestions |
| Specific examples | Must | Provide code examples or user request examples; AI needs to know exactly how to do it |
| Decision logic | Recommended | For complex tasks, provide conditional judgments or a decision tree to help 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 exceeding 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 AI: after reading the skill, can you know: when to use it? How to use it? What to output?
- Use specific 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: 功能描述。何时使用:当用户说/需要/遇到...时
---
name field rules
- 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
description field rules
- 1-1024 characters
- Must contain two parts, separated by
何时使用::- Functional description - what this skill does
- When to use - what the user says to trigger this skill
- All trigger condition information should be placed in the description - do not place it in the body
Good examples:
description: 分析并优化其他 Skill 的文档质量问题,包括 frontmatter 格式、渐进式披露结构等检查。何时使用:当用户说"优化这个 skill"、"检查 skill 质量"、"review skill"时。
Bad examples:
# ❌ 缺少"何时使用"部分
description: 分析并优化 Skill 的文档质量问题
# ❌ 使用"触发条件"而非"何时使用"
description: 分析 Skill 质量问题。触发条件:用户说优化 skill 时
Progressive disclosure design
Skills use a three-level loading system to efficiently manage context:
- Metadata(name + description) - always in context (about 100 words)
- SKILL.md body - loaded when the skill is triggered (recommended < 5000 words, < 500 lines)
- Bundled resources - loaded by 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 deep nested references; keep referenced files within the first-level subdirectory of SKILL.md
- Avoid duplication: information should exist only in SKILL.md or the reference files, not both
SKILL.md structure patterns
Choose the structure that best fits the skill's purpose:
| Pattern | Applicable scenarios | Structure |
|---|---|---|
| Workflow-based | Sequential process | ## 概览 → ## 工作流程决策树 → ## 步骤 1... |
| Task-based | Tool collection | ## 概览 → ## 快速开始 → ## 任务类别 1... |
| Reference/guide | Standard or specification | ## 概览 → ## 指南 → ## 规范 |
| Capability-based | Integrated system | ## 概览 → ## 核心能力 → ### 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 to perform | 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 the 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 the functionality description | Run SearchReplace Fill in the description, trigger conditions, and execution steps |
| 6 | Create scripts | If scripts are needed, run Write Create to the scripts/ directory |
| 7 | Create reference documents | If reference documents are needed, run Write Create to the references/ directory |
| 8 | Validate the 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 documentation。
Output patterns
For detailed output patterns (templates, examples, checklists), see Output patterns documentation。
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: The input and output of the code 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 AI should refer to when working
- Benefits: Keep SKILL.md concise, loading only when needed
assets/
Files not intended to be loaded into context, but used in the output produced 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
| 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 an example
User input: "Create a skill for handling PDFs"
Execution steps:
| Step | Execution action | Specific command/operation |
|---|---|---|
| 1 | Ask about the scenario | Run AskUserQuestion to ask about the specific usage scenario (extracting text, filling forms, merging, etc.) |
| 2 | Plan the content | Analyze the requirements and determine that a Python script is needed to handle PDFs |
| 3 | Initialize the 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 the description | Run SearchReplace to fill in the description as "Handle PDF files. When to use: when the user says to handle a PDF" |
| 6 | Create the processing script | Run Write to create scripts/pdf_extractor.py |
| 7 | Validate the structure | Run RunCommand to execute python scripts/quick_validate.py ./skills/pdf-processor |