OpenAI Skills の構造を slides skill から理解する

slides skill を読んで分かった Skills の構造

2026年3月7日に、1プロンプトでWBC試合スライドを生成してみた（Codex + OpenAI Skills） という記事を書きました。
本稿はその続きとして、実際に使った slides skill から Skills の構造を整理するものです。

OpenAI の Skills を最初に見たとき、「長いプロンプトをまとめる仕組み」だと思っていました。
ですが slides skill を読むと、その理解では足りませんでした。
Skills は単なる長いプロンプトではなく、手順、再利用部品、検証方法、補足資料まで含めた「作業パッケージ」として設計できるものだと分かります。

この記事では、OpenAI の slides skill を題材にして、Skills がどんな構造を持っているのかを整理します。

※ なお、本文中の slides skill の構成や各スクリプトの役割は、2026年3月8日時点で確認できた情報に基づいています。
※ 本記事はAIを活用して作成し、著者が確認・編集を行っています。誤りが残っている可能性があります。

結論(わかったこと)

Skill は、プロンプト、再利用素材、スクリプト、参考資料、エージェント用メタデータをまとめた作業パッケージです。

slides skill を見る限り、OpenAI の Skills は次のように理解するとしっくりきます。

• SKILL.md で Skill の中核となる作業手順を定義する
• assets/ で生成物に使う再利用素材を持つ
• scripts/ で作業を支える処理を自動化する
• references/ で必要時だけ読む知識を持つ
• agents/ で UI 向けメタデータを持つ

つまり Skill は、単なる説明文ではなく、専門作業を安定して進めるためのパッケージです。

slides skill の構成を見る

2026年3月8日時点で確認した slides skill の構成は次の通りでした。

slides/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── assets/
│   ├── pptxgenjs_helpers/
│   ├── slides-small.svg
│   └── slides.png
├── references/
│   └── pptxgenjs-helpers.md
└── scripts/
    ├── render_slides.py
    ├── slides_test.py
    ├── create_montage.py
    ├── detect_font.py
    └── ensure_raster_image.py

slides skill の構造を簡単に整理すると、次のようになります。

Skill
├── SKILL.md      作業手順
├── assets/       再利用部品
├── scripts/      検証ツール
├── references/   技術資料
└── agents/       UI設定

この時点で、Skill が Markdown 1ファイルでは終わっていないことが分かります。
構造ごとに役割を見ると、次のように読めます。

SKILL.md は作業手順の中心

slides/SKILL.md には、スライド作成に PptxGenJS を使うことを前提に、新規作成か既存編集かの判断、スライドサイズの決定、helper の複製・インポート、レンダリング、検証、最後に渡すファイルまで、かなり具体的な進め方が書かれています。

要するに SKILL.md は、「何を作るか」だけでなく「どう進めるか」を示す文書です。

assets/ は再利用部品の置き場

assets/ には、pptxgenjs_helpers/ のような再利用コードだけでなく、slides-small.svg や slides.png のような画像資材も入っています。
つまり assets/ は説明資料ではなく、生成物や作業でそのまま利用する素材をまとめた場所です。

その中でも slides/SKILL.md では、assets/pptxgenjs_helpers/ を作業ディレクトリへコピーして使う前提になっていました。

確認したコードでは、たとえば次の helper が含まれていました。

• autoFontSize: テキストを枠内に収めるための文字サイズ調整
• calcTextBox: 文字量と幅・高さの条件からテキスト枠の寸法や行数を見積もる
• imageSizingCrop: 画像を枠いっぱいに見せるための crop 配置情報を作る
• latexToSvgDataUri: LaTeX の数式を SVG の data URI に変換する

つまり assets/ は添付資料ではなく、実作業で使う部品置き場です。

コード参照:

• pptxgenjs_helpers/text.js: autoFontSize, calcTextBox
• pptxgenjs_helpers/image.js: imageSizingCrop
• pptxgenjs_helpers/latex.js: latexToSvgDataUri

scripts/ は確認工程を支える

scripts/ は、生成結果の確認や検証を行うための補助ツール群です。

確認した実装では、各スクリプトは次の役割を持っていました。

