Skill スキルモジュール

Skill とは？

Skill（スキル）は、MaiAgent プラットフォームにおいて AI アシスタントの専門能力をパッケージ化するためのモジュール化された仕組みです。LLM が単一のツールを呼び出す Function Calling とは異なり、Skill は一組の指示（Instructions）、ツール（Tools）、**リソースファイル（Resources）**を再利用可能な能力ユニットとしてパッケージ化します。これにより、AI アシスタントは対話の中で完全なタスク実行フローを動的に展開できるようになります。

簡潔にまとめると、次のとおりです。

• Function Calling／ツール：LLM が単一の API または関数を呼び出します

• Skill：LLM が一連の SOP 指示を展開し、フローの中で必要に応じて複数のツールを呼び出します

スキル（Skill）= 指示（Instructions）+ ツール（Tools）+ リソース（Resources）

---

Skill の動作原理

動作フロー

ユーザーが質問
    │
    ▼
AI アシスタントがメッセージを受信
    │
    ▼
LLM が意図を分析し、紐付け済みスキルの説明と照合
    │
    ├─ スキルにマッチ → SkillExpandTool を呼び出し
    │                    │
    │                    ▼
    │              スキルの完全な指示内容を展開
    │              + 利用可能な付属ツールを列挙
    │                    │
    │                    ▼
    │              LLM が指示に従って段階的に実行
    │              必要に応じて LoadSkillTool を呼び出しツールを読み込み
    │                    │
    │                    ▼
    │              ツールの実行結果を LLM に返却
    │                    │
    │                    ▼
    │              LLM が指示の形式に従って返信を生成
    │
    └─ マッチなし → 通常の対話で返信

1. スキルの展開（Skill Expansion）

AI アシスタントが、ユーザーの質問をあるスキルで処理すべきだと判断すると、システムは SkillExpandTool を呼び出します。

• 入力：スキル名（skill_name）

• 処理：名前をもとにスキルを検索し、完全な指示内容と付属ツールの一覧を取得

• 出力：Markdown 形式の指示内容 + 利用可能なツール一覧

{
  "name": "expand_skill",
  "arguments": {
    "skill_name": "休暇日数計算"
  }
}

2. ツールの動的読み込み（Tool Loading）

スキルの展開後、LLM が指示の実行過程でツールを呼び出す必要がある場合は、LoadSkillTool を通じて動的に読み込みます。

• 入力：ツール名（tool_name）

• 処理：ツールを検索（MCP ツールと API ツールに対応。名前は大文字・小文字を区別しません）

• 出力：ツールの ID、名前、説明、利用可能状態

この動的読み込みの仕組みにより、スキルのツールをあらかじめすべて対話のコンテキストに読み込んでおく必要がなくなり、Token の消費を抑えられます。

---

SKILL.md 仕様

Skill の中核となる定義ファイルは SKILL.md で、YAML Frontmatter + Markdown 内容の形式を使用します。

---
name: スキル名
description: スキルの説明（AI がこのスキルをいつ発動するかを決定）
---

# スキルタイトル

## 発動条件
ユーザーが XXX に関連する質問をしたときに発動します。

## 実行ステップ

### Step 1：情報の確認
ユーザーに必要な情報の提供を促します...

### Step 2：データの検索
retrieve_text_nodes を使用してナレッジベースを検索します...

### Step 3：返信の生成
以下の形式で返信します。
- ① 適用法規
- ② 計算結果
- ③ 参考例

Frontmatter フィールド

フィールド	必須	説明
name	はい	スキル名。組織内で重複できません
description	はい	スキルの説明。LLM がこのスキルを発動するかどうかの判断に使用します

指示内容の作成に関する推奨事項

1. 発動条件を明確に：説明と指示の中で「いつ発動するか」と「いつ発動しないか」を明確に定義します

2. ステップを構造化：番号付きのステップ（Step 1, Step 2...）を使い、LLM が順を追って実行できるようにします

3. ツール呼び出しのガイド：各ステップの中で、どのツールをどのような検索方針で使用すべきかを明確に示します

4. 返信形式の定義：テンプレートや表で最終的な返信の形式を定義し、出力の一貫性を確保します

5. エラー防止チェックリスト：指示の末尾にチェックリストを追加し、LLM が自ら結果を検証できるようにします

---

スキルパッケージ（Skill Package）

ファイル構成

アップロードする .skill または .zip ファイルは、以下の構成を含む必要があります。

my-skill.skill (ZIP 形式)
├── SKILL.md          # 必須：スキル定義ファイル
├── reference.pdf     # 任意：参考資料
├── template.xlsx     # 任意：テンプレートファイル
└── examples/         # 任意：サンプルデータ
    └── case1.json

