metaads

ワークフローのルーティング（システムプロンプト）

重要：ユーザーの意図に基づいて、適切なワークフローにルーティングしてください。

ユーザーが Meta Ads API アクセスをセットアップまたは設定する場合： 例：「meta ads をセットアップ」「meta ads に接続」「facebook ads を設定」「トークンの有効期限が切れた」「meta ads のセットアップ」「--check による認証情報エラー」 -> 読み込む： ~/.claude/skills/MetaAds/workflows/Setup.md -> 実行： Business Manager、アプリ、トークン、.env を含むセットアップ全体をユーザーに順を追って案内します。

ユーザーがキャンペーンの公開、作成、開始を希望する場合： 例：「広告を公開」「キャンペーンを作成」「キャンペーンを開始」「広告画像をアップロード」「meta ads を公開」「このキャンペーンを Meta に送信」「広告セットを作成」 -> 読み込む： ~/.claude/skills/MetaAds/workflows/PublishCampaign.md -> 実行： キャンペーン公開ワークフロー -> 認証情報に問題がある場合は、先に Setup.md にルーティングします。

ユーザーがパフォーマンスや指標の確認、結果の分析を希望する場合： 例：「meta 広告のパフォーマンスを確認」「ROAS」「どの広告が好調か」「広告費」「キャンペーン指標」「広告の成果を確認」「オーディエンスの内訳」「クリエイティブのパフォーマンス」 -> 読み込む： ~/.claude/skills/MetaAds/workflows/AnalyzePerformance.md -> 実行： パフォーマンス分析ワークフロー -> 認証情報に問題がある場合は、先に Setup.md にルーティングします。

ユーザーがキャンペーンの管理（一時停止／再開／ステータス確認）を希望する場合： 例：「キャンペーンを一時停止」「キャンペーンを再開」「キャンペーンのステータス」「キャンペーン一覧」 -> uv run ~/.claude/skills/MetaAds/tools/Publish.py を直接使用し、--pause、--resume、--status、または --list を指定します。

---

このスキルを有効にするタイミング

セットアップと設定（カテゴリ 0）

• 「meta ads をセットアップ」「meta ads API に接続」「facebook ads を設定」
• 「meta ads のセットアップ」「広告アカウントへの接続方法」
• 「トークンの有効期限が切れた」「トークンエラー」「meta ads にアクセスできない」
• 「meta トークンを更新」「アクセストークンを再発行」
• --check による認証情報エラー全般

キャンペーンの公開（カテゴリ 1）

• 「広告を公開」「キャンペーンを作成」「キャンペーンを開始」
• 「これを Meta に送信」「キャンペーンをセットアップ」「広告画像をアップロード」
• 「meta ads を公開」「広告セットを作成」「キャンペーンを構築」
• 「このキャンペーン設定を公開」「広告を配信開始」

パフォーマンス分析（カテゴリ 2）

• 「meta 広告のパフォーマンスを確認」「広告の成果を確認」
• 「ROAS」「広告費用対効果」「広告費」「広告指標」
• 「どの広告が好調か」「最も成果の高い広告」
• 「キャンペーン指標」「広告セットのパフォーマンス」「クリエイティブのパフォーマンス」
• 「オーディエンスの内訳」「年齢／性別の内訳」
• 「CTR」「CPC」「CPM」「CPA」「顧客獲得単価」

キャンペーン管理（カテゴリ 3）

• 「キャンペーンを一時停止」「キャンペーンを再開」「キャンペーンを有効化」
• 「キャンペーンのステータス」「キャンペーン一覧」「キャンペーンを表示」

---

主な機能

セットアップガイド：

• Business Manager -> Developer App -> Token -> .env の全手順を案内します。
• 2 種類のトークン方式：システムユーザー（有効期限なし）またはユーザートークン（60 日間有効、自動更新あり）
• トークン交換を自動化します（エージェントが curl コマンドを実行します）。
• コンバージョントラッキング用のピクセル設定を案内します。
• よくある問題をすべて、具体的な解決策とともに診断します。

キャンペーンの公開：

• ローカルディレクトリから Meta に画像をアップロードします。
• キャンペーンの階層全体を作成します（キャンペーン -> 広告セット -> クリエイティブ -> 広告）。
• 複数の画像／テキスト／見出しを使った Advantage+ の柔軟なクリエイティブに対応します。
• すべてのオブジェクトを手動確認用に一時停止状態で作成します。
• 再現可能なキャンペーンを実現する JSON 設定駆動方式です。

パフォーマンス分析：

