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

Unreal Agent Skills 技能系统详解skill-use 工具如何扩展 AI 智能体能力【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agentUnreal Agentasync-first agent harness由 Unreal Labs 开源内置了一套轻量级Skills 技能系统把特定任务的指令写成SKILL.md文件放进工作区AI 智能体就能通过skill-use 工具按需加载这些技能从而扩展自身能力。本文带你快速理解技能系统的文件结构、注册机制和加载流程帮你为 AI 智能体定制专属技能。一、什么是 Skills 技能系统在 Unreal Agent 中技能Skill就是一份写给 AI 看的专业指令文档。它的核心思想是按需加载层级内容是否常驻上下文技能摘要名称 描述✅ 常驻开销极小技能正文SKILL.md 全文❌ 仅调用 skill-use 后加载这样设计的好处很明显注册 10 个技能也不会撑爆上下文窗口——模型平时只看到每个技能叫什么、能干什么只有任务真正匹配时才把完整指令读进来。技能在代码中被表示为一个三元组定义见 tool.goName技能的唯一名称模型用它来调用技能Description技能描述帮助模型判断什么时候该用Path技能文件SKILL.md的路径二、如何编写一个技能SKILL.md 文件结构技能遵循简单约定每个技能一个目录目录里放一个SKILL.md文件头部用 YAML frontmatter 声明元数据--- name: review description: 按团队规范审查代码变更 --- 这里是给 AI 的详细操作指令……框架通过 registry.go 中的DiscoverSkills函数自动发现技能扫描目录下所有*/SKILL.md文件解析 frontmatter 中的name与description字段解析逻辑见 parseSkillFrontmatter校验必填字段并拒绝重名技能单个文件出错不会中断其他技能的加载。⚠️ 两个易踩的坑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.mdReady → Awaiting → Completed读取完成即把文件内容交还给模型失败或取消则把错误信息作为结果返回。第 4 步结果回传。TranslateResultskill_use.go把读取到的技能正文格式化后返回给模型模型随后按指令执行任务。 注意细节若技能读取尚未完成模型会收到 Skill is loading. 的占位回复保证异步流程下交互体验一致。四、技能如何进入模型上下文技能列表通过上下文构建器注入提示词。contextbuilder/skills.go 会取嵌入的引导语 skill-preamble.md把所有已注册技能序列化成available_skillsXML 清单含 name / description / location引导语与清单拼接后插入模型输入。引导语同时教会模型两条使用规则任务匹配描述时才加载技能技能文件中出现相对路径时要基于技能目录解析成绝对路径再调用其他工具。五、运行器中的技能注册流程在命令入口 agentrunner/run.go 中技能系统的启动逻辑体现了零配置设计从工作区的.harness/skills目录自动发现技能只有发现到至少一个技能时才会把 SkillUse 工具加入可用工具列表——没有技能就不暴露这个工具避免干扰模型逐个调用RegisterSkill注册重复路径或名称会直接报错终止。注册接口支持随时增删技能Registry 接口 提供RegisterSkill/UnregisterSkill/Skills因此宿主程序可以为不同会话动态挂载不同技能集。六、关键源码导航模块文件说明技能发现与注册harness/tool/registry.goDiscoverSkills、RegisterSkillskill-use 翻译器harness/tool/skill_use.go参数校验与结果格式化工具 Schema 定义harness/tool/static.goBash / ViewImage / SkillUse技能加载操作harness/operation/skill_use.go异步分块读取状态机上下文注入harness/contextbuilder/skills.go技能清单进提示词引导提示词harness/contextbuilder/prompts/skill-preamble.md技能使用规则运行器装配cmd/internal/agentrunner/run.go技能目录扫描与注册测试用例harness/tool/skills_test.go技能发现的边界情况七、上手清单在 AI 智能体的工作区创建.harness/skills/技能名/SKILL.md写好 frontmattername description和正文指令启动 agent runner确认没有skill error输出给智能体布置与技能描述匹配的任务观察它自动调用SkillUse加载技能并执行需要调整行为时直接修改 SKILL.md 即可——技能即文档改文档就是改行为。整套 Skills 技能系统的设计哲学可以概括为一句话用 Markdown 给 AI 装插件用 skill-use 工具实现零成本的按需扩展。【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考