Document Illustrator Skill

AI による文書内容の自動理解と、プロフェッショナルな挿絵生成ツール。特定のフォーマットに依存せず、ドキュメントを自動解析して最適な図版を生成します。

🎯 主な特長

✨ AI スマート要約：文書内容を自動理解し、コアテーマをインテリジェントに抽出
🎨 フォーマット非依存：Markdown、プレーンテキスト、PDF などあらゆる形式に対応
📐 柔軟な比率：16:9（横長）と 3:4（縦長）をサポート
🖼️ カバー画像オプション：文書全体を要約するカバー画像の生成が可能
🎭 3 種類のスタイル：グラデーションガラスカード、チケット風、ベクターイラスト

🚀 使い方

Codex に直接指示

このドキュメントに挿絵を生成して：/path/to/document.md

または：

この記事に挿絵を何枚か生成してほしい

📝 完全なワークフロー

ステップ 1：Codex がドキュメントを読み取り理解

挿絵生成をリクエストすると、Codex は以下の処理を行います：

Read ツールを使ってドキュメント全体を読み取り
AI が文書の内容と構造を分析
コアテーマと要点を特定

ドキュメント形式を気にする必要なし：

✅ 標準 Markdown（##、###）
✅ 区切り線形式（======、------）
✅ プレーンテキスト段落
✅ その他あらゆる形式

ステップ 2：設定オプション（3 つの質問）

Codex があなたの好みを尋ねます：

質問 1：画像の比率

画像の比率を選んでください：
1. 16:9 (横長) - プレゼンテーション、スライド、横長表示に最適
2. 3:4 (縦長) - SNS、スマホ表示、ポスターに最適

選択 (1/2)：

質問 2：カバー画像

カバー画像を生成しますか？
カバー画像はドキュメントの全コア情報を要約し、一連の挿絵のガイドとなります。

1. はい - カバー画像 + 内容挿絵を生成
2. いいえ - 内容挿絵のみ生成

選択 (1/2)：

質問 3：内容挿絵の枚数

何枚の内容挿絵を生成しますか？
推奨範囲：3～10 枚
ドキュメントの内容に基づき、6 枚を推奨

数字を入力：

ステップ 3：Codex が内容を要約して表示

指定した枚数に基づき、Codex がインテリジェントにドキュメントを要約し、確認を求めます：

📋 内容の要約が完了しました

📄 カバー画像の内容：（カバー生成選択時）
「AI プログラミングツールの概念進化：Rules から Skills へ」
- コア概念：静的コンテキスト vs 動的コンテキスト
- 進化の道筋：Rules → Commands → MCP → Modes → Skills
- ベストプラクティス：2 つのコアツールへの集約

📚 内容挿絵（合計 6 枚）：

1. Rules の誕生と進化
   内容：初期モデルの幻覚問題、rules ファイルの役割、静的コンテキストの概念

2. Commands とワークフローのパッケージ化
   内容：固定ワークフローの登場、スラッシュコマンド、チーム共有

3. MCP Servers がもたらす動的機能
   内容：サードパーティツール統合、OAuth 認証、コンテキスト肥大化問題

4. Modes と Subagents の登場
   内容：ペルソナプロンプト、システムプロンプト修正、信頼性設計、Hooks による決定性

5. Skills による動的コンテキストの統一
   内容：Skills の概念、動的ロード、プログラミングツールの最適化

6. ベストプラクティスと今後の展望
   内容：Rules の使用提案、Skills の探求、核心理念のまとめ

✓ すべての内容をカバー、漏れなし

挿絵の生成を開始してよろしいですか？(Y/N)

重要な保証：

✅ 内容完全性：すべての重要な情報がいずれかの画像に含まれます
✅ 論理明瞭：内容の自然な論理に従ってセグメント化
✅ ユーザー制御可能：要約結果を表示し、ユーザーの確認を待ちます

ステップ 4：挿絵の生成

確認後、Codex が Python スクリプトを呼び出して画像を生成：

