企业官网建设流程全解析

Unreal Agent Skills 技能系统详解：skill-use 工具如何扩展 AI 智能体能力

【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agent

Unreal Agent（async-first agent harness，由 Unreal Labs 开源）内置了一套轻量级Skills 技能系统：把特定任务的指令写成SKILL.md文件放进工作区，AI 智能体就能通过skill-use 工具按需加载这些技能，从而扩展自身能力。本文带你快速理解技能系统的文件结构、注册机制和加载流程，帮你为 AI 智能体定制专属技能。

一、什么是 Skills 技能系统？

在 Unreal Agent 中，技能（Skill）就是"一份写给 AI 看的专业指令文档"。它的核心思想是按需加载：

这样设计的好处很明显：注册 10 个技能也不会撑爆上下文窗口——模型平时只看到每个技能"叫什么、能干什么"，只有任务真正匹配时才把完整指令读进来。

技能在代码中被表示为一个三元组，定义见 tool.go：

• Name：技能的唯一名称，模型用它来调用技能
• Description：技能描述，帮助模型判断"什么时候该用"
• Path：技能文件（SKILL.md）的路径

二、如何编写一个技能：SKILL.md 文件结构

技能遵循简单约定：每个技能一个目录，目录里放一个SKILL.md，文件头部用 YAML frontmatter 声明元数据：

--- name: review description: 按团队规范审查代码变更 --- 这里是给 AI 的详细操作指令……

框架通过 registry.go 中的DiscoverSkills函数自动发现技能：

1. 扫描目录下所有*/SKILL.md文件；
2. 解析 frontmatter 中的name与description字段（解析逻辑见 parseSkillFrontmatter）；
3. 校验必填字段并拒绝重名技能，单个文件出错不会中断其他技能的加载。

⚠️ 两个易踩的坑：name 和 description 都必填，且所有技能名称不能重复，否则该技能会被跳过并输出skill error>提示。

三、skill-use 工具：AI 如何按需调用技能

SkillUse是三大静态工具之一（与 Bash、ViewImage 并列），其工具定义在 static.go 中，描述就一句话：

Load the instructions for a registered skill.

它只接收一个参数name——要加载的技能名。一次完整的调用流程如下：

第 1 步：模型发起调用。模型判断任务与某技能匹配，输出SkillUse工具调用。

第 2 步：翻译器校验。skillUseTranslator在 skill_use.go 中验证参数：技能名必须存在、且是已注册的技能；校验通过后创建一个skill_use操作并提交给操作管理器。

第 3 步：异步读取文件。操作状态机（operation/skill_use.go）驱动分块读取 SKILL.md：Ready → Awaiting → Completed，读取完成即把文件内容交还给模型；失败或取消则把错误信息作为结果返回。

第 4 步：结果回传。TranslateResult（skill_use.go）把读取到的技能正文格式化后返回给模型，模型随后按指令执行任务。

💡 注意细节：若技能读取尚未完成，模型会收到 "Skill is loading." 的占位回复，保证异步流程下交互体验一致。

四、技能如何进入模型上下文

技能列表通过上下文构建器注入提示词。contextbuilder/skills.go 会：

1. 取嵌入的引导语 skill-preamble.md；
2. 把所有已注册技能序列化成<available_skills>XML 清单（含 name / description / location）；
3. 引导语与清单拼接后插入模型输入。

引导语同时教会模型两条使用规则：任务匹配描述时才加载技能；技能文件中出现相对路径时，要基于技能目录解析成绝对路径再调用其他工具。

五、运行器中的技能注册流程

在命令入口 agentrunner/run.go 中，技能系统的启动逻辑体现了"零配置"设计：

• 从工作区的.harness/skills目录自动发现技能；
• 只有发现到至少一个技能时，才会把 SkillUse 工具加入可用工具列表——没有技能就不暴露这个工具，避免干扰模型；
• 逐个调用RegisterSkill注册，重复路径或名称会直接报错终止。

注册接口支持随时增删技能（Registry 接口 提供RegisterSkill/UnregisterSkill/Skills），因此宿主程序可以为不同会话动态挂载不同技能集。

六、关键源码导航

七、上手清单

1. 在 AI 智能体的工作区创建.harness/skills/<技能名>/SKILL.md，写好 frontmatter（name + description）和正文指令；
2. 启动 agent runner，确认没有skill error>输出；
3. 给智能体布置与技能描述匹配的任务，观察它自动调用SkillUse加载技能并执行；
4. 需要调整行为时，直接修改 SKILL.md 即可——技能即文档，改文档就是改行为。

整套 Skills 技能系统的设计哲学可以概括为一句话：用 Markdown 给 AI 装"插件"，用 skill-use 工具实现零成本的按需扩展。

【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agent