在 Skill 体系中，description（技能描述）是技能的触发开关、识别入口与功能简介。它是整个 Skill 中最重要、最影响触发效果的字段，直接决定 TraeCode 智能体在什么场景下启用当前技能。
一、什么是 Skills 描述
Skills 描述是写在 SKILL.md 文件 YAML 头部中的 description 字段，用于简要说明该技能的用途、能力与适用场景。
它是智能体「发现阶段」唯一读取的核心依据，让 AI 快速知道：这个技能是干什么的、什么时候可以用。
二、description 的核心作用
description 不控制具体执行步骤，只负责匹配与触发，拥有三大核心作用：
- 技能识别：会话启动后，TraeCode 只扫描 name 和 description，快速收录所有技能能力。
- 意图匹配：用户发送消息后，AI 通过语义对比 description 判断是否需要激活该技能。
- 精准分流：多个技能共存时，依靠描述关键词区分不同任务，避免技能乱触发、误触发。
三、description 的工作时机（结合渐进式原理）
description 全程参与 Skill 的三层加载机制，是整个流程的入口：
- 发现阶段：仅加载 description 和 name，轻量化注册技能能力。
- 匹配阶段：用户提问命中描述关键词，触发技能激活。
- 执行阶段：匹配成功后，才加载完整 SKILL.md 规则执行任务。
简单理解：description 是敲门砖，正文是施工手册。
四、优质 description 编写规范
想要技能触发稳定、精准，描述必须遵循以下编写标准：
- 功能清晰：一句话说明技能用途，不写废话。
- 关键词齐全：覆盖用户常用口语、指令、英文简写。
- 场景明确：写清什么时候触发、解决什么问题。
- 简洁精炼：不要过长，避免干扰模型匹配。
- 排他性强：避免和其他技能描述高度重合，防止误触发。
五、实战示例对比
较差写法（模糊、无法精准触发）
用于处理骰子相关操作。
标准优质写法（我们课程 roll-dice 规范）
掷骰子技能，用户需要掷骰子、roll d6、roll d20、随机点数、2d6 场景自动触发。调用终端生成真实随机点数。
优点：关键词丰富、场景明确、AI 极易精准匹配。
六、常见问题与原因
- 技能不触发：description 关键词太少、太抽象、不符合用户口语。
- 技能误触发：多个技能描述语义重叠、关键词冲突。
- 触发不稳定：描述过长、语句杂乱，模型无法准确识别意图。
七、总结
Skills 描述（description）是技能的唯一触发入口。它在发现阶段完成技能注册，在匹配阶段完成意图识别，是决定技能能否正常工作的关键字段。精准、简洁、场景化的描述，是写出稳定、好用、专业 Skill 的基础。
0 条笔记