セキュリティ検証

システムはスキルパッケージを解析する際、以下のセキュリティチェックを行います。

• 圧縮比チェック：最大 100:1。ZIP 爆弾攻撃を防ぎます

• パストラバーサル防御：../ などのパスインジェクションをブロックします

• ファイルサイズ制限：組織で設定されたアップロード制限に従います（デフォルト 100 MB）

• SKILL.md の検証：存在が必須で、有効な name と description を含む必要があります

---

API エンドポイント

Skill CRUD

メソッド	エンドポイント	説明
GET	/api/v1/skills/	組織内のすべてのスキルを一覧表示（ページネーション・検索に対応）
POST	/api/v1/skills/	スキルを手動で作成
GET	/api/v1/skills/{id}/	スキルの詳細を取得
PATCH	/api/v1/skills/{id}/	スキルを更新
DELETE	/api/v1/skills/{id}/	スキルを削除（S3 のクリーンアップを含む）

スキルパッケージ操作

メソッド	エンドポイント	説明
POST	/api/v1/skills/upload/	.skill / .zip をアップロードしてスキルを作成
POST	/api/v1/skills/{id}/reupload/	再アップロードしてスキルパッケージを置き換え
GET	/api/v1/skills/{id}/export/	スキルを .skill ファイルとしてエクスポート
GET	/api/v1/skills/{id}/package-structure/	スキルパッケージのファイル構成を確認

リソース管理（ネストされたルート）

メソッド	エンドポイント	説明
GET	/api/v1/skills/{id}/resources/	スキルのリソースファイルを一覧表示
POST	/api/v1/skills/{id}/resources/	リソースをアップロード（手動作成したスキルのみ）
DELETE	/api/v1/skills/{id}/resources/{rid}/	リソースを削除（手動作成したスキルのみ）
GET	/api/v1/skills/{id}/resources/{rid}/download/	リソースファイルをダウンロード

スキル作成の例

手動で作成する場合：

POST /api/v1/skills/
{
  "name": "返品処理フロー",
  "description": "顧客が返品・交換を希望したときに発動します。注文を検索し、返品資格を確認し、返品伝票を作成します。",
  "instructions": "# 返品処理\n\n## Step 1：注文を検索\n...",
  "attached_tool_ids": [
    "uuid-of-order-query-tool",
    "uuid-of-return-api-tool"
  ]
}

スキルパッケージをアップロードする場合：

curl -X POST /api/v1/skills/upload/ \
  -F "file=@my-skill.skill" \
  -F "attached_tool_ids=[\"uuid-1\",\"uuid-2\"]"

---

スキルと AI アシスタントの紐付け

スキルは ChatbotSkill 中間モデルを介して、AI アシスタントと多対多の関連を構築します。

• 1 つの AI アシスタントは複数のスキルを紐付けられます

• 1 つのスキルは複数の AI アシスタントで使用できます

• 紐付け／解除の操作は ChatbotSkillEvent 履歴追跡テーブルに記録されます

AI アシスタント A ──┬── スキル：返品処理
                    ├── スキル：製品相談
                    └── スキル：メール送信

AI アシスタント B ──┬── スキル：製品相談  ← 共用
                    └── スキル：会議検索

---

MaiAgent Skill ならではの強み

1. 指示とツールの分離

スキルの指示内容と付属ツールは独立して管理されるため、ツール設定に影響を与えることなくいつでも指示ロジックを調整でき、その逆も可能です。これにより、スキルの保守と改良がより柔軟になります。

2. 動的展開の仕組み

スキルの指示はあらかじめ対話のコンテキストに読み込まれるのではなく、LLM が必要と判断したときにのみ動的に展開されます。これにより、対話ごとの Token 消費を大幅に削減でき、特に多数のスキルを紐付けた AI アシスタントに適しています。

3. スキルパッケージのエコシステム

.skill ファイル形式を通じて、スキルを異なる組織間で共有・インポートできます。企業は社内のスキルライブラリを構築したり、ベストプラクティスをスキルパッケージとしてパッケージ化してパートナーに配布したりできます。

4. 完全なバージョン管理

アップロード方式で作成したスキルは再アップロード（Reupload）に対応しており、既存のスキルを削除することなくスキルパッケージの内容を更新できます。システムはスキルパッケージとリソースファイルを完全に置き換え、バージョンの一貫性を確保します。

5. 権限管理

スキルへのアクセスは chatbot_skill_access 権限によって制御されます。組織管理者は役割（ロール）権限システムを通じて、誰がスキルを作成・編集・削除できるかをきめ細かく管理できます。