# EMQXエージェントスキルの管理

デプロイメントレベルのスキルは、エージェントの種類を作成するための再利用可能なMarkdownガイドです。エージェントの目的、トリガー、データソース、ツールの使用方法、および出力要件を記述します。チャット内でスキルを参照することで、異なるトピック、設定、出力要件を持つ類似のエージェントを作成できます。

たとえば、スキルは以下のようなエージェントの作成方法を記述できます。

- デバイスのオフラインイベントを監視し、アラートの要約を生成する。
- EMQX Tablesからテレメトリデータをクエリし、日次レポートを生成する。
- MQTTトピックをリッスンして異常を検知し、標準的なアクションを実行する。
- チーム定義のフォーマットで原因分析レポートを作成する。

スキルは現在の会話をガイドします。スキルを参照しても直接エージェントが作成・デプロイされるわけではありません。生成されたエージェント定義を確認し、検証後にデプロイする必要があります。スキルはコネクター、ツール、権限を追加せず、エージェントの指示を置き換えることもありません。

デプロイメントレベルのスキルは、デプロイされたエージェントにバンドルされているスキルとは異なります。スキルを参照してもアップロード済みの`SKILL.md`ファイルが自動的にデプロイ済みエージェントに追加されることはありません。デプロイメントレベルのスキルは左側ナビゲーションメニューの**Skills**から管理します。バンドルされたエージェントスキルはエージェント詳細ページで読み取り専用のままです。

## 前提条件

デプロイメントレベルのスキルを管理または使用する前に：

- EMQX Agentsデプロイメントを作成し、**Running**状態であることを確認してください。
- デプロイメントのスキルを閲覧する権限があることを確認してください。

スキルはデプロイメント管理と同じロール権限を使用します：

| メンバーロール | スキルの権限 |
|---|---|
| **Administrator** | スキルの閲覧、アップロード、削除、置換が可能。 |
| **Project Administrator** および **Project User** | 許可されたプロジェクト内でスキルの閲覧、アップロード、削除、置換が可能。 |
| その他のデプロイメントアクセス権を持つメンバー | 読み取り専用アクセス。 |