• render_slides.py: スライドを画像として書き出し、目視確認しやすくする
• slides_test.py: 描画結果のはみ出しを検査する
• detect_font.py: フォントの未インストールや置換の有無を確認する
• create_montage.py: 複数スライドを一覧で確認しやすくする
• ensure_raster_image.py: 画像資材の確認や扱いやすさを補助する

生成して終わりではなく、確認や検証の工程まで Skill に含めているのがポイントです。

references/ は必要時に引く資料

references/pptxgenjs-helpers.md には helper API、依存パッケージ、Python スクリプトの役割などがまとめられています。SKILL.md でも、必要に応じてこの資料を読むよう案内されています。

常に読む本体というより、詳細確認用のリファレンスです。

agents/openai.yaml は Skill の設定を持つ

agents/openai.yaml には display_name、short_description、default_prompt、アイコン画像の指定などが入っています。

この slides skill では、agents/ は Skill をどう表示し、どう呼び出させるかに関わる設定層だと理解できます。

slides skill の基本フロー

SKILL.md の内容を読むと、slides skill の作業フローは次のように整理できます。

依頼を確認
  ↓
新規作成か既存編集かを判断
  ↓
スライドサイズを決定
  ↓
helper を作業ディレクトリへコピー
  ↓
PptxGenJS で .js を作成
  ↓
.pptx を出力
  ↓
render_slides.py で画像化して確認
  ↓
必要に応じて slides_test.py などで検証
  ↓
.pptx と .js を出力

ここで重要なのは、作成物が .pptx だけではないことです。生成元の .js も残す前提になっています。

これは「見た目だけ合っていればよい」ではなく、「あとで編集できる状態を保つ」ことまで含めて Skill が設計されている、ということです。.js を残しておけば、あとからテキストや配置を修正しやすく、同じ構成を再生成することもできます。

Skills と Prompt Engineering の違い

Prompt Engineering が「指示文の書き方」を調整する技術だとすると、Skills は「作業そのものを再利用可能な形でパッケージ化する仕組み」です。

slides skill は、その違いがかなり分かりやすく出ています。指示文だけでなく、使う helper、確認用スクリプト、参照資料、出力形式までセットで定義されているからです。

slides から分かる Skills の面白さ

slides を読むと、Skills の面白さは単に「長い指示文を渡す」ことではないと分かります。

• 使うライブラリをそろえる
• 再利用部品を持たせる
• 検証手順まで固定する
• 作成物の形式まで決める

つまり、知識だけでなく運用までまとめて渡せるのが Skill の強みです。LLM の使い方を「プロンプトを書くこと」から、「再利用可能なワークフローパッケージを作ること」へ広げている点が、Skills の面白さにあります。

slides はそのことがかなり分かりやすく出ている例でした。

まとめ

slides skill を読むと、OpenAI の Skills は「LLM が参照する手順書」よりもう少し広いものだと分かります。実際には、手順、再利用コード、補足資料、検証スクリプト、設定をまとめたひとまとまりの作業単位に近いです。

PowerPoint 作成のように、作り方のばらつきが出やすく、確認工程も重要な作業では、この形はかなり相性がよさそうです。

ほかの Skill を読むときは、まず SKILL.md を見て、その後に assets/、scripts/、references/、agents/ を追うと理解しやすいはずです。

今後 Skills が増えていけば、「AIエージェントのOSSパッケージ」のような形で共有されていく可能性もありそうです。
Skills の設計思想は、今後の AI エージェント開発の基本パターンの一つになるかもしれません。

参照した資料

1. OpenAI Docs: Codex Skills
   https://developers.openai.com/codex/skills

2. Agent Skills Specification
   https://agentskills.io/specification

3. OpenAI Skills slides の定義書
   https://github.com/openai/skills/blob/main/skills/.curated/slides/SKILL.md

4. OpenAI Skills slides の helper / 依存関係メモ
   https://github.com/openai/skills/blob/main/skills/.curated/slides/references/pptxgenjs-helpers.md

5. OpenAI Skills slides の表示・既定プロンプト設定
   https://github.com/openai/skills/blob/main/skills/.curated/slides/agents/openai.yaml

補足:

• 本文中で触れた scripts/ 配下の役割は、主に SKILL.md と pptxgenjs-helpers.md の記述を要約したものです。