social-fetch

/social-fetch — URL からあらゆるソーシャル投稿を取得

各プラットフォームのソーシャル投稿を正規化して取得します。URL からプラットフォームを判定し、順番に各種戦略を試して、取得元にかかわらず同じ JSON 形式で返します。

Step 1 — プラットフォームを判定する

URL パターン	プラットフォーム
x.com/<user>/status/<id> または twitter.com/<user>/status/<id>	x（Twitter）
linkedin.com/posts/<slug> または linkedin.com/feed/update/urn:li:activity:<id>	linkedin
linkedin.com/in/<handle>（プロフィール、最近のアクティビティ）	linkedin-profile
instagram.com/p/<id> または instagram.com/reel/<id>	instagram
tiktok.com/@<user>/video/<id>	tiktok
bsky.app/profile/<handle>/post/<rkey>	bluesky
reddit.com/r/<sub>/comments/<id>/...	reddit
<mastodon-instance>/@<user>/<id>（例：mastodon.social、hachyderm.io）	mastodon
threads.net/@<user>/post/<id>	threads
news.ycombinator.com/item?id=<id>	hn
youtube.com/watch?v=<id> または youtu.be/<id>	→ watch-video に引き継ぎます

URL がどのパターンにも一致しない場合は、ユーザーにプラットフォームを尋ねてください。

Step 2 — 戦略チェーンを選ぶ

プラットフォームごとの戦略チェーンは references/strategies.md を確認してください。各プラットフォームでは、2～5 個の戦略を順番に試します。

主な原則：

• 無料の戦略を先に試す（直接 API、agent-browser）
• 有料の戦略はフォールバックとしてのみ使用する（ScrapeCreators / Apify）。また、環境変数キーが設定されている場合に限ります
• Bluesky / Mastodon / HN / Reddit は無料で信頼性が高い（公開 API）
• X / LinkedIn / Instagram / TikTok / Threads では、すべてのデータを取得するために有料またはスクレイピングのフォールバックが必要です

Step 3 — 戦略を実行する

チェーン内の各戦略について：

1. 試します
2. 成功した場合：解析 → 正規化 → 返します
3. 失敗した場合（404、402、認証ウォール、空のレスポンス）：失敗を記録し、次の戦略を試します

チェーンをすべて試しても取得できない場合は、明確なエラーを返します。試した戦略、それぞれが失敗した理由、利用を可能にするために必要なもの（例：「X を利用するには $SCRAPECREATORS_API_KEY を追加してください。references/auth-keys.md を参照してください」）を記載します。

Step 4 — 出力を正規化する

プラットフォームにかかわらず、次の形式で返します（仕様全体とプラットフォーム別の例については references/output-schema.md を参照してください）。

{
  "platform": "x",
  "url": "https://x.com/example/status/1234567890",
  "fetched_at": "2026-06-17T14:35:00Z",
  "raw_source": "scrapecreators",
  "author": {
    "handle": "@example",
    "name": "the user Ganim",
    "verified": true
  },
  "posted_at": "2026-06-17T16:53:00Z",
  "text": "The 80/20 of a useful AI second brain: ...",
  "media": [],
  "engagement": {
    "likes": 51,
    "reposts": 13,
    "replies": 9,
    "bookmarks": 7,
    "views": 32700
  },
  "is_thread": true,
  "thread": [],
  "replies": []
}

プラットフォームに該当する項目がない場合（例：Mastodon の bookmarks）は、0 ではなく null にします。データがないことと、データがゼロであることは異なります。

Step 5 — オプションの追加取得

フラグや依頼に応じて実行します。

フラグ	動作
--with-replies	トップレベルの返信を取得します（1 階層）。API クォータを追加で消費します。
--thread	投稿が同じ著者によるスレッドの一部である場合、スレッド全体を取得します。
--raw	デバッグ用に、生の API／スクレイピングレスポンスを出力に含めます
--media	メディアファイル（画像／動画）を ~/Documents/social-fetches/<platform>-<id>/ にダウンロードします

デフォルトでは投稿自体のみを対象とし、返信は取得せず、メディアもダウンロードしません（URL のみ）。

Step 6 — キャッシュ（任意）