🖼️  挿絵を生成中...

カバー画像を生成中...
  ✓ 保存完了: /path/to/document/images/cover.png

1/6 枚目を生成中...
  タイトル: Rules の誕生と進化
  ✓ 保存完了: /path/to/document/images/illustration-01.png

2/6 枚目を生成中...
  タイトル: Commands とワークフローのパッケージ化
  ✓ 保存完了: /path/to/document/images/illustration-02.png

...

✨ 完了！合計 7 枚の挿絵を生成（カバー 1 枚 + 内容 6 枚）

ステップ 5：出力結果

出力先：ドキュメントと同じディレクトリ内の images/ フォルダ

/path/to/your/document/
└── images/
    ├── cover.png              # カバー画像（選択時）
    ├── illustration-01.png    # 1 枚目の内容挿絵
    ├── illustration-02.png    # 2 枚目の内容挿絵
    ├── illustration-03.png
    ├── illustration-04.png
    ├── illustration-05.png
    └── illustration-06.png

🎨 3 種類のスタイル説明

1. グラデーションガラスカードスタイル (gradient-glass)

特徴：

Apple Keynote 風のミニマリズム
グラスモーフィズム（Glassmorphism）デザイン
深い漆黒またはピュアホワイトのベース
流れるようなオーロラグラデーション
3D ガラスオブジェクトと発光エフェクト

適用シーン：

テクノロジー製品紹介
データ分析レポート
未来トレンド展望
製品機能デモ

2. チケット風スタイル (ticket)

特徴：

デジタルミニマルなチケットデザイン
高コントラストの白黒配色
搭乗券や入場券のような構造
正確な幾何学的区画
中日混在、多方向テキストレイアウト

適用シーン：

インフォグラフィック
統計データ表示
タイムラインとフローチャート
要点のまとめ

3. ベクターイラストスタイル (vector-illustration)

特徴：

フラットベクターイラスト
均一な太さの黒い輪郭線
レトロでソフトな配色
幾何学的な処理
横長パノラマ構図

適用シーン：

ストーリーテリング
概念説明
教育コンテンツ
ブランドプロモーション

💡 使用例

例 1：完全なフロー

ユーザー: ~/blog/ai-tools.md に挿絵を生成して、チケット風で

Codex: はい、まずこのドキュメントを読み込みます...
       [ドキュメントを読み込み、内容を分析]

       ドキュメントの長さは約 3000 文字、AI ツールの進化に関する内容です。

       画像の比率を選んでください：
       1. 16:9 (横長)
       2. 3:4 (縦長)

ユーザー: 1

Codex: カバー画像を生成しますか？
       1. はい
       2. いいえ

ユーザー: はい

Codex: 何枚の内容挿絵を生成しますか？
       推奨範囲：3～10 枚
       ドキュメントの内容に基づき、5 枚を推奨

ユーザー: 5

Codex: [要約された 5 つのテーマを表示]
       挿絵の生成を開始してよろしいですか？

ユーザー: Y

Codex: [Python スクリプトを呼び出して 6 枚の画像を生成]
       ✨ 完了！挿絵は ~/blog/images/ に保存されました

例 2：プレーンテキストドキュメント

ユーザー: このプレーンテキストのノートに挿絵を生成して

Codex: [ノートを読み込み、見出しがなくても内容を理解]
       [インテリジェントに 3 つのコアテーマを特定]
       [設定を確認、要約を表示、挿絵を生成]

例 3：カスタム枚数

ユーザー: 8 枚欲しい、縦長で、カバーはなし

Codex: はい、16:9 縦長、カバーなし、8 枚の内容挿絵ですね。
       [ドキュメントを 8 つのテーマに要約]
       [要約結果を表示し、ユーザー確認後に生成]

🔧 技術詳細

画像仕様

以下の比率と解像度は Gemini に適用されます。Nebula image2-4k は 16:9、3840x2160 のみサポートします。ユーザーが Nebula を選択した場合、直接 4K を使用します。ユーザーが 2K や縦長画像を要求した場合は、先に制限を説明し、対応可能な方式を決定します。

