Skills 参数传递与接收

基础 Skill 只能执行固定指令，而真正实用、可复用的智能体技能，都支持动态参数传递与接收。Skills 参数机制允许用户输入自定义内容，让同一套技能逻辑根据不同参数执行不同结果，实现一次开发、多次复用、动态适配。

本文结合 TraeCode 运行机制、roll-dice 掷骰子案例，讲解 Skill 参数的定义、传递、接收、替换与执行全流程。

一、什么是 Skill 参数

Skill 参数是技能中预留的动态占位变量，用于接收用户输入的自定义数据。

例如掷骰子场景：骰子面数、骰子数量是不固定的，用户可以输入 1d6、2d6、1d20。其中 骰子面数、骰子数量 就是动态参数。

简单区分：

• 固定逻辑：技能执行流程、输出格式（写死在 SKILL.md）
• 动态参数：用户每次调用时自由传入的变量（动态替换）

二、参数传递的核心作用

如果没有参数机制，每一种骰子类型都需要单独写一个技能，代码冗余、无法复用。参数机制解决了这一问题：

• 实现技能通用化：一个技能适配无数种场景
• 支持用户自定义输入，灵活性大幅提升
• 减少重复开发，符合工程化思想
• 配合终端命令、脚本扩展，实现动态自动化执行

三、Skill 参数的标准格式

在标准 Skill 体系中，参数使用尖括号占位符定义：

<参数名>

在 roll-dice 案例中，核心参数为：<sides>（骰子面数）。

示例原始命令模板：

Get-Random -Minimum 1 -Maximum <sides>

其中 <sides> 是等待用户传入、动态替换的参数变量。

四、参数传递与接收完整流程

Skill 参数工作完全依托渐进式加载机制运行，分为 5 个标准步骤：

1. 参数定义（开发者阶段）

开发者在 SKILL.md 的执行命令或脚本中预留占位参数，声明需要接收的动态变量。

2. 用户传入参数（调用阶段）

用户自然语言输入，携带自定义参数数据，例如：帮我掷一个 d20 骰子。TraeCode 智能体自动识别出用户需要 20 面 的骰子。

3. 参数解析（匹配阶段）

技能激活后，AI 解析用户意图，提取有效参数值：sides = 20。

4. 参数替换（执行阶段）

系统将文档中的占位符 <sides> 替换为真实数值，命令从模板变为可执行真实指令：

模板命令 → Get-Random -Minimum 1 -Maximum 20

5. 执行并返回结果

终端或脚本执行替换后的真实代码，按规范输出结果。

五、多参数传递扩展（进阶）

Skill 支持同时传递多个参数。例如掷骰子 2d6 场景包含两个参数：

• <count>：骰子数量
• <sides>：骰子面数

多参数机制让技能可以实现更复杂的批量运算、多条件判断，是高级自动化技能的核心基础。

六、参数传递的优势

• 高复用：一套模板适配无数参数场景
• 轻量化：无需修改技能文件，仅改变传入参数即可变更结果
• 智能化：AI 自动解析用户口语参数，无需用户手动输入代码
• 可扩展：可配合脚本实现复杂参数校验、参数计算、异常处理

七、常见参数问题排查

• 参数不生效：占位符书写错误、未使用尖括号格式
• 参数识别错误：description 关键词不全，导致 AI 无法正确解析参数
• 执行报错：用户传入非法参数（负数、0、非数字），无参数校验逻辑

八、总结

Skills 参数传递与接收是智能体技能动态化、通用化、工程化的关键能力。通过在技能中预留占位参数，AI 可以自动解析用户输入、动态替换指令、执行差异化逻辑。

固定规则保证技能稳定，动态参数保证技能灵活，二者结合，让 Skill 从“固定工具”升级为“可自适应的智能自动化能力”。