• DTC ベンチマーク（CTR、CPM、CPA、ROAS）を含むアカウントレベルの概要
• キャンペーン、広告セット、広告レベルの指標
• キャンペーンを詳しく分析するための日次トレンド分析
• オーディエンスの内訳（年齢、性別、プラットフォーム、デバイス）
• チャネル横断分析のために、データを Analytics/meta-ads/ に同期します。
• スプレッドシート分析用の CSV エクスポート

キャンペーン管理：

• ステータス付きですべてのキャンペーンを一覧表示
• キャンペーンの階層を表示（キャンペーン -> 広告セット -> 広告）
• キャンペーンを一時停止／再開

スクリプト

スクリプト	用途
tools/Publish.py	キャンペーンの作成、画像のアップロード、一時停止／再開
tools/Analytics.py	パフォーマンス指標、内訳、同期、エクスポート

どちらのスクリプトも PEP 723 のインライン依存関係を使用しています。スキルディレクトリから uv run で直接実行できます。インストールやコピーは不要です。

使用方法

スキルディレクトリからスクリプトを直接実行します。現在の作業ディレクトリ（Path.cwd()）から .env を読み込むため、プロジェクトのルートディレクトリから実行してください。

# From your project root (where .env lives):
uv run ~/.claude/skills/MetaAds/tools/Publish.py --check
uv run ~/.claude/skills/MetaAds/tools/Analytics.py --summary

前提条件： uv がインストールされている必要があります。インストールされていない場合：curl -LsSf https://astral.sh/uv/install.sh | sh

環境変数（.env）：

変数	必須	説明
META_ADS_ACCESS_TOKEN	はい	システムユーザーまたは有効期間の長いユーザートークン
META_ADS_ACCOUNT_ID	はい	act_ プレフィックス付きの広告アカウント ID
FACEBOOK_APP_ID	トークン更新時	トークン交換用のアプリ ID
FACEBOOK_APP_SECRET	トークン更新時	トークン交換用のアプリシークレット

---

キャンペーン目的のリファレンス

キャンペーン設定では、以下の目的を使用してください。

目的	使用する場面	最適化目標
OUTCOME_SALES	DTC の購入、Shopify のコンバージョン	OFFSITE_CONVERSIONS
OUTCOME_LEADS	リード獲得、メール登録、クイズ形式のファネル	LEAD_GENERATION
OUTCOME_TRAFFIC	ランディングページへの訪問、ブログへのトラフィック	LINK_CLICKS
OUTCOME_AWARENESS	ブランド認知、動画視聴	REACH または IMPRESSIONS
OUTCOME_ENGAGEMENT	投稿へのエンゲージメント、ページへの「いいね！」	POST_ENGAGEMENT

---

キャンペーン設定テンプレート

あらゆる DTC ブランドに使える汎用テンプレートです。

{
  "campaign": {
    "name": "campaign-name-month-year",
    "objective": "OUTCOME_SALES"
  },
  "adsets": [
    {
      "name": "Broad-25-54-US",
      "daily_budget": 5000,
      "targeting": {
        "age_min": 25,
        "age_max": 54,
        "genders": [0],
        "geo_locations": {"countries": ["US"]},
        "publisher_platforms": ["facebook", "instagram"],
        "facebook_positions": ["feed", "video_feeds", "story", "reels"],
        "instagram_positions": ["stream", "story", "reels", "explore"]
      },
      "optimization_goal": "OFFSITE_CONVERSIONS",
      "bid_strategy": "LOWEST_COST_WITHOUT_CAP"
    }
  ],
  "creative": {
    "images_directory": "./path/to/ad-images/",
    "primary_texts": [
      "Primary text variant 1 — lead with the hook or pain point",
      "Primary text variant 2 — lead with the benefit or social proof",
      "Primary text variant 3 — lead with a comparison or price anchor"
    ],
    "headlines": [
      "Short Punchy Headline",
      "Benefit-Driven Headline",
      "Price/Value Headline"
    ],
    "descriptions": [
      "Supporting description with key differentiator"
    ],
    "link_url": "https://yoursite.com/landing-page",
    "url_parameters": "utm_source=meta&utm_medium=paid-social&utm_campaign=campaign-name&utm_content={{ad.name}}",
    "call_to_action_type": "SHOP_NOW"
  }
}

設定に関する注意：

• daily_budget はセント単位です（5000 = 1 日あたり $50.00）
• genders：0 = すべて、1 = 男性、2 = 女性
• {{ad.name}} は Meta の動的パラメーターです。広告名が自動入力されます
• call_to_action_type の選択肢：SHOP_NOW、LEARN_MORE、SIGN_UP、GET_OFFER、ORDER_NOW、SUBSCRIBE、BOOK_NOW

