unreal-skill

Unreal Skill

你正在编写 Unreal Engine Agent Skill：一种命名且可复用的指令包，用于封装 Agent 不知道或需要特别留意的关键知识。Skill 可以提供某个领域的一般最佳实践、针对特定工作流的指导，也可以兼而有之。

原则

优秀的 Skill 应当：

新颖：内容应当是 Agent 原本不知道、或无法通过使用工具学到的知识。如果 Agent 可以通过调用工具自行弄清楚，就不要把它放进 Skill。

协作：像向一位知识渊博的同事介绍情况一样编写，而不是撰写文档。假设读者了解 Unreal。提供他们采取行动所需的信息，而不是完整解释一切的工作原理。

灵活：Skill 可以包含概念说明、分步操作指南，也可以兼有两者。选择最能清晰指导任务的形式。

持久：不要嵌入属性名称、工具名称或其他会随时间变化的细节。引用特定 API 名称的 Skill 会在这些名称变更时悄然失效。

独立：不要提及编排系统、角色名称、模型名称，也不要提及 Agent 的连接方式。无论周边基础设施如何，Skill 都应当适用。

精简：每个 token 都会占用上下文。把内容放在最重要之处，删去非必要或不会过时的内容。如果删掉一句话也不会有人注意到，就删掉它。

编写之前

开始编写前，先逐一思考以下问题。

1. 这个 Skill 已经存在吗？ 通过 MCP 调用 ListSkills，查看项目中所有已注册的 Skill，然后对相关 Skill 调用 GetSkills。如果已有 Skill 涵盖该能力，请引导用户使用现有 Skill，而不是创建新的 Skill。

2. 选择实现路径。 有两种路径，具体选择取决于 Skill 的归属：

• Python 类：适用于作为代码插件一部分的 Skill。它与插件的 Python 工具集位于同一位置，由插件进行版本控制，并在插件加载时自动注册。
• UAsset：适用于项目专属且不属于插件的 Skill。通过 MCP 使用 CreateSkill，直接在 Content Browser 中创建。无需编写代码。

结构

每个 Unreal Skill 都有两个字段。

Description：在读取 Skill 的完整指令之前，于发现阶段加载。用一到两句话清晰描述该 Skill 涵盖的内容及适用时机。

Instructions：Skill 的内容，即 Skill 激活时 Agent 遵循的实际指导。遵循上述原则：聚焦于工具无法教会的内容，删去所有非必要信息。

Agent 会在运行时通过 unreal-mcp 元工具（list_toolsets、describe_toolset、call_tool）发现并调用工具，因此编写指令时应假设 Agent 会自行找到所需工具，而不是列出固定的工具集。

Python Skills

Python Skill 是在插件中的 Python 文件里定义的 UAgentSkill 子类。当 Skill 属于代码插件且应由插件进行版本控制时，使用此路径。

编写

使用 @agent_skill 装饰类，并继承 unreal.AgentSkill。结构部分提到的两个字段对应类属性：

• 类文档字符串会成为 Description。保持在一到两句话。
• instructions 是类属性字符串，包含 Skill 激活时加载的指导。

import unreal

from toolset_registry.agent_skill import agent_skill

_INSTRUCTIONS = (
    'Do X before Y, because Z.\n'
    'Always verify the result after performing the operation.\n'
)

@agent_skill
class MySkill(unreal.AgentSkill):
    """Provides guidance on doing X in Unreal Engine.
    Apply this skill whenever the user wants to accomplish X."""

    instructions = _INSTRUCTIONS

注册

Skill 会在导入时自行注册。除非另有说明，否则请将 Skill 文件放在插件 Python 包内的 skills/ 子文件夹中，在该子文件夹的 __init__.py 中显式导入每个文件，并确保 init_unreal.py 导入 skills 包。

重新加载

编辑 Python 技能后，请先重新加载插件包再进行验证，否则编辑器不会获取更改。在 Edit → Project Settings → Plugins → Python → Enable Remote Execution 中启用 Remote Execution，然后运行：

python Engine/Plugins/Experimental/ToolsetRegistry/Content/Python/toolset_registry/tests/reload_remote.py your_plugin

UAsset 技能

UAsset 技能是保存为 Content Browser 资产的 UAgentSkill 实例。对于不属于插件且无需代码的项目专属技能，请使用此方式。

编写

通过 MCP 使用 AgentSkillToolset。首先调用 ListSkills 查看现有技能，然后创建或更新：

创建：调用 CreateSkill，并提供：

• FolderPath：Content Browser 文件夹，例如 /Game/Skills/
• AssetName：PascalCase 名称，例如 MyWorkflowSkill
• Description：一到两个句子（参见上文的结构）
• Details：包含 Instructions 的 FAgentSkillDetails

更新：调用 UpdateSkill，并提供：

• SkillPath：技能的完整路径，例如 /Game/Skills/MyWorkflowSkill.MyWorkflowSkill_C
• Description：修订后的描述
• Details：修订后的 FAgentSkillDetails

检查你的工作

交付前，调用技能路径上的 GetSkills，确认技能看起来正确。然后一起阅读描述和说明，了解 Agent 将如何看到它们：

• 描述：是否清楚说明了此技能适用的情况？只阅读描述的 Agent 能否判断是否应针对给定任务启用此技能？
• 说明：是否传授了 Agent 无法从工具中学到的内容？是否足够简短，值得占用上下文？