スキル＝1つのフォルダ

では、この「必要に応じて読み込む」スキルはどんな見た目でしょうか？答えは驚くほどシンプル：スキルは1つのフォルダで、中にSKILL.mdファイルが必須です。このファイルは2つの部分に分かれます。前半がfrontmatter、---で囲まれた小さなメタデータで、スキルの名前と「どんなときに使うべきか」を記述します。後半がbody、実際の操作手順です。フォルダには任意のリソースを3種類追加できます：scripts/（実行可能スクリプト）、references/（参照ドキュメント）、assets/（テンプレート素材）。

skill-name/
├── SKILL.md          # 必須: メタデータ + 手順書
├── scripts/          # 任意: 実行可能コード
├── references/       # 任意: ドキュメント
├── assets/           # 任意: テンプレート、リソース
└── ...               # その他のファイルやディレクトリ

スキルはMarkdownと通常ファイルで構成されるため、コードと同じようにGitで配布できます。追加サーバーは不要です。frontmatterには公式のテンプレートが用意されており、ポイントはすべてdescriptionにあります。これがトリガースイッチです。

---
name: adr-template
description: Activate this skill when proposing significant architectural changes, documenting codebase refactorings, or resolving design/technical debates. Use this skill to author and maintain Architecture Decision Records (ADRs) to preserve engineering context.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

プログレッシブ・ディスクロージャー：目次は常駐、本文は指名後に

フォルダが用意できたら、モデルはどうやって使うタイミングを知るのでしょうか？鍵となるのは「プログレッシブ・ディスクロージャー（progressive disclosure）」と呼ばれる仕組みで、3つのステップで構成されます：

1. 発見（Discovery）：起動時にスキルディレクトリをスキャンし、各スキルの名前と説明だけをシステムプロンプトに注入。モデルには目次だけを見せている状態です。
2. 活性化（Activation）：タスクが特定のスキルの説明と一致したら、フレームワークがuse_skillツールを呼び出し、そのSKILL.mdの完全な本文をコンテキストに読み込みます。
3. 実行（Execution）：モデルは本文の手順に従って作業を進め、必要に応じてreferences/を参照したり、同梱のスクリプトを実行します。

トークンの節約はこのようにして実現されます。コンテキストに常駐するのは各スキルの数十文字の名刺だけ。数百ページの詳細はディスク上に置かれ、指名された者だけがメモリに読み込まれます。この設計の利点は3つにまとめられます。

元記事のプログレッシブ・ディスクロージャー図：トークン消費は本当に必要な瞬間まで先延ばし。画像はGoogle Developers Blogより（Gemini 3.1 Flash Image生成）

導入は1行のパラメータ、裏ではミドルウェアが活躍

仕組みが分かったところで、実際にコードで書く量はどれくらいでしょうか？答えは1行。genkit.Generate呼び出しにai.WithUseパラメータを追加し、スキルフォルダを指定するだけで統合完了です。

resp, err := genkit.Generate(ctx, g,
    ai.WithPrompt("How do I run tests in this repo?"),
    ai.WithUse(&middleware.Skills{SkillPaths: []string{"./skills"}}),
)

この1行の背後にあるのは、Genkitのミドルウェア（middleware）体系です。コードとモデルの間に挟まる層で、リクエストが通過するたびに、追加・迂回・記録といった処理を行うことができます。宅配便の仕分け場のようなもの。フックは3種類あり、各段階を担当します：WrapGenerateは各会話ループを横取りし、システムプロンプト注入のような会話全体を見る処理を担当。WrapModelはモデルAPI呼び出しのたびに介入し、リトライ、フォールバック、キャッシュを管理。WrapToolはツール実行のたびに介入します。Skillsミドルウェアはこのフック群の上に構築され、やることは3つ：ディレクトリをスキャンしてSKILL.mdを探す → 名刺をシステムプロンプトに注入 → リクエストが説明と一致したら活性化。

例1：「Cheese」と入力して、チーズパンスキルを起動

まずは最小限の例から見てみましょう。公式の最初のサンプルはコマンドラインレシピツールです。食材を入力するとレシピを出力します。スキルフォルダには2つのスキルが入っています。banana-bread（バナナブレッド）とcheese-bread（チーズパン）。go run main.go cheeseを実行すると、モデルがcheese-breadの説明と一致してスキルを活性化し、スキル内のレシピに従ってブラジルのチーズパン（Pão de Queijo）の完全なレシピをターミナルに出力します。

+-------------------------------------------------+
|         TRADITIONAL BRAZILIAN CHEESE BREAD      |
|                 (Pao de Queijo)                 |
+-------------------------------------------------+
INGREDIENTS
* Tapioca Flour (Sour Starch) .. 2 cups (240g)
* Grated Parmesan/Queijo ...... 1.5 cups (150g)
  ……
PRO TIP: You can freeze the unbaked dough balls
on a tray, then store them in a bag.

この例が示すのは最も基本的な流れです。ユーザーの一言がスキル説明に一致 → 名刺が本文に置き換わる → モデルがレシピ通りに作業。

例2：AIアート修復、モデルが画像を見てスキルを選択