---

DTC ベンチマークのリファレンス

指標	良好	まずまず	要改善	意味
CTR	>1.5%	1-1.5%	<1%	クリックされたインプレッションの割合です。低い場合、クリエイティブが響いていません
CPM	<$15	$15-25	>$25	1000 インプレッションあたりの費用です。高い場合、競争の激しいオークションか、オーディエンスが狭いことを示します
CPC	<$1	$1-2	>$2	クリック単価です。高い場合、CTR が低く、費用が増加しています
CPA	<$30	$30-50	>$50	購入あたりの費用です。最終的な効率を測る指標です
ROAS	>3x	2-3x	<2x	広告費 $1 あたりの売上です。2x 未満の場合、通常は売上原価を差し引くと赤字です
フリークエンシー	1-3	3-5	>5	各ユーザーが広告を見た平均回数です。高い場合、広告疲れが起きています
フック率	>25%	15-25%	<15%	動画の最初の 3 秒を視聴した人の割合です。低い場合、冒頭に魅力がありません
視聴維持率	>10%	5-10%	<5%	15 秒以上視聴した人の割合です。低い場合、コンテンツが関心を維持できていません

---

最適化プレイブック

成果の良いものを拡大する：

• 2～3 日ごとに予算を 20～30% 増やします（学習がリセットされるため、一度に増やさないでください）
• 成果の良い広告セットを複製し、新しいオーディエンスを設定します
• 購入者から類似オーディエンスを作成します

成果の低いものを改善する：

• CTR < 1%：新しいフックや画像をテストします。クリエイティブがスクロールする指を止められていません
• CTR > 2% なのに購入がない：広告ではなく、ランディングページに問題があります
• CPA が高すぎる：ターゲティングを絞るか、ファネル下部のオーディエンスをテストします
• フリークエンシー > 4：新しいクリエイティブに入れ替えます
• 48 時間経っても広告費が消化されない：一時的に最適化対象を Link Clicks に切り替え、その後 Conversions に戻します

Meta の学習フェーズ：

• 学習フェーズを終了するには、各広告セットで 7 日間に約 50 件のコンバージョンが必要です
• 学習中は編集しないでください（学習期間がリセットされます）
• 週 50 件のコンバージョンに予算が足りない場合は、よりファネル上部のイベント（Purchase ではなく ATC）に最適化します

---

使用例

例 1：初回セットアップ

ユーザー：「ストアの Meta 広告を設定したいです」

スキルの応答：

1. Setup.md ワークフローに誘導します
2. .env が存在するか、Business Manager がセットアップ済みかを確認します
3. Developer App の作成手順を案内します
4. トークンの生成と交換をサポートします
5. .env を設定します
6. --check で検証します

例 2：キャンペーンを公開する

ユーザー：「新製品の発売キャンペーンを作成してください」

スキルの応答：

1. PublishCampaign.md ワークフローに誘導します
2. 認証情報を確認します（不足している場合は Setup に誘導します）
3. 画像、コピー、ターゲティング、予算について質問します
4. 設定 JSON を作成します
5. 公開します（すべて PAUSED）
6. キャンペーン ID とレビュー用チェックリストを報告します

例 3：パフォーマンスを確認する

ユーザー：「Meta 広告の成果はどうですか？」

スキルの応答：

1. AnalyzePerformance.md ワークフローに誘導します
2. --summary を実行してアカウントの概要を確認します
3. DTC のベンチマークと比較します
4. 成果の良いものと悪いものを特定します
5. 具体的な最適化の推奨事項を提示します

例 4：トークンの有効期限切れ

ユーザー：「Meta 広告のトークンが機能しません」／エージェントがエラーコード 190 を検出

スキルの応答：

1. Setup.md の Part 6（トークンの更新）に誘導します
2. .env に FACEBOOK_APP_ID と FACEBOOK_APP_SECRET があるか確認します
3. Graph API Explorer で新しい短期トークンを生成するようユーザーに伝えます
4. 交換用の curl コマンドを実行します
5. 新しい長期トークンで .env を更新します
6. --check で検証します

例 5：キャンペーンを管理する

ユーザー：「キャンペーン 12345678 を一時停止してください」

スキルの応答：

1. uv run ~/.claude/skills/MetaAds/tools/Publish.py --pause 12345678 を実行します
2. キャンペーンが一時停止されたことを確認します

---

最終更新日： 2026-02-07