10. スキル¶

10.1. スキルで確かめること¶

スキルは、LLM に読ませる手順書であって、ツールのような実行部品ではありません。この前提を取り違えると、実行できるはずのない処理をスキルに書いてしまいます。手順を実際に実行させる必要がある場合は、スキル単体では完結しないため、ツールと組み合わせます（「ツール」）。

スキルにはカテゴリの区分がなく、一覧は検索だけで絞り込みます。ナレッジベースやツールのように業務ドメインで事前に整理する必要はなく、名前と説明で見分けられる粒度で作成して構いません。

10.2. スキルを構成する要素¶

スキルは、SKILL.md と補助ファイルをひとまとめにしたものです。ここでは、その中身が何で構成されるかを説明します。実際に作成する画面の操作は「スキルを作る」で扱います。

SKILL.md の先頭には、---で囲んだフロントマターとして name（画面の「スキル名」）と description（画面の「指示（AI用）」）という 2 つの項目を書きます。Skill ID はスキルを格納するフォルダの名前で、nameとは別の値です。---が無いと、この部分はフロントマターとして認識されず、SKILL.md 全体が本文として扱われます。description は、LLM がこのスキルを選ぶかどうかを判断する唯一の手がかりです。何ができるかだけでなく、いつ使うべきかをここに書きます。

例えば、次のように書きます。

---
name: ticket-triage
description: 問い合わせメールの内容から緊急度を判定し、担当チームへの振り分け案を作るときに使う
---

（ここから本文。LLM に読ませる具体的な手順を書く）

このフロントマターは、フル仕様の YAML ではなく専用の簡易パーサで読み取ります。key: valueの単純な書き方と、説明文を複数行に分けたいときの description: |（改行を残す）のようなブロックスカラ、metadata:配下に1段だけ key: valueを並べる書き方に対応しています。フロー形式（[a, b]）や2段以上のネストなど、凝った書き方はできません。構文がおかしいと取り込みに失敗します（「困ったときの確認」）。

悪い例は対象を述べているだけで、いつ使うべきかが書かれていません。複数のスキルを割り当てたエージェントでは、この違いが実際に選ばれるかどうかを左右します。

SKILL.md 本文（フロントマターより後ろの部分）には、手順そのものを書きます。ここは LLM 向けの「指示」であり、人が読む利用者向け説明とは別です。利用者向け説明は SKILL.md の中ではなく、SKILL.md と同じ場所に置く予約ファイル .description（ロケール別は .description_<ロケール>）に書きます。作成画面の「説明」欄に入力した文章はこの .descriptionファイルに保存され、Skill 一覧に表示されるだけで、LLM の選択には使われません。SKILL.md と説明ファイルを混同すると、人向けの文章が LLM の選択材料に混ざってしまいます。

編集画面では、SKILL.md 以外の補助ファイルを追加・リネーム・移動できます。ファイル追加時はファイル名とフォルダ名を、リネーム時は新しい名前を、移動時は移動先フォルダを指定します。補助ファイル（SKILL.md 以外にスキルへ追加できるファイル）には上限があります。

上限を超えると、切り詰めずに失敗します。登録・インポートの入口では取り込み自体を拒み、実行時にはツールの実行を失敗させます。一部だけを渡すと、LLM が本文全体を読んだものとして続きを組み立ててしまうためです。SKILL.md は UTF-8 で書きます。UTF-8 として読めない場合は、文字化けしたまま取り込まれることを避けるため、取り込みを拒みます。

下位フォルダに置いた SKILL.md（入れ子スキル）は対応していません。スキルの定義になるのは、直下に置いた SKILL.md 1 個だけです。

10.3. スキルを作る¶

作成の経路は、空から書く、ZIP を取り込む、AI に生成させるの 3 通りがあります。いずれも作成方法を選ぶ画面から始まり、空から書く場合はそのまま基本情報（Skill ID・スキル名・指示・説明）の入力画面に進みます。

図：Skill の作成方法を選択する画面。空から作成・ZIP をアップロードして作成・AI で生成の 3 通りから選ぶ。

作成画面の入力欄は、Skill ID・スキル名・指示（AI用）・説明の 4 つです。このうちスキル名と指示（AI用）が、そのまま SKILL.md の name・descriptionに書き込まれます。画面上は「指示（AI用）」という名前でも、実体は SKILL.md の descriptionフィールドである点に注意します。

図：空から作成を選んだ場合の基本情報入力画面。Skill ID・スキル名・指示（AI用）・説明を入力する。

AI 生成では、基本情報の入力後に生成用プロンプトを追加で入力します。生成中は、SKILL.md の生成、補助ファイルの生成、AI への問い合わせ（複数回になることがあります）といった進行状況が画面に表示されます。ツール呼び出しが失敗した場合は自動的にやり直されます。生成後の中身はたたき台として扱い、実際に使う前に SKILL.md と補助ファイルの内容を確認します。AI に生成させる場合は、暴走を止めるための上限として、1 ファイル 200KB・最大 30 件までという、「スキルを構成する要素」の上限より厳しい枠が別に設けられています。

ZIP を取り込む際、Skill ID には予約語が使えません（list・draft・export・import・generate・catalog・limits）。これらは管理画面の REST パスで固定語として使われているため、スキルID に許すと、パスを見ただけではスキルを指すのか操作を指すのか区別できなくなります。

ZIP の展開時、macOS の __MACOSX・.DS_Storeや Windows の Thumbs.db・desktop.iniといった OS の作業ファイルは、利用者が入れたものではないため無かったものとして扱われます。大文字・小文字だけが違う同名パスが 2 つ以上あると、取り込みを拒みます（大文字小文字を区別しないファイルシステムでは、後から書いたほうだけが残り、片方が黙って消えるためです）。

10.4. スキルが使われる仕組み¶

スキルの中身は、概要（Skill ID・name・description・metadata）だけを先に読み込み、必要になった時点で本文を取得する段階取得の仕組みで扱われます。一覧・選定の段階では本文を読み込まないため、長い手順書を書いても、選定時のコンテキストを圧迫しません。本文は、実際にそのスキルが使われる段になって初めて取得されます。

この仕組みが、「スキルを構成する要素」で説明した description が選定の唯一の手がかりになる理由です。選定の時点ではまだ本文が読み込まれていないため、本文にどれだけ詳しく書いても、それだけでは選ばれません。

10.5. エージェントへの割り当てと利用箇所の確認¶

作成したスキルは、エージェント定義の画面から割り当てます（「ナレッジベース・スキル・ツール・ガードレールを割り当てる」）。割り当てたスキルの利用箇所は、スキル管理画面側からも確認できます。利用中（いずれかのエージェントに割り当てられている状態）のスキルは削除できません。

10.6. インポート・エクスポート¶

スキルは ZIP 形式でインポート・エクスポートできます。手順と注意事項は「インポート／エクスポート」を参照してください。

10.7. 困ったときの確認¶