Joeldkelly/banner-forge

banner-forge は何をしますか？

1つのブランド設定から、完全でネットワーク対応のディスプレイキャンペーンを生成します。設定優先、Figmaはオプション。すべての成果物は150KB未満、clickTag配線済み、バリデーター通過済み。

呼び出すタイミング

以下のようなリクエストがあった場合にこのスキルを使用します：

• バナー広告、ディスプレイ広告、IABサイズ、HTML5バナーの生成
• クリエイティブのアドネットワーク仕様へのリサイズ
• Google Ads / DV360 / TTD / Adform / Amazon DSP 向けZIPファイルの作成
• Figmaフレームからの本番バナー生成
• GSAPを使用したバナーアニメーション
• 既存HTML5バナーのネットワークルールに対する検証

呼び出さないでください： Meta/LinkedIn/TikTokのニュースフィード用静止画や動画クリエイティブ（MetaはHTML5を拒否します — 利用可能な場合はV1静止画/動画パスに誘導するか、直接静止画PNG/MP4を生成してください）。

基本原則

単一パイプライン、ファイルベース、再開可能。 各ステージは前のステージのJSONサイドカーファイルを読み込み、自身のファイルを書き込みます。エラーは1つのステージに限定されます。一度構築したものを再構築する必要はありません。

banner.config.json
    → scripts/build.js    → build/<size>/{index.html, assets/, meta.json}
    → scripts/render.js   → build/<size>/{backup.png, preview.gif, preview.mp4}
    → scripts/package.js  → dist/<network>/<size>.zip
    → scripts/validate.js → dist/validation-report.json

標準フロー（設定 → 成果物）

1. プロジェクトルートに banner.config.json が存在することを確認します。ない場合は banner.config.example.json をコピーし、ユーザーに記入を依頼します。
2. node scripts/build.js を実行します — templates/gsap/ 内のテンプレートが設定から埋められ、サイズごとに build/<size>/ に書き込まれます。
3. node scripts/render.js を実行します — Puppeteerが最終アニメーションフレームを backup.png（sharp圧縮）としてキャプチャし、次に page.screencast によるネイティブMP4、gifskiによるGIFを生成します。
4. node scripts/package.js を実行します — 正しいマニフェスト（Adform用 manifest.json、Google用 index.html（ルートにclickTag変数あり））を含むネットワーク別ZIPを dist/<network>/<size>.zip に構築します。
5. node scripts/validate.js を実行します — ファイルサイズ（≤150KB）、clickTagの存在、必要なアセット、マニフェストの正確性をチェックします。dist/validation-report.json を書き込みます。
6. ユーザーに結果を要約します：構築されたサイズ、総バイト数、バリデーションエラー、ZIPファイルの保存場所。

5つのステージはすべて scripts/build-all.sh または npm run all でラップされています。

エントリーポイント

設定ファイルから（デフォルト、Figmaなし）

ユーザーが banner.config.json を提供または編集します。スキルは4段階のパイプラインを実行します。スキーマについては banner.config.example.json を参照してください。

Figmaフレームから

/banner-from-figma <url> は scripts/figma-import.js をトリガーし、Figma MCPを使用してトークン、テキストスタイル、アセットを banner.config.json に抽出し、その後のデフォルトパイプラインにフォールスルーします。

無料シートFigmaユーザー向けのグレースフルフォールバック： 書き戻しには有料Figmaシートが必要です。スキルはこれを検出し、読み取り専用モードにダウングレードし、生成された設定をFigmaファイルにプッシュする代わりにディスクに書き込みます。1つの警告をログに記録して続行します。

ブリーフから（Figmaなし、設定なし）

/banner-from-brief <path> はブリーフ（マークダウン、テキスト、または将来のPDF抽出）を読み取り、Claudeにブランドトークン、コピー、サイズ、ネットワークを banner.config.json に合成させ、その後のデフォルトパイプラインにフォールスルーします。

標準サイズマトリックス

完全なテーブルは references/SIZES.md を参照してください。MVPとしての15サイズ：

300x250, 336x280, 300x600, 728x90, 970x90, 970x250, 160x600, 120x600, 320x50, 320x100, 300x50, 300x1050, 468x60, 250x250, 200x200。

ルール：

• 50KB以下のサイズ（300x50、320x50、300x600モバイルファーストバリアント）は 必ず CSSのみのテンプレートを使用し、GSAPは使用しません。references/ANIMATION.md を参照してください。
• 固定のポライトロード上限（Google 初期150KB / 合計2.2MB）があるサイズは、scripts/validate.js であらかじめ検証されます。

clickTagパターン

