unreal-skill

Unreal スキル

Unreal Engine エージェントスキルを作成します。これは、エージェントが知らない、または特に注意を払う必要がある重要な知識をまとめた、名前付きで再利用可能な指示の集合です。スキルには、ある領域における一般的なベストプラクティス、特定のワークフローに関するガイダンス、またはその両方を含められます。

原則

優れたスキルは、次の性質を備えています。

新規性：内容は、エージェントがすでに知っていることや、ツールを使って学べることではなく、エージェントが知らないことにしてください。ツールを呼び出せば把握できる内容は、スキルに含めないでください。

協調的：ドキュメントを執筆するのではなく、知識のある同僚に説明するように書いてください。読者は Unreal を理解しているものとします。すべての仕組みを詳しく説明するのではなく、読者が作業を進めるために必要な情報を伝えてください。

柔軟性：スキルには、概念的な説明、手順、またはその両方を含められます。ガイダンスが最も明確に伝わる形式を選んでください。

長期的な有用性：時間とともに変わるプロパティ名、ツール名、その他の詳細を埋め込まないでください。特定の API 名を参照するスキルは、その名前が変わると気づかないうちに機能しなくなります。

非依存性：オーケストレーションシステム、ロール名、モデル名、またはエージェントの接続方法には触れないでください。周囲のインフラストラクチャにかかわらず、スキルが機能するようにしてください。

簡潔さ：すべてのトークンがコンテキストを消費します。重要な点に使い、必須でも長期的に役立つものでもない内容は削ってください。なくても困らない文は削除してください。

作成前に確認すること

作成を始める前に、次の質問を確認してください。

1. すでにスキルが存在しますか？ MCP 経由で ListSkills を呼び出して、プロジェクトに登録済みのスキルをすべて確認し、関連するスキルがあれば GetSkills を呼び出してください。必要な機能がすでに網羅されている場合は、新しいスキルを作成するのではなく、既存のスキルをユーザーに案内してください。

2. 実装方法を選んでください。 スキルの配置先に応じて、次の2つの方法があります。

• Python クラス：スキルがコードプラグインの一部である場合に適しています。プラグインの Python ツールセットと同じ場所に配置され、プラグインとともにバージョン管理され、プラグインの読み込み時に自動で登録されます。
• UAsset：スキルがプロジェクト固有で、プラグインに属さない場合に適しています。MCP 経由で CreateSkill を使い、コンテンツブラウザー内に直接作成します。コードは不要です。

構成

Unreal スキルには、2つのフィールドがあります。

Description：スキルの詳細な指示が読み込まれる前に、発見時に読み込まれます。スキルの対象と適用される場面を明確に説明する1～2文を記述してください。

Instructions：スキルの内容です。スキルが有効なときにエージェントが従う実際のガイダンスです。上記の原則に従い、ツールでは学べないことに焦点を当て、必須でない内容は削ってください。

エージェントは、unreal-mcp のメタツール（list_toolsets、describe_toolset、call_tool）を通じて実行時にツールを発見し、呼び出します。そのため、固定のツールセット一覧を指定するのではなく、エージェントが必要なツールを見つけることを前提に指示を作成してください。

Python スキル

Python スキルは、プラグイン内の Python ファイルで定義される UAgentSkill のサブクラスです。スキルがコードプラグインに属し、プラグインとともにバージョン管理される必要がある場合は、この方法を使ってください。

作成

クラスに @agent_skill デコレーターを付け、unreal.AgentSkill を継承してください。「構成」セクションの2つのフィールドは、クラス属性に対応します。

• クラスの docstring は Description になります。1～2文に収めてください。
• instructions は、スキルの有効化時に読み込まれるガイダンスを含むクラス属性の文字列です。

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

登録

スキルはインポート時に登録されます。特に指示がない限り、スキルファイルはプラグインの 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：1～2 文の説明（上記の構成を参照）
• Details：Instructions を含む FAgentSkillDetails

更新：次の値を指定して UpdateSkill を呼び出します。

• SkillPath：スキルの完全なパス。例：/Game/Skills/MyWorkflowSkill.MyWorkflowSkill_C
• Description：修正した説明
• Details：修正した FAgentSkillDetails

作業内容の確認

引き渡す前に、そのパスで GetSkills を呼び出し、スキルが正しく表示されることを確認してください。次に、エージェントに表示される形式で、説明と手順をあわせて確認します。

• 説明：このスキルがいつ適用されるのか、明確に示されていますか？説明だけを読んだエージェントが、特定のタスクでこのスキルを有効にすべきか判断できますか？
• 手順：ツールからは学べない内容をエージェントに教えていますか？コンテキストコストに見合うだけの簡潔さがありますか？