Consoleでスキルを更新するには、一度削除してから修正版の`SKILL.md`をアップロードしてください。読み取り専用ユーザーは、許可されたチャット内でのみスキルを参照できます。プロジェクトアクセスの詳細は[Roles and Permissions](../feature/user.md#roles-and-permissions)を参照してください。

## エージェント作成ワークフローの再利用

エージェント作成時に生成されたスキルを再利用するか、自分でスキルを書いてエージェントの作成方法を定義できます。

### 生成されたスキルの再利用

1. チャットを開始し、作成したいエージェントを説明します。
2. 生成されたエージェント定義を確認し、フォローアップメッセージで要件に合うまで調整します。
3. 検証後、[エージェントをデプロイ](./chats.md#deploy-an-agent-from-a-chat)します。
4. エージェント詳細ページの[Skillsタブ](./agents.md#skills-tab)を開き、生成された`SKILL.md`ファイルを選択してダウンロードします。
5. ダウンロードしたファイルをデプロイメントの**Skills**ページに[アップロード](#upload-a-skill)します。
6. 類似のエージェントを作成する際に、チャットで[スキルを参照](#create-an-agent-with-a-skill)し、エージェント名、MQTTトピック、閾値、出力要件などの違いを説明します。

### 独自スキルの作成

生成されたエージェントが要件を満たさない場合、エージェントの目的、トリガー、データソース、ツール、動作、出力フォーマットを指定する`SKILL.md`ファイルを作成できます。ファイルをアップロードし、その後のチャットで参照して作成要件を再利用します。完全な`SKILL.md`の例は[スキルファイルの準備](#prepare-a-skill-file)を参照してください。

## スキルファイルの準備

UTF-8エンコードのMarkdownファイルを1つ、名前は必ず`SKILL.md`としてください。ファイルサイズは64 KiBを超えてはいけません。

以下の例は、デバイスのオフラインイベントの急増を検知するエージェントの作成方法を記述しています。エージェント完成前に要求するデータや設定を指定しています。内容を`SKILL.md`として保存し、ワークフローに合わせて適宜修正してください。

```markdown
---
name: device-offline-monitor
description: Create an agent that detects spikes in device offline events and produces an MQTT operations alert.
---

# Device Offline Monitor Agent

## Goal

Create an agent that monitors device status messages, detects an unusual increase in offline events, and produces a concise operations alert.

## Trigger and Data

1. Use an MQTT event trigger for `factory/+/device/+/status`.
2. Treat a message with `status = offline` as an offline event.
3. Query the latest 15 minutes of device status history from EMQX Tables for historical comparison.

## Agent Behavior

1. Group offline events by factory and production line using the data mappings provided by the user.
2. Compare the number of offline events in the current five-minute window with the recent baseline.
3. Report only when the event count exceeds the configured threshold.
4. Include the affected devices, time range, likely cause, and recommended next action.

## Configuration to Request

- MQTT topic filter and required connectors.
- EMQX Tables table and data mappings for factory, production line, device, status, and timestamp.
- Offline-event count threshold.
- Comparison window and baseline window.
- Output language and alert destination.

## Output Format

Return a short alert with these sections: Summary, Evidence, Affected Devices, Likely Cause, and Recommended Action.

## Guardrails

Do not claim that a device is offline without an MQTT event or matching historical data. Ask for missing connectors, topic, data mappings, threshold, or alert-destination details before finalizing the agent.
```

ConsoleはZIPファイルやディレクトリのアップロードをサポートしていません。既に存在するスキル名のアップロードは拒否されます。

## デプロイメントレベルスキルの表示

左側ナビゲーションメニューの**Skills**をクリックします。Skillsページにはアップロード済みスキルの**Name**、**Description**、**Size**、**Updated At**が一覧表示されます。

![デプロイメントレベルスキル管理用Skillsページ](./_assets/agents_skills_page.png)

スキル名をクリックすると詳細が開きます。詳細ドロワーからは以下が可能です。

- レンダリング済みMarkdownのプレビュー表示
- Markdownソースの表示
- 表示内容の更新
- `SKILL.md`ファイルのダウンロード

![SKILL.mdのMarkdownプレビューを表示したスキル詳細ドロワー](./_assets/agents_skill_details.png)

## スキルのアップロード

1. **Skills**ページで**Upload Skill**をクリックします。
2. `SKILL.md`ファイルをアップロード領域にドラッグするか、クリックしてファイルを選択します。
3. 選択したファイルが`SKILL.md`でUTF-8エンコードかつ64 KiB以下であることを確認します。
4. **Confirm**をクリックします。
5. スキルがSkillsテーブルに表示されることを確認します。

アップロードされたスキルは同じデプロイメント内のチャットで即座に選択可能になります。既存のスキル名と重複するアップロードは拒否されます。スキルを更新する場合は、一度削除してから修正版の`SKILL.md`をアップロードしてください。

![SKILL.mdを選択してアップロードするUpload Skillダイアログ](./_assets/agents_upload_skill.png)

## スキルの削除

1. **Skills**ページで該当スキルの**Actions**列にある削除アイコンをクリックします。
2. ダイアログで削除を確認します。

削除後、そのスキルは候補リストに表示されなくなり、現在のデプロイメントの新規実行で読み込まれなくなります。過去のメッセージは元の`/skill-name`テキストを保持します。スキル削除は他のEMQX Agentsデプロイメントのスキルやチャットには影響しません。

## スキルを使ったエージェントの作成

デプロイメントレベルのスキルは、**Overview**ページの最初のチャット、新規メッセージの**Chats**ページ、または過去のユーザーメッセージ編集時の応答再生成時に参照できます。

スキルを参照するには：

1. メッセージの先頭または空白の後に`/`とスキル名の一部（例：`/device`）を入力します。
2. 候補リストからスキルを選択します。候補にはスキル名と説明が表示されます。
3. このエージェントの要件（スキル例との違いを含む）を説明し、メッセージを送信します。

キーボード操作でも候補を選択可能です：

- 上矢印キーまたは下矢印キーでリストを移動
- EnterキーまたはTabキーでスキルを選択
- Escapeキーでリストを閉じる

![チャット入力で該当スキルがない状態](./_assets/agents_reference_skill_in_chat.png)

選択したスキル参照はメッセージ内に残り、ハイライトされます。例えば、オフライン監視スキルを冷蔵倉庫用にステータストピックや英語アラートに変更して適用する例：

![device-offline-monitorスキル参照がハイライトされたチャット入力](./_assets/agents_selected_reference_skill.png)

1つのメッセージで複数スキルを参照可能です。同じスキルが複数回参照されても、EMQX Agentsは1回だけ選択し、最初の出現順に読み込みます。

生成されたエージェント定義を確認し、チャットで要求される不足情報を提供してください。定義が要件を満たし検証に合格したら、[エージェントをデプロイ](./chats.md#deploy-an-agent-from-a-chat)します。

## スキルの適用範囲の理解

スキル参照は、現在のメッセージから作成または再生成されたチャット実行にのみ適用されます。その会話内でのエージェント作成・変更をガイドし、デプロイ済みエージェントを自動的に変更することはありません。稼働中のエージェントを更新するには、変更内容を確認し、[チャットから再デプロイ](./chats.md#redeploy-from-a-chat)してください。

スキル参照のルールは以下の通りです：

- EMQX Agentsは、現在のデプロイメントに存在し、メッセージ送信時に認識されたスキルのみを読み込みます。
- 選択したスキルは次のメッセージに自動適用されません。
- スキルリストが読み込み中に手動で`/skill-name`を入力すると、プレーンテキストとして送信されます。入力はリストの読み込み完了や自動選択を待ちません。
- 不明なスキル名や`/path`のような通常のパスはプレーンテキストのままです。単語の途中のスラッシュはスキル参照を開始しません。
- 過去のメッセージを編集する際は、応答再生成前にスキル参照を確認・調整してください。新しい実行は編集済みメッセージのスキルを使用します。
- 応答を再生成すると、EMQX Agentsは選択されたスキルの現在の内容を使用します。スキルが元のメッセージ時から変更されている場合、再生成結果は異なる可能性があります。

現在のデプロイメントに`/`以降のテキストに一致するスキルがない場合、メニューに**No matching skills**と表示されます。

## スキルの問題解決

| 状況 | 動作および対応 |
|---|---|
| ファイル名が`SKILL.md`でない | Consoleがアップロード前に拒否します。ファイル名を変更して再試行してください。 |
| 複数ファイルが選択されている | Consoleが選択を拒否します。`SKILL.md`ファイルを1つだけアップロードしてください。 |
| ファイルサイズが64 KiBを超えている | Consoleがファイルを拒否します。64 KiB以下にサイズを縮小してください。 |
| スキル内容が無効 | アップロードに失敗します。表示されたエラーメッセージに従って修正し、再アップロードしてください。 |
| 同名のスキルが既に存在する | Consoleがアップロードを拒否します。既存スキルを削除してから修正版をアップロードしてください。 |
| ロールがスキルの読み取り専用アクセスのみ | Administrator、Project Administrator、またはProject Userに依頼してスキルのアップロード、削除、置換を行ってもらってください。 |
| サービスが利用不可でスキル操作に失敗 | デプロイメントが稼働中か確認し、再試行してください。 |
| 参照スキルが削除または無効で再生成に失敗 | メッセージを編集して参照を削除するか、利用可能なスキルを選択して再試行してください。 |
| 1メッセージで選択した`SKILL.md`ファイルの合計サイズが256 KiBを超える | 実行を開始できません。選択スキル数を減らすか内容を縮小して再試行してください。 |

## デプロイメントレベルスキルの制限

| 項目 | 制限 |
|---|---|
| ファイル | 1回のアップロードにつきUTF-8エンコードの`SKILL.md`ファイル1つのみ。 |
| ファイルサイズ | 64 KiB以下。 |
| 1メッセージあたりの合計サイズ | 選択した`SKILL.md`ファイルの合計サイズは256 KiB以下。 |
| アーカイブ・ディレクトリ | ZIPファイルやディレクトリのアップロードは非対応。 |
| 重複名 | 既存のスキル名と重複するアップロードは拒否。 |
| スコープ | スキルはアップロードされたEMQX Agentsデプロイメント内でのみ利用可能。必要な各デプロイメントに個別にアップロードしてください。 |
| 権限 | スキルはデプロイメント管理の権限を使用。管理可能なロールは[前提条件](#前提条件)を参照。 |

## 次のステップ

- [チャットの開始と管理](./chats.md)
- [エージェントの管理](./agents.md)
- [コネクターの管理](./connectors.md)