比率	解像度	適用シーン
16:9	2560x1440 (2K)	プレゼンテーション、横長表示
3:4	1920x2560	SNS、縦長表示

選択可能な 4K 解像度：

16:9 → 3840x2160
3:4 → 2880x3840

API 呼び出し

Gemini モデル：gemini-3-pro-image-preview（スクリプトのデフォルト値）
Nebula モデル：gpt-image-2-4k、image2-4k グループトークンを使用
コスト：1 画像 = 1 回の API 呼び出し
速度：バックエンド負荷に依存。Nebula 4K リクエストのタイムアウトは 1800 秒

バックエンド選択と Nebula 呼び出し

nanobanana グループ

ユーザーが nanobanana を指定した場合、両方のスクリプトで --provider nanobanana を渡します。統一 .env で専用の NEBULA_NANOBANANA_API_KEY（nanobanana グループトークン）を使用し、 image2-4k のキーを再利用しません。NEBULA_NANOBANANA_MODEL のデフォルトは gemini-3.1-flash-image で、トークンがサポートする他のモデルも指定可能です。ILLUSTRATOR_IMAGE_PROVIDER=nanobanana をデフォルトに設定できます。単一画像、バッチ生成ともに 16:9、3:4 をサポート。1K、2K、4K をリクエスト可能で、デフォルトは 2K。具体的なサポート値と実際のピクセル数は選択したモデルに依存し、image2-4k の 4K 横長制限は適用されません。

統一 .env で ILLUSTRATOR_SINGLE_RATIO を単一画像のデフォルト比率、 ILLUSTRATOR_BATCH_RATIO をバッチのデフォルト比率、ILLUSTRATOR_RESOLUTION をデフォルトのリクエスト解像度として設定します。両方のエントリポイントで --ratio、--resolution による設定上書きをサポートします。設定がないか値が空の場合、比率は 16:9、解像度はバックエンドのデフォルト値（Gemini/nanobanana は 2K、image2-4k は 4K）を使用します。これらの設定はすべてのバックエンドに適用されます。バックエンドの制限と競合する場合は、リクエスト前にエラーを出力し、設定を調整するか明示的に上書きする必要があります。

python -X utf8 scripts/generate_single_image.py --provider nanobanana --title "テーマ" --content "挿絵の内容" --style-file styles/ticket.md --ratio 3:4 --resolution 2K --output output/banana.png
python -X utf8 scripts/generate_illustrations.py article.md --provider nanobanana --style ticket --level h2 --resolution 2K

Gemini ネイティブの POST /v1beta/models/{model}:generateContent を呼び出し、inlineData から画像をデコードして検証し、完全な Base64 レスポンスを保持しません。Google SDK は不要です。現在の接続はテキストからの画像生成のみをサポート。タイムアウト後は課金タスクを自動再送しません。詳細は README.md と公式 API ドキュメントを参照してください。

従来の image2-4k グループ

両方のスクリプトで --provider gemini|nebula をサポートします。指定がない場合は ILLUSTRATOR_IMAGE_PROVIDER を読み取り、未設定の場合は Gemini を使用します。ユーザーが明示的に Nebula を指定した場合は --provider nebula を渡します。他のサービスに切り替えないでください。統一パス ~/.agents/skills/document-illustrator/.env に NEBULA_API_KEY を設定するか、同名の環境変数を使用します。トークンは image2-4k グループに属している必要があります。 Nebula は Gemini キーや Google SDK を必要としませんが、Pillow と python-dotenv が必要です。

python -X utf8 scripts/generate_single_image.py --provider nebula --title "テーマ" --content "確定した挿絵の内容" --style-file styles/ticket.md --output output/image-01.png --resolution 4K
python -X utf8 scripts/generate_illustrations.py article.md --provider nebula --style ticket --level h2 --resolution 4K

