SKILL.md 是 AI 智能体技能体系的唯一核心文件，是定义 Skill 能力、触发规则、执行流程、输出规范的标准配置文件。所有 TraeCode 可识别的技能，本质上都是依靠标准化的 SKILL.md 文件实现自动化工作。可以说：一个 Skill 的全部逻辑，都由 SKILL.md 定义。
一、SKILL.md 的作用
SKILL.md 是技能的“说明书+执行手册”，用来告诉 AI 智能体：什么时候触发、要做什么、怎么做、输出什么格式。
主要作用：
- 定义技能唯一标识与基础信息
- 设置技能触发条件与匹配关键词
- 规范 AI 的执行步骤与工作流程
- 统一输出格式，避免模型自由发挥
- 支撑 TraeCode 渐进式加载机制
二、SKILL.md 文件结构组成
标准 SKILL.md 文件分为两大模块：YAML 头部元信息 和 Markdown 规则正文，两者缺一不可。
1. YAML 头部元信息（识别层）
位于文件最顶部，被 --- 包裹，用于插件扫描、发现、匹配技能，决定技能能否被识别、能否触发。
核心字段：
- name：技能唯一名称，必须和技能文件夹名完全一致
- description：触发关键词描述，决定用户什么指令可以激活技能
- version：技能版本号，用于迭代管理
- author：作者信息
这部分是轻量扫描阶段读取的内容，常驻内存、极低消耗。
2. Markdown 正文规则（执行层）
正文是技能真正的工作逻辑，在技能被触发后才会完整加载。用于约束 AI 的行为，保证任务标准化执行。
通用正文结构：
- 任务目标：说明本技能要解决什么问题
- 触发场景：明确哪些用户指令会启用技能
- 执行步骤：AI 必须严格遵守的操作流程
- 执行命令/资源：终端指令、模板、样例、脚本依赖
- 输出规范：限定返回格式、语言、样式
三、SKILL.md 命名与目录规范
想要被 TraeCode 正常识别，必须遵守两条硬性规范：
- 文件名必须为 SKILL.md（大写、固定拼写）
- 存放路径必须在
.agents/skills/技能名/目录下 - 文件夹名必须与 YAML 中的 name 字段完全一致
规范错误会直接导致：技能扫描不到、无法触发、执行失效。
四、SKILL.md 的运行机制
SKILL.md 完美配合 Skill 渐进式加载原理 工作：
- 发现阶段：插件只读取 YAML 头部信息，轻量化扫描所有技能
- 激活阶段：用户指令匹配 description，加载完整 SKILL.md 正文
- 执行阶段：AI 严格按照正文步骤完成任务
相比普通 Prompt，SKILL.md 实现了可保存、可复用、可迭代、低消耗的工程化能力。
五、SKILL.md 的优势
- 标准化：统一结构、统一规则，人人可看懂、可维护
- 可复用：一次编写，永久生效，多对话复用
- 高稳定：强制流程执行，减少 AI 幻觉与随意回答
- 可迭代：可随时修改、升级、扩展功能
- 工程化：支持版本管理、团队共享、项目统一管理
六、总结
SKILL.md 是 AI 技能体系的核心载体，是智能体实现自动化任务的标准配置文件。YAML 头部负责“被发现、被触发”，正文规则负责“怎么做、怎么输出”。掌握 SKILL.md 的结构与规范，是开发、使用、自定义所有 AI 技能的基础。
0 条笔记