1つのZIPがGoogle、DV360、TTD、Adformのすべてで合格するように、二重グローバルパターンを使用します：

<script>
  var clickTag = "https://example.com/landing";
  var clickTAG = clickTag; // TTD + Adform レガシー大文字
</script>

Adformではさらに、ZIPルートに manifest.json が必要です。scripts/package.js がネットワークごとにこれを処理します。

完全なルール：references/CLICKTAG.md。

アニメーション

• デフォルト： GSAP 3.13+（2025年4月時点で商用利用無料、広告を含む）。npm経由でバンドルされ、ビルドにインライン化されます。
• ≤50KBサイズ： CSSのみのテンプレート。JSバイト数はゼロ。
• 禁止： lottiefiles.com から読み込まれたLottie（Google AdsでCORSが拒否されます）。Lottieが必要な場合は、JSONをインライン化してください — そのテンプレートはV1に格納されます。
• 禁止： Riveランタイム、生のCanvas、プログラマティックディスプレイでのWebGL（DSPが拒否します）。

完全な決定木は references/ANIMATION.md を参照してください。

サポートされるネットワーク

MVP：Google Ads、DV360、The Trade Desk、Adform。V1：Amazon DSP（2x Retina）。

ネットワークごとの違い（マニフェスト、ポライトロード、Retina、clickTagの大文字小文字）は、references/NETWORK_SPECS.md に基づいて scripts/package.js で処理されます。

フォント

Fontsourceファミリー（OFL、Apache、Ubuntu Font License）のみをバンドルします。セルフホストのみ — 実行時に fonts.googleapis.com にアクセスすることは 絶対に しないでください（GDPR）。

拒否： Helvetica、Futura、Adobe Fontsファミリー、ファウンドリフォント（Monotype、H&Co、Commercial Type）。Inter / Figtree / Manropeに置き換え、警告をログに記録します。

完全なフォントルールは references/LEGAL.md を参照してください。

画像

MVP：ユーザー提供のヒーロー画像のみ。

V1：Nano Banana（Gemini 2.5 Flash Image）またはFLUX.1 schnell（Apache 2.0）によるオプションのAI生成。絶対に FLUX.1 devは使用しないでください — 非商用です。references/IMAGE_MODELS.md を参照してください。AI出力はC2PAメタデータの保存をトリガーします。これを除去するとプラットフォームポリシーに違反します。

監視すべき障害モード

1. Puppeteer初回ダウンロード — 約170MBのChromium。最初の npm install の前にユーザーに警告します。
2. gifskiがインストールされていない場合 — package.json の optionalDependencies にあり、render.jsは欠落している場合、ffmpegのみにフォールバックし、品質低下の警告をログに記録します。
3. 設定に clickUrl がない場合 — ビルドを拒否します。URLなしのclickTagは無意味です。
4. 設定が assets/fonts/ にないフォントを参照している場合 — 警告を出して代替フォントを使用します。
5. ヒーロー画像がない場合 — ビルドはニュートラルなプレースホルダーで続行され、バリデーターがフラグを立てます。
6. Figma MCP書き戻しが失敗した場合（無料シート） — 警告をログに記録し、設定をディスクに書き込んで続行します。
7. ネットワーク名のタイプミス — package.jsが有効なネットワークを一覧表示して終了します。

段階的な情報開示

上記のすべてがコンテキスト内リファレンスです。より詳細な資料は references/ にあり、必要なときだけ読み込まれます：

• references/SIZES.md — 標準サイズテーブル、ネットワークごとの可用性、ファイルサイズ上限。
• references/NETWORK_SPECS.md — マニフェスト形式、ポライトロード、Retina、ネットワークごとのclickTagの大文字小文字。
• references/CLICKTAG.md — 正確な二重グローバルスニペットとネットワークごとのバリエーション。
• references/ANIMATION.md — GSAP vs CSS vs Lottieの決定木、タイミング規則。
• references/IMAGE_MODELS.md — Nano Banana、FLUX、Imagen、ライセンス、透かしリスク。
• references/LEGAL.md — AI開示、フォントライセンス、商標、FTC/DSA/EU AI法。

成功基準

正常に実行されると、各サイズに対して以下が生成されます：

• スタンドアロンで動作する index.html（clickTagブリッジを除く外部CDNなし）
• 40KB未満の backup.png
• GIFプレビュー（オプション）とMP4プレビュー（オプション）
• 150KB未満のネットワーク別ZIP、マニフェスト+ポライトロード+二重clickTagを含む
• pass または pass-with-warnings のバリデーションレポートエントリ

エラーは明示的に報告します。ユーザーに通知せずにバリデーターがフラグを立てたバナーを出荷することは絶対にしないでください。