~/Documents/social-fetches/_cache/ が存在する場合、取得に成功したデータを {platform}-{id}.json として 24 時間キャッシュします。同じ投稿が複数のスキルで繰り返し参照される場合に、API クォータを節約できます。

--no-cache フラグが設定されている場合、または --with-replies／--thread が指定されている場合（古くなっている可能性が高いため）は、キャッシュをスキップします。

連携先

• deep-research — リサーチ概要で特定の投稿を引用します。リサーチで関連するツイート／投稿の URL が見つかった場合、取得して概要に含めます。
• jab-hook — インスピレーション元のアカウントから最近の投稿を取得し、形式を詳しく分析します（現在は agent-browser をインラインで使用していますが、代わりにこのスキルを呼び出すべきです）。
• business-brainstorm — スコアリング中の根拠として、競合他社や事業者のコメントを取得します。
• second-brain — tweet-／bookmark- のプレフィックスを付けて、投稿を raw/ に保存します。構造化された出力により、スクリーンショットやコピー＆ペーストよりも整理された raw ファイルを作成できます。
• watch-video — YouTube の URL（または Loom、Vimeo、Riverside、MP4 など、あらゆる動画）はこちらに引き継ぎます。

既知の制限

• X：無料の取得方法ではツイートのプレビューのみ（テキスト、投稿者、基本的なエンゲージメント）が返されます。スレッド全体と返信を取得するには、$SCRAPECREATORS_API_KEY または $APIFY_API_TOKEN が必要です。
• LinkedIn：モーダルを閉じた後は、agent-browser でプロフィールの最近のアクティビティを取得できます。特定の投稿 URL（linkedin.com/posts/...）では、有料の代替手段が必要になることがよくあります。
• Instagram / TikTok / Threads：ボット対策が非常に強力です。有料の代替手段を強くおすすめします。
• Bluesky / Mastodon / HN / Reddit：無料で信頼性があります。
• 非公開または削除済みの投稿：有効な手段はありません。削除済みのコンテンツには Wayback Machine をお試しください。

あるプラットフォームで無料の取得方法が継続的に失敗し、ユーザーがそのプラットフォームをよく使う場合は、有料キーを設定するよう案内してください（references/auth-keys.md を参照）。

品質に関する注意事項

• 単一ソースではなく、取得方法を段階的に切り替えます。 各プラットフォームには代替手段の順序（ネイティブ oEmbed → agent-browser → SCS API → Apify）があります。ある手順が失敗したら、次の手順に適切に切り替えてください。最初の試行で処理を完全に失敗させないでください。
• スクリーンショットより構造化出力を優先します。 後続のスキル（jab-hook、deep-research、second-brain）では、画像ではなく、投稿者、テキスト、エンゲージメントの各フィールドを含む JSON が必要です。元の取得方法がスクリーンショットであっても、返す前にテキストを抽出してください。
• キャッシュは積極的に使い、無効化は適切に行います。 ~/Documents/social-fetches/_cache/ の 24 時間 TTL により、セッション中に同じ投稿が複数のスキルで参照されても、API の使用量を抑えられます。返信はすぐに古くなるため、--with-replies / --thread ではキャッシュをスキップします。
• 有料キーのコストに配慮します。 ScrapeCreators / Apify の呼び出しには実費がかかります。ユーザーが詳細な取得を希望すると確認できていない場合は、有料の取得方法を使う前に確認してください。常に無料の取得方法を先に試してください。
• メディアのダウンロードはオプトインです。 デフォルトでは投稿テキストのみを取得し、画像や動画をダウンロードするのは --media を指定した場合です。メディアを無断でダウンロードすると、ディスク容量をすぐに消費します。
• 非公開または削除済みのコンテンツは取得できません。 どの取得方法を段階的に試しても、非公開アカウントや削除済みの投稿は取得できません。削除済みのコンテンツには Wayback Machine を提案し、それ以上の取得は中止してください。
• レート制限はプラットフォームごとに異なります。 X の無料の取得方法では、レート制限にすぐ達します。LinkedIn では agent-browser の使用によりセッションフィンガープリントを消費します。ループ内で呼び出しの間隔を空けてください。そうしないと、ワークフローの品質が手作業を下回ります。