スクリプトは POST https://img-api.apinebula.ai/v1/images/generations を呼び出し、固定で gpt-image-2-4k、3840x2160、quality=high、response_format=url を使用します。 URL を優先的に読み取り、Base64 にも対応。保存前に実際のピクセル数を検証し、サーバー側の JPEG をローカル拡張子に対応する形式に変換します。 API レスポンスは <画像ファイル名>.response.json として保存され、ダウンロード失敗時はその中の一時リンクを再利用して再ダウンロードを試みます。 POST タイムアウト後はタスクの状態が不明な可能性があるため、自動再送しません。まずサーバー側の状態を確認し、重複課金を避けてください。 HTTP 403 または接続が確立されていない場合は、http://127.0.0.1:81 プロキシを試みます。現在はテキストからの画像生成のみをサポート。参照画像編集は未実装です。

完全な設定説明とオフラインテストコマンドは README.md を参照し、 API パラメータは公式ドキュメントに基づきます。

環境要件

必須：

pip install google-genai pillow python-dotenv

API キー：

Codex、Claude などすべての Agent は統一して ~/.agents/skills/document-illustrator/.env を読み取ります
Windows では %USERPROFILE%\.agents\skills\document-illustrator\.env に対応
このファイルのみを読み込み、その値は同名の環境変数を上書きします。ファイルが存在しない場合は既存の環境変数のみを使用し、他の場所は検索しません
Gemini は GEMINI_API_KEY、Nebula は NEBULA_API_KEY を使用
nanobanana グループは NEBULA_NANOBANANA_API_KEY を使用。モデル設定は上記グループ説明を参照

📊 内容要約の原則

Claude は内容を要約する際、以下の原則に従います：

1. 完全性優先

✅ すべての重要な情報が含まれる
✅ 重要な概念を見逃さない
✅ 原文のコアポイントを保持

2. 論理明瞭

内容の自然な論理に従ってセグメント化
関連する内容をグループ化
ナラティブの一貫性を維持

3. バランスの取れた割り当て

各画像に同程度の情報量を含める
特定の画像が過密または疎にならないようにする
内容の重要度に応じて調整

4. ユーザー制御可能

要約結果をユーザーに表示して確認
ユーザーは調整を要求可能
確認後に生成を開始

🐛 トラブルシューティング

問題 1：API キーエラー

エラーメッセージ：

Error: Invalid API key

解決方法：

.env で対応するバックエンドの GEMINI_API_KEY または NEBULA_API_KEY を確認。Nebula の場合はトークングループも確認
API キーが有効で期限切れでないことを確認
新しいキーを取得：https://makersuite.google.com/app/apikey

問題 2：内容要約が期待通りでない

問題：要約されたテーマが期待と異なる

解決方法：

要約表示段階で、期待を Codex に伝える
Codex が再要約して調整
満足してから生成を開始

問題 3：画像生成失敗

考えられる原因：

ネットワーク接続の問題
API クォータの枯渇
内容が長すぎて制限を超過

解決方法：

ネットワーク接続を確認
API クォータを確認
画像枚数を増やして内容を分散

💰 コスト見積もり

画像枚数	API 呼び出し回数	推定コスト
カバーなし + 3 枚	3 回	低
カバーあり + 5 枚	6 回	中
カバーあり + 10 枚	11 回	やや高

推奨：

短い文書（<1000 字）：3～5 枚
中程度の文書（1000～3000 字）：5～7 枚
長い文書（>3000 字）：8～10 枚

📚 ベストプラクティス

1. 適切な画像枚数の選択

少なすぎる場合：

各画像の情報量が多くなりすぎる
理解や記憶が難しい

多すぎる場合：

内容が分散する
コストと生成時間が増加

推奨：

文書の長さに応じて選択
各画像で 1～2 のコアポイントをカバー

2. 用途に応じた比率の選択

16:9 が適している場合：

PPT プレゼンテーション
Web サイトのバナー
動画のサムネイル
ブログのアイキャッチ（デスクトップ向け）

3:4 が適している場合：

SNS（Instagram、小红书）
モバイル向け記事
ポスターデザイン
縦長動画

