Skill Creator（Skill 编写规范）

本 Skill 定义 如何设计一个高质量、低上下文占用、可复用的 AI Skill。

一、什么是 Skill

Skill 是 面向 AI 的能力包，用于将通用模型约束为某一领域的“专业执行体”。

Skill 用来解决：

“AI 每次都要重新摸索的事”

Skill 能提供什么

•标准化流程：明确多步骤执行顺序
•工具 / API 使用规范：避免重复推理
•领域知识封装：结构、约束、业务规则
•可复用资源：脚本（节省 Token）、参考文档、模板

二、核心设计原则（必须遵守）

1. 极度精简（Context 是稀缺资源）

•默认 AI 已经很聪明：不写常识，不写 AI 能够根据环境自行推理的内容。
•只写「非直观逻辑」：侧重于特定的业务逻辑、内部工具链和特定的工作流。
•优先级：规则＞示例＞描述。

2. 控制自由度

根据任务“脆弱性”选择表达方式：

场景	表达方式	自由度
路径多样、依赖上下文	自然语言指引 (Infinitive)	高
有推荐范式、需标准化	伪代码 / 参数化脚本	中
易出错、结果必须一致	固定脚本 (Scripts)	低

原则：越容易出错，约束越强

三、Skill 目录结构（标准）

text

skill-name/
├── SKILL.md          # 核心指令 (必须)
├── scripts/          # 可执行脚本 (确定性任务)
├── references/       # 参考文档 (大数据量、按需读取)
└── assets/           # 静态资源 (模板、图片、不入上下文)

四、SKILL.md 规范（最重要）

1. Frontmatter

yaml

---
name: xxx
description: 用于 [场景] 的 [功能]。当用户需要 [任务] 时使用。
---

触发逻辑：

•第三人称描述：使用“本 Skill 用于...”而非“你可以用我...”。
•明确触发词：包含用户可能的查询关键词（如：格式化、校验、转换）。

2️⃣ 正文（Body）

•命令式语气：使用动词开头（如：读取、执行、验证），严禁第二人称（你应、请）。
•
结构化设计：
- •# 核心流程：定义 Top-down 的执行步骤。
- •# 关键规则：定义不可逾越的边界（Do's and Don'ts）。
- •# 资源索引：明确说明何时读取 references/ 下的文件。

五、Bundled Resources 进阶指南

scripts/ (确定性与效率)

•节省 Token：长逻辑封装为脚本，AI 只需调用并观察输出。
•一致性：处理文件、转换数据等任务必须使用脚本以消除随机性。

references/ (按需加载)

•延迟加载：SKILL.md 中通过“若涉及 XXX，请读取 references/xxx.md”实现。
•分层设计：核心指令在 SKILL.md，细节手册在 references。

assets/ (最终产物)

•模版复制：用于初始化项目、生成标准报表等。

六、禁止内容 (Negative Constraints)

•禁止出现：README.md, CHANGELOG, INSTALL, 使用说明。
•禁止废话：不写“我会帮助你”、“这是一个非常有用的 Skill”等修饰性语句。
•禁止重复：SKILL.md 与 references 内容不得重叠。

七、Skill 创建流程

Step 1: 需求锚定 (Intent)

•收集 3-5 个真实的用户查询示例。
•确定：用户问什么？AI 应该调用哪个工具？

Step 2: 资源规划 (Resources)

•判断哪些环节 AI 会“反复写同样的代码” (→ scripts)。
•判断哪些文档“太大且不常读” (→ references)。

Step 3: 初始化 (Init)

使用项目内置脚本初始化：

bash

python ./.trae/skills/skill-creator/scripts/init_skill.py <name> --path <dir>

Step 4: 编写与自检 (Write & Check)

•遵循命令式语气编写 SKILL.md。
•自检：如果我（AI）失忆了，只看这个 Skill 能否 100% 复现正确结果？

Step 5: 打包 (Package)

bash

python ./.trae/skills/skill-creator/scripts/package_skill.py <dir>

八、写作强约束

•动词开头：每个条目必须以动词（如：分析、读取、输出）开始。
•零背景说明：直接给指令，不解释为什么要这么做。
•Markdown 优化：多用列表和加粗，少用长段落。