> 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/ja/advanced-genai-tech/skill.md). # スキルモジュール Skill スキルモジュールの技術説明：タスクの指示、ツール、リソースファイルを Agent が必要に応じて展開する機能単位にまとめる仕組み、SKILL.md の仕様、トリガー条件、スキルパッケージの構成、API エンドポイント。 ## Skill とは？ Skill（スキル）は、タスクの指示、追加ツール、リソースファイルを、Agent が必要に応じて展開できる機能単位にまとめたものです。概念、利用場面、管理画面での操作については、ユーザーマニュアルの[スキル](https://docs.maiagent.ai/build/skills)をご覧ください。このページでは、動作原理、`SKILL.md` の仕様、API を説明します。

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

*** ## Skill の動作原理 ### 動作フロー ``` ユーザーが質問 │ ▼ Agent がメッセージを受信（利用可能なスキル一覧：名前＋使用場面を含む） │ ▼ LLM が意図を分析し、スキルの使用場面と照合 │ ├─ スキルが一致 → skill_expand_tool を呼び出し │ │ │ ▼ │ スキルの指示全文を取得 │ ＋追加ツール名（スキルとともにすでに接続済み） │ ＋リソースファイルの場所（Code Interpreter が有効な場合） │ │ │ ▼ │ LLM が指示に従って順に実行し、追加ツールを呼び出し │ │ │ ▼ │ LLM が指定された形式で回答を生成 │ └─ 一致なし → 通常の会話として回答 ``` ### 1. スキル一覧 Agent にスキルを関連付けると、モデルは最初に各スキルの名前と使用場面だけを参照します。使用場面には `SKILL.md` の `when_to_use` を使い、未設定の場合は `description` を使います。指示全文は、あらかじめコンテキストに読み込まれません。 ### 2. スキルの展開（Skill Expansion） モデルが特定のスキルで質問を処理すべきだと判断すると、`skill_expand_tool` を呼び出します。 * **入力**：スキル名（`skill_name`、大文字・小文字を区別しません） * **出力**：スキルの指示全文（`instructions`）、使用場面、追加ツール名（`attached_tools`）、リソースファイル一覧とディレクトリ（`resource_files`、`resource_directory`）を含む JSON です ```json { "name": "skill_expand_tool", "arguments": { "skill_name": "休暇日数計算" } } ``` ### 3. 追加ツールとリソースファイル * **追加ツール**：スキルに関連付けられた API ツールと MCP ツールは、会話開始時にスキルとともに接続されます。モデルはスキルを展開した後、追加の読み込みなしで直接呼び出せます。 * **リソースファイル**：Agent で Code Interpreter を有効にしている場合、スキルを展開するとリソースファイルがサンドボックスの `/workspace/skills/<スキル名>/` ディレクトリに読み込まれ、モデルがプログラムで参照できます。Code Interpreter が無効な場合、モデルは指示内容だけを取得します。 *** ## SKILL.md の仕様 スキルの中心となる定義ファイル `SKILL.md` は、YAML Frontmatter と Markdown 本文で構成されます。 ```markdown --- name: スキル名 description: スキルの説明（AI がこのスキルを起動するタイミングを決定） --- # スキルのタイトル ## トリガー条件 ユーザーが XXX に関する質問をしたときに起動します。 ## 実行手順 ### Step 1：情報の確認 必要な情報をユーザーに提供してもらいます... ### Step 2：情報の検索 retrieve_text_nodes を使ってナレッジベースを検索します... ### Step 3：回答の生成 以下の形式で回答します： - ① 適用法令 - ② 計算結果 - ③ 参考例 ``` ### Frontmatter のフィールド | フィールド | 必須 | 説明 | | ------------- | --- | -------------------------------------------------------- | | `name` | はい | スキル名です。組織内で重複できません | | `description` | はい | スキルの説明です。`when_to_use` が未設定の場合、LLM はこの説明で起動するタイミングを判断します | | `when_to_use` | いいえ | 使用場面です。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 ``` ### セキュリティ検証 システムはスキルパッケージの解析時に、次のセキュリティチェックを行います。 * **圧縮率チェック**：ZIP 爆弾攻撃を防ぐため、最大 100:1 に制限します * **パストラバーサル対策**：`../` などのパスインジェクションを防ぎます * **ファイルサイズ制限**：組織のアップロード制限に従います（デフォルトは 100 MB） * **SKILL.md の検証**：ファイルが存在し、有効な `name` と `description` を含む必要があります *** ## API エンドポイント ### スキルの 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/` は JSON でスキルを作成します（`Authorization: Api-Key <キー>`、`Content-Type: application/json`）。フィールド名は camelCase と snake\_case の両方に対応し、レスポンスは常に camelCase です。 | フィールド | 必須 | 説明 | | ----------------- | ------------ | --------------------------------------------------------------------------------------------------------------- | | `name` | はい | スキル名です。組織内で重複できず、フォルダー名に使える文字のみ使用できます | | `description` | はい | スキルの説明です。`whenToUse` が未設定の場合、モデルはこの説明で起動するタイミングを判断します | | `whenToUse` | いいえ | 使用場面です。モデルはスキルを起動するかどうかを判断する際にこのフィールドを優先します | | `instructions` | はい | `SKILL.md` の内容（Markdown）です | | `attachedToolIds` | いいえ | 追加するツールの ID 配列です。有効なツールだけを受け付けます。レスポンスではこのフィールドを返さず、代わりに `attachedTools` でツールの概要を返します | | `groups` | ユーザーの立場によります | `[{"id": "<ロール ID>"}]` です。組織の owner は省略できますが、その他のメンバーは自分が所属するロールを少なくとも 1 つ指定する必要があります。未指定の場合は `400` を返します | | `files` | いいえ | スキルに付属するリソースファイルです。各項目は `{"path": "scripts/run.py", "content": "…", "contentEncoding": "text" または "base64"}` です | 成功時は `201` を返し、内容はスキルオブジェクトです（`id`、`createdAt`、`resources` を含む）。名前の重複、無効なツール ID、ロールの条件違反の場合は `400` を返し、内容はフィールドのエラーまたは `{"detail": "…"}` です。更新には `PATCH /api/v1/skills/{id}/` を使い、フィールドは同じです（`files` を除く）。`name`、`description`、`whenToUse`、`instructions` のいずれかを変更すると、`SKILL.md` が再生成されます。 ### スキル作成の例 **手動作成：** ```json POST /api/v1/skills/ { "name": "返品処理フロー", "description": "顧客の返品・交換依頼を処理します：注文の確認、返品条件の確認、返品依頼の作成。", "whenToUse": "顧客が返品、交換、返金に言及したときに起動します", "instructions": "# 返品処理\n\n## Step 1：情報の確認\n...", "attachedToolIds": [ "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\"]" ``` *** ## スキルと Agent の関連付け スキルと Agent は、`ChatbotSkill` 中間モデルを介して多対多で関連付けられます。 * 1 つの Agent に複数のスキルを関連付けられます * 1 つのスキルを複数の Agent が使用できます * 関連付けと解除の操作は `ChatbotSkillEvent` 履歴テーブルに記録されます ``` Agent A ──┬── スキル：返品処理 ├── スキル：製品相談 └── スキル：メール送信 Agent B ──┬── スキル：製品相談 ← 共用 └── スキル：会議検索 ``` *** ## 設計上の特性と制限 ### 指示とツールを分けて管理します スキルには指示内容、使用場面、リソースファイルを保存します。追加ツールは組織の既存ツールへの参照です。スキルの指示を変更してもツール設定は変わりません。ツール自体（URL、ヘッダーなど）を変更すると、そのツールを追加しているすべてのスキルと、それらのスキルに関連付けられた Agent に影響します。 ### 必要に応じた展開 スキルの指示全文は、モデルが `skill_expand_tool` を呼び出した時点でコンテキストに入ります。展開前のスキルが占めるのは名前と使用場面だけです。[スキル一覧](#skill-list)をご覧ください。そのため、スキルが使われるかどうかは、モデルが使用場面から適用を判断できるかに依存します。使用場面が曖昧だと、スキルが展開されない場合があります。よくある表現と「適用しない」場面を記載することをおすすめします。 ### エクスポートと組織間インポート * エクスポートした `.skill` ファイルには、`SKILL.md` とすべてのリソースファイルが含まれます。手動作成したスキルでは、生成された `SKILL.md` に使用場面と追加ツール名も含まれます。 * 別の組織にアップロードすると、システムはツール名を使って、その組織のツールに再度関連付けます。一致するツールが見つからない項目（ツール名がない MCP ツールを含む）はアップロード結果に表示され、手動での関連付けが必要です。 * ツール本体とその認証情報は、スキルパッケージに含めてエクスポートされません。 ### 再アップロード アップロードで作成したスキルは、再アップロード（Reupload）できます。新しいスキルパッケージで名前、説明、指示内容、すべてのリソースファイルを置き換え、古いリソースファイルは削除されます。プラットフォームは旧版のスキルパッケージを保持しません。復元が必要な場合は、以前の `.skill` ファイルを自身で保存してください。手動作成したスキルは再アップロードできません。 ### 権限管理 スキルページへのアクセスは「スキル権限」（`chatbot_skill_access`）で制御します。組織が作成したスキルはロールに割り当てられ、「ロール × スキル」の各組み合わせで読み取り・編集・削除を個別に設定できます。ロールには「スキルの新規作成を許可」の切り替えもあります。設定方法は、ユーザーマニュアルの[ロールごとのスキル表示と権限の管理](https://docs.maiagent.ai/build/skills/skills-management#skill-role-visibility)をご覧ください。 *** ## 操作方法はユーザーマニュアルをご覧ください * [スキル](https://docs.maiagent.ai/build/skills)：概念と利用場面 * [スキル管理](https://docs.maiagent.ai/build/skills/skills-management)：作成、アップロード、ツールの追加、エクスポート、Agent への関連付け --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.