3. カバー画像の使用

カバー画像の生成を推奨するシーン：

シリーズ記事（統一的なガイドとして）
SNS シェア（プレビュー画像として）
ドキュメントのトップページ（全文を要約）

生成しなくてもよいシーン：

内部利用のみ
画像枚数がすでに十分
コストを抑えたい場合

4. スタイル選択の提案

技術ドキュメント → グラデーションガラスカードスタイル データレポート → チケット風スタイル チュートリアルストーリー → ベクターイラストスタイル 製品紹介 → グラデーションガラスカードスタイル

🔄 動作原理

従来の方法（廃止）

[コード] ドキュメントを読み取り → ## ### 見出しを認識 → 機械的に分割
       ↓
    特定の形式に依存
    内容を省略しやすい
    インテリジェントでない

新しい方法（現在の実装）

[Claude] ドキュメントを読み取り → AI が内容を理解 → インテリジェントにテーマを要約
         ↓
      形式に依存しない
      内容が完全
      ユーザーが制御可能

主な違い：

❌ 旧方式：コード解析に依存し、標準形式のみ処理可能
✅ 新方式：AI が内容を理解し、あらゆる形式を処理可能

🎯 他のツールとの比較

機能	Document Illustrator	従来の PPT ツール	AI 画像生成ツール
文書内容の理解	✅ AI がインテリジェントに理解	❌ 手動で入力が必要	❌ 手動で入力が必要
形式依存性	✅ 形式に依存しない	❌ 特定の形式に依存	✅ 依存しない
内容の完全性	✅ 自動検証	⚠️ 手動で確認	❌ 保証できない
バッチ生成	✅ 一度に複数枚生成	❌ 1 枚ずつ作成	⚠️ 複数回の入力が必要
スタイルの一貫性	✅ 自動維持	⚠️ 手動で調整	⚠️ プロンプトの繰り返しが必要

📞 ヘルプ

ご質問やご提案がある場合：

Codex で直接質問
Skill ディレクトリを確認：~/.agents/skills/document-illustrator

AI に内容の理解と要約を任せて、プロフェッショナルな挿絵を生成しましょう！ ✨

お気に入りのAIに質問する

ドキュメント

Document Illustrator Skill

🎯 主な特長

🚀 使い方

Codex に直接指示

📝 完全なワークフロー

ステップ 1：Codex がドキュメントを読み取り理解

ステップ 2：設定オプション（3 つの質問）

質問 1：画像の比率

質問 2：カバー画像

質問 3：内容挿絵の枚数

ステップ 3：Codex が内容を要約して表示

ステップ 4：挿絵の生成

ステップ 5：出力結果

🎨 3 種類のスタイル説明

1. グラデーションガラスカードスタイル (gradient-glass)

2. チケット風スタイル (ticket)

3. ベクターイラストスタイル (vector-illustration)

💡 使用例

例 1：完全なフロー

例 2：プレーンテキストドキュメント

例 3：カスタム枚数

🔧 技術詳細

画像仕様

API 呼び出し

バックエンド選択と Nebula 呼び出し

nanobanana グループ

従来の image2-4k グループ

環境要件

📊 内容要約の原則

1. 完全性優先

2. 論理明瞭

3. バランスの取れた割り当て

4. ユーザー制御可能

🐛 トラブルシューティング

問題 1：API キーエラー

問題 2：内容要約が期待通りでない

問題 3：画像生成失敗

💰 コスト見積もり

📚 ベストプラクティス

1. 適切な画像枚数の選択

2. 用途に応じた比率の選択

3. カバー画像の使用

4. スタイル選択の提案

🔄 動作原理

従来の方法（廃止）

新しい方法（現在の実装）

🎯 他のツールとの比較

📞 ヘルプ

関連スキル

steipete/songsee

affaan-m/frontend-design

mattpocock/improve-codebase-architecture

lobehub/add-provider-doc

addyosmani/browser-testing-with-devtools

bytedance/chart-visualization