Skills 触发机制

Skills 触发机制是 AI 智能体技能体系的核心调度规则，决定了 TraeCode 在何时、何种条件下、启用哪一个技能。Skill 不会一直运行，也不会随意触发，而是基于意图匹配、按需激活的机制工作。掌握触发机制，是写出稳定、精准、低误判技能的关键。

一、触发机制核心原理

Skills 触发遵循官方核心规则：先扫描元数据、再语义匹配、匹配成功才加载完整技能。

TraeCode 不会一次性加载所有技能完整内容，只会在用户提问命中技能描述后，才动态加载、激活、执行技能。这也是渐进式加载机制在“触发层面”的具体体现。

二、触发的两大核心依据

1. 技能描述 description（自动触发核心）

YAML 头部的 description 字段是自动触发的唯一入口。它定义了技能的功能、适用场景、关键词。AI 通过语义理解用户提问，判断用户需求是否与当前技能能力匹配。

description 关键词越全面、场景越清晰，触发越精准。

2. 正文触发场景规则（执行约束）

SKILL.md 正文中的“触发场景”用于进一步约束使用范围，明确：

• 哪些用户指令可以触发
• 哪些场景禁止触发

双层约束可以大幅降低误触发、乱触发概率，让技能执行更稳定。

三、两种触发方式（完整分类）

1. 自动触发（隐式触发）

用户使用自然语言提问，无需指定技能名，AI 自动识别意图并匹配技能。

示例：用户输入 “帮我掷骰子”，自动匹配 roll-dice 技能。

特点：智能、人性化、适合日常使用，依赖 description 精准度。

2. 手动精准触发（显式触发）

用户通过 @技能名 强制指定技能运行，跳过语义匹配，直接激活目标技能。

示例：@roll-dice 1d20

特点：强制、稳定、零误判，适合测试、精准调用、自动化场景。

四、完整触发执行流程（四阶段）

Skill 从等待状态到最终执行，严格遵循四步触发逻辑：

1. 扫描注册阶段

会话启动，TraeCode 扫描 .agents/skills 目录，读取所有技能 name、description，生成技能能力清单，全程轻量化、不加载正文与脚本。

2. 意图匹配阶段

用户发送指令，AI 语义分析用户需求，对比所有技能描述，筛选出最匹配的单个技能。

若无匹配项，不触发任何技能，使用模型默认回答。

3. 技能激活阶段

匹配成功后，系统按需加载完整 SKILL.md，锁定执行规则、步骤、输出规范，禁止模型自由发挥。

4. 任务执行阶段

按照技能规则执行终端命令、脚本逻辑或业务流程，最终输出标准化结果。

五、触发机制关键特性

• 按需触发：技能不常驻内存，只有匹配成功才加载，资源消耗极低。
• 唯一触发：同一时间只会匹配最贴合的一个技能，避免多技能冲突。
• 智能语义触发：支持口语化、多样化用户指令，不需要固定命令词。
• 分层约束：头部描述负责匹配、正文场景负责校验，双层保障精准触发。

六、常见触发问题与原因

• 技能不触发：description 关键词过少、场景描述模糊、用户语句不匹配。
• 技能误触发：多个技能描述重叠、无排他场景、语义冲突。
• 触发不稳定：描述语句过长、逻辑混乱，模型无法精准识别意图。
• 加载不生效：目录不规范、文件名错误、name 与文件夹不一致。

七、如何写出高精准触发的技能

• description 覆盖高频口语关键词与英文简写
• 明确技能专属场景，避免与其他技能语义重叠
• 正文区分“可用场景”和“不可用场景”
• 测试多组口语指令，保证触发稳定、零误判

八、总结

Skills 触发机制的本质是语义匹配 + 按需加载 + 精准调度。依靠 YAML 描述完成智能匹配，依靠正文规则完成执行约束，结合渐进式加载实现高效、稳定、低消耗的技能调度。

熟练掌握触发机制，是开发稳定可用、可工程化、可批量扩展 AI 技能的核心基础。