> For the complete documentation index, see [llms.txt](https://studio-docs.japan-ai.co.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.japan-ai.co.jp/rupageskillrissu/create-and-use-skills.md).

# Skillを作成して利用する

繰り返し発生する業務の手順、出力形式、補助ファイル、必要なツールをSkillとしてまとめると、複数のAgentで再利用しやすくなります。この記事では、Skillの設計、スキルビルダーでの作成・編集、既存パッケージの取り込み、Agentへの追加と確認を説明します。

* AgentへSkillを追加する方法：[Agentにツール・Skill・Datasetを設定する](/ruagent/configure-agent-tools-skills-datasets.md)
* Skill固有の仕様・制限：[Skillの仕様・制限](/shi-yang-zhi-xian/skill-specs-and-limits.md)

## Skillとは

Skillは、特定のタスクに必要な**指示・コード・リソースをまとめたフォルダ**です。Agentは依頼に応じて必要なSkillを判断して読み込みます。テンプレート、参照用のファイル、処理用のコードを一緒に管理できるため、同じ手順や出力を複数のAgentで再現したい場合に向いています。

| 向いているもの     | 例                       | 別の方法を検討するもの                          |
| ----------- | ----------------------- | ------------------------------------ |
| 定型的な判断・作業手順 | 議事録から決まった形式で要点を抽出する     | 一度だけの依頼や、会話ごとに大きく変わる依頼               |
| 共通の出力ルール    | 回答を「結論・根拠・確認事項」の順で作成する  | Agent全体の振る舞い・口調を決める基本指示              |
| 再利用する素材     | 文書テンプレート、補助スクリプト、参照ファイル | 最新性が必要な業務資料そのもの。必要に応じてDatasetなどを検討する |

Skillを追加するだけで、すべての依頼で必ず同じ処理が実行されるわけではありません。いつ使うか、何を確認するか、出力に何を含めるかをSkillの説明と本文、Agentの指示に分けて明確にします。

## 始める前に

* 対象の組織・Projectと、Skillを作成・編集できる権限を確認します。画面に「スキルの作成・編集にはエディターまたは管理者権限が必要です。」と表示される場合は、管理者に確認してください。
* 既存のSkillを検索し、同じ用途のものがないか、更新対象ではないかを確認します。
* 対象業務、想定する入力、完了条件、利用者、必要なツールを整理します。
* 外部サービスを操作する場合は、先に接続・権限・テスト対象を確認します。認証情報、パスワード、APIキー、Secretの値をSkill本文や添付ファイルに書かないでください。
* 影響の小さいテスト入力と、期待する出力を用意します。

> Skillの作成・編集と、Agentへ追加して利用可能にすることは別の操作です。作成直後にAgentへ反映されたとは扱わず、追加先と実際の動作を確認してください。

## 1. 再利用する処理を設計する

最初から大きなSkillを作らず、1つの目的を完了する最小単位にします。例えば「営業資料を作る」ではなく、「商談メモから提案骨子を作る」のように、入力と出力を限定します。

| 整理する項目 | 決める内容                           |
| ------ | ------------------------------- |
| 目的     | 何を完了させるSkillか。完了した結果をどう判断するか    |
| 入力     | 利用者に何を渡してもらうか。不足時に何を質問するか       |
| 手順     | 確認、処理、見直しをどの順で行うか               |
| 出力     | 見出し、表、文体、必ず含める項目、根拠の示し方         |
| 例外     | 情報不足、根拠なし、実行不可のときに推測せずどう返すか     |
| ツール    | 使用が必要なツールと、その用途。不要な更新系ツールは選ばない  |
| 素材     | テンプレートやスクリプトなど、Skill内で再利用するファイル |

### 説明と指示を分けて書く

「説明」は、AgentがSkillを選ぶ判断にも利用されるため、利用者が読んで分かる言葉で、用途・対象・期待する成果物を具体的に書きます。「何でも対応する」「便利なSkill」のような説明では、使いどころが分かりません。

本文の指示では、処理の順序と判断基準を書きます。次のように、確認可能な表現にしてください。

| 避ける表現    | 書き換え例                                      |
| -------- | ------------------------------------------ |
| 適切に要約する  | 指定された議事録だけを読み、「決定事項」「担当者と期限」「未決事項」に分けて出力する |
| 必要なら確認する | 日付、担当者、期限のいずれかがない場合は、推測せず不足項目として質問する       |
| 正しい内容にする | 入力に根拠がない事項は追加せず、「入力からは確認できません」と記載する        |

指示は、通常の流れだけでなく、禁止する操作と例外時の返し方も書きます。ただし、Skill本文に「外部へ送信しない」と書いても、ツールや接続先の権限そのものを取り消すことにはなりません。

## 2. 新しいSkillを作成する

1. 対象の組織またはProjectで「スキル」の一覧を開きます。
2. 「新規スキル」を選択します。画面によっては「スキルビルダー」が開きます。
3. 「構成」を開き、「スキルID」を入力します。スキルIDには半角英小文字・数字・アンダースコアを使用します。既存のIDと重複しないようにします。
4. 「表示名」に、利用者に分かる名称を入力します。
5. 「説明」に、どの依頼で使い、何を返すSkillかを具体的に入力します。
6. 必要な場合だけ「ツール」を選択します。選択したツールは、このSkillで使用できるようになります。
7. 必要に応じて「アイコンを選択」で識別用の画像を設定します。画像なしで保存することもできます。
8. 「SKILL.md」を開き、前節で整理した手順、判断条件、出力形式、例外時の扱いを記載します。ファイル一覧で補助ファイルを確認し、本文から参照する場合は名前と用途を一致させます。
9. 保存操作を行い、保存エラーがないことを確認します。

SKILL.mdにはfrontmatterが必要です。少なくとも`name`と`description`を含めます。画面上の「スキルID」「表示名」「説明」や選択した「ツール」は、SKILL.mdの情報と対応します。SKILL.mdを直接編集した場合も、保存前にこれらが意図どおりであることを確認してください。

> 「保存に失敗しました」と表示された場合は、作成完了として扱わないでください。SKILL.mdのfrontmatter、スキルIDの形式・重複、必要な権限、画面に表示されたエラーを確認します。

## 3. 既存のSkillパッケージを取り込む

既に用意されたSkillを利用する場合は、「スキルのアップロード」から取り込みます。

1. 作成または編集するSkillを「スキルビルダー」で開きます。
2. 「構成」の「スキルのアップロード」を確認します。
3. 「ZIPファイルを選択」を選ぶか、画面へファイルをドラッグ＆ドロップします。フォルダを選択できる画面では「フォルダを選択」も利用できます。
4. ZIPの内容を確認します。SKILL.mdと、処理に必要な補助ファイルが含まれていることを確認してください。
5. 取り込み後、SKILL.mdの「スキルID」「説明」、ツール、ファイル一覧を確認します。
6. 内容を自組織の用途・接続・共有範囲に合わせて見直し、保存します。

ZIPを使う場合、SKILL.mdが必要です。形式や構造が正しくない場合、SKILL.mdのfrontmatterに`name`または`description`がない場合は取り込めません。同じスキルIDがすでに存在する場合は、上書きに関する確認が表示されることがあります。意図しない既存Skillを更新しないよう、名前と内容を確認してから続けてください。

> ダウンロード元が不明なSkillや、内容を確認できないコード・ファイルをそのまま取り込まないでください。外部送信、ファイル操作、認証情報の取り扱いを確認し、許可されたテスト環境で検証してください。

## 4. 共有範囲と編集内容を確認する

画面に表示される共有範囲は「組織」または「非公開」です。利用者と利用させるAgentに合わせて選択します。利用できる選択肢や変更可否は、操作する場所・権限・提供状態により異なる場合があります。

| 確認すること         | 確認内容                                    |
| -------------- | --------------------------------------- |
| 非公開で試す場合       | 自分だけで検証するSkillかを確認する                    |
| 組織で使う場合        | Skill本文、補助ファイル、選択ツールを組織内の利用者へ見せてよいか確認する |
| 共有Agentへ追加する場合 | Agentの共有とSkillの共有が別設定であることを確認する         |
| 更新する場合         | 影響するAgent、利用者、既存の手順・出力を確認してから保存する       |

組織に公開されたAgentへ非公開Skillを追加すると、「他のユーザーは非公開スキルを利用できません。スキルの公開範囲を変更してください。」という案内が表示される場合があります。警告を消すことだけを目的に共有範囲を広げず、Skillの内容と想定利用者を確認してください。

Projectへ外部のSkillをリンクした場合、そのSkillはProject内で読み取り専用です。内容を変更したい場合は作成元で更新します。リンクできる候補と必要な権限は、画面に表示される候補で確認してください。

## 5. Agentで有効にして試す

1. 作成したSkillを利用するAgentの編集画面を開きます。
2. 「プラグイン」の「追加」を選択します。
3. 「スキル」と表示される候補から、作成したSkillを検索して選択します。
4. 名前、説明、共有範囲、必要なツールや認証を確認し、「追加」を選択します。
5. Agentの「プラグイン」欄にSkillが表示されることを確認します。
6. Agentの指示に、Skillを使う業務の目的、優先する条件、出力の確認方法を補足します。
7. 機密情報を含まない小さな入力で実行し、手順、根拠、出力形式、ツールの利用結果を確認します。

作成後に「このエージェントでスキルを有効化しますか？」と表示される場合は、対象Agentと影響を確認してから「有効化する」を選択します。あとで設定する場合は、上記の手順でAgentから追加できます。詳細な追加・認証・設定解除は[Agentにツール・Skill・Datasetを設定する](/ruagent/configure-agent-tools-skills-datasets.md)を参照してください。

### 更新後も確認する

Skillを更新したら、少なくとも代表的な正常入力、情報が不足した入力、実行してはいけない条件を試します。ツールや共有範囲を変更した場合は、想定利用者のアカウントでも確認してください。「バージョン履歴」が表示される場合は、現在の版と過去版を取り違えず、過去バージョンの表示中は保存できない案内に従います。

## うまくいかないとき

| 状況                  | 確認・対応                                                 |
| ------------------- | ----------------------------------------------------- |
| 「新規スキル」や編集操作が表示されない | 組織・Project、権限、機能の提供状態を確認する                            |
| 保存できない              | SKILL.mdのfrontmatter、スキルID、description、重複、画面のエラーを確認する |
| ZIPを取り込めない          | ZIP形式、SKILL.mdの有無と位置、内容・構造、アップロード権限を確認する              |
| 利用者がSkillを使えない      | AgentとSkillそれぞれの共有範囲、利用者のアクセス、必要な認証を確認する              |
| 意図した手順・形式にならない      | 説明の用途、SKILL.mdの手順・例外条件、Agentの指示、テスト入力を見直す             |
| 更新内容が確認できない         | 保存結果、現在表示しているバージョン、Agentで設定したSkillを確認する               |

## チェックリスト

* [ ] 再利用する目的、入力、完了条件、例外時の扱いを決めた
* [ ] 利用者に分かる表示名と、用途が具体的な説明を設定した
* [ ] SKILL.mdに必要なfrontmatterと、確認可能な手順・出力条件を記載した
* [ ] 必要なツールだけを選び、認証情報を本文やファイルに含めなかった
* [ ] 取り込んだファイル・コードの内容と安全性を確認した
* [ ] 共有範囲と、共有Agentの利用者への影響を確認した
* [ ] Agentへ追加し、設定が残っていることを確認した
* [ ] 小さな入力で、出力・根拠・必要なツールの動作を確認した

## 次に読む記事

* [Agentにツール・Skill・Datasetを設定する](/ruagent/configure-agent-tools-skills-datasets.md)
* [Agentをテストして改善する](/ruagent/test-and-improve-agents.md)
* [Skillの仕様・制限](/shi-yang-zhi-xian/skill-specs-and-limits.md)
