> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/maiagent-tech-ja/advanced-genai-tech/skill.md). # 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 形式の指示内容 + 利用可能なツール一覧 ```json { "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 内容の形式を使用します。 ```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/` | リソースファイルをダウンロード | ### スキル作成の例 **手動で作成する場合：** ```json 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" ] } ``` **スキルパッケージをアップロードする場合：** ```bash 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` 権限によって制御されます。組織管理者は役割（ロール）権限システムを通じて、誰がスキルを作成・編集・削除できるかをきめ細かく管理できます。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.maiagent.ai/tech/maiagent-tech-ja/advanced-genai-tech/skill.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.