skill-creator-yashu

🎯 触发映射

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

---

创建模式

执行步骤

步骤	执行动作	具体命令/操作
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>

输出结果

成功时输出示例：

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

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

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

失败时输出示例：

❌ Skill 创建失败

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

错误处理

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

核心原则

简洁至上 (Concise is Key)

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

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

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

设置适当的自由度

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

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

AI 友好性 (AI-Friendly)

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

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

优化技巧：

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

Agent Skills 规范要点

目录结构

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

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

SKILL.md 格式

必需的前置元数据：

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

name 字段规则

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

description 字段规则

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

好的示例：

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

不好的示例：

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

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

渐进式披露设计

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

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

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

渐进式披露模式

模式 1：高级指南 + 参考

## 快速开始

[核心代码示例]

## 高级功能

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

模式 2：按领域组织

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

重要指南：

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

SKILL.md 结构模式

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

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

模式可以混合搭配。

Skill 创建流程

按顺序执行以下步骤：

Skill 创建流程

按顺序执行以下步骤：

步骤	执行动作	具体命令/操作
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 修复问题

工作流程模式

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

输出模式

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

捆绑资源

scripts/

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

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

references/

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

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

assets/

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

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

实用脚本

脚本	用途	命令
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>

创建示例

用户输入： "创建一个处理 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