最小例が「マッチング」を示すなら、2つ目の例はより本番に近いケースです。マルチモーダルAIアート修復。損傷したアート作品の写真を渡すと、モデルはまずスケッチか油絵か写真かを判断し、対応する修復スキルを活性化します。drawings、paintings、photographyにはそれぞれ修復手順があり、最後にGemini 3.1 Flash Image（別名 Nano Banana 2）が修復後の画像を生成します。スキル選択には分岐ロジックを1行も書く必要がなく、モデルが画像を見て判断します。

paintingsスキルのSKILL.mdには、プロの修復家の心得が書かれています。絶対的忠実（作品にない要素の追加は厳禁）、反近代化（筆致を残し、テクスチャを平坦にしない）、クラックルの尊重（ひび割れ網は作品の歴史の一部であり、塗りつぶさない）。そして3段階の流れを完結に記述：ワニス補正 → 汚れ除去 → 欠損補填。このファイル自体が「専門手順をスキル化する」良いお手本です。

---
name: paintings
description: Restoration protocol for fine art paintings.
---

# Painting restoration

Perform direct, minimal-intervention restoration of fine art
paintings. Prioritize historical integrity, original pigment
depth, and surface textures over cosmetic modernization. Do not
include any elements, nor introduce any techniques not present
in the original piece.

### 1. Core conservation mandates
* **Absolute Fidelity:** Strictly forbidden to add new subjects,
  figures, scenery, details, or narrative elements under any
  circumstances.
* **Anti-Modernization:** Retain original brushstroke
  characteristics. Do not flatten support textures.
* **Patina & Craquelure:** Respect the natural crack network
  (craquelure) as part of the artwork's history. Do not fill or
  erase cracks unless they pose an active risk of paint loss.

### 2. Step-by-step restoration process
1. **Varnish Correction:** Gently balance aged, yellowed natural
   varnishes to recover original pigment chromaticity without
   forcing modern, high-contrast saturation.
2. **Soot & Grime Reduction:** Isolate and lift surface grime
   while protecting delicate, thin underlying glaze layers.
3. **Inpaint Major Loss:** Where paint layers are missing, use
   references from the surviving elements to bridge the gap.
   Replicate the original brush direction, speed, height,
   transparency, and light source.

テスト画像はおなじみの作品。スペインの画家エリアス・ガルシア・マルティネスによる《Ecce Homo》。2012年、教区のアマチュアがこの壁画を修復し「猿のキリスト」としてネットで話題になりました。チュートリアルでは、修復事故前の元の姿をモデルに与え、モデルはこれを古典的な宗教油絵と正しく認識し、paintingsスキルを活性化、修復プランを出力します。まず黄ばんだワニスと汚れを除去し、深紅と肌色を復元。次に妨害的なひび割れを減らし、紫のローブの斑点テクスチャを保存。最後に背景の巻物に経年変化した羊皮紙の質感を加えます。

この修復スキルはまだ初期の試みです。大規模言語モデルにはランダム性があるため、同じ画像でも何度か実行しないと良い結果が得られないことがあります。手順自体もプロの修復家による調整が必要です。2つのサンプルの完全なコードはGoogleCloudPlatformのdevrel-demosリポジトリでオープンソース公開されています。リンクは記事末尾にあります。

スキル作成の4つの心得

自分のスキルを作る前に、チュートリアルの最後に付いている4つの心得をチェックしておきましょう。

答えは驚くほどシンプル：スキルとは1つのフォルダであり、中に SKILL.md ファイルが必須で置かれている。このファイルは2部構成で、軽い部分は常駐、重い部分はオンデマンドで呼び出す。

モデルは、どのスキルをいつ使うべきかをどう判断するのか？「プログレッシブ・ディスクロージャー（progressive disclosure）」という仕組みで、3ステップだ。例として、小互さんが自分のライティングアシスタントに30個のスキルを準備していたとしよう。今日はアーキテクチャ決定記録（ADR）を書きたい。

Genkit は Google 製のオープンソースAIアプリ開発フレームワーク。このスキルを認識させるには、従来の生成呼び出しにパラメータを1つ追加してスキルフォルダを指定するだけだ。

この1行の背後には、Genkit のミドルウェア（middleware。コードとモデルの間に入り、リクエストに処理を追加・変更・記録できる層）がある。このスキル用ミドルウェアは3つのことを行う。ディレクトリから SKILL.md を探し、名刺をシステムプロンプトに注入し、リクエストの説明が一致したらスキルを活性化する。

チュートリアルには Go で書かれた完全なサンプルが2つ付属しており、コードはオープンソースで流用自由だ。

チュートリアルの締めくくりは、この4点。作る前にチェックリストとして使おう。

• 説明は詳細に：名刺内の description が唯一のトリガー。命令形で「どんな時に私を使うのか」を明確に。「このスキルは〇〇の時に使う」と具体的に書くほど、モデルが呼び出すタイミングを正しく判断できる。
• 1スキル＝1つの仕事：「何でも屋」の巨大スキルは作らない。役割を絞ったスキルほど、正確に発動する。
• 実行可能なスクリプトを同梱：モデルに決定論的な「正解」を出すツールを与えよう。重要なステップをモデルのその場しのぎに委ねない。
• 詳細は references/ へ：SKILL.md 本体は簡潔に保つ。長文ドキュメントは参照ディレクトリに移し、モデルが必要に応じて読むようにする。

本文には、1行の接続パラメータ、スキルディレクトリ構造、名刺の書き方のテンプレート、そして完全な油絵修復手順書が含まれており、4つの資料をそのままコピーして使える。