x-research

X Research（xAI/Grok）

xAI の Grok API を使用した AI によるリサーチです。生のツイートデータではなく、引用付きの AI 要約を返します。

生のツイートを取得したい場合はこちらのスキルを使用してください。

• x-user-timeline - ユーザーの生のツイート
• x-tweet-search - 生の検索結果
• x-tweet-fetch - 個別の生のツイート
• x-user-lookup - ユーザープロフィールデータ

X の公式 XMCP server のツールが利用できる場合は、 生の X データの取得にはそちらを優先してください。XMCP は通常、ローカルで http://127.0.0.1:8000/mcp にて実行されます。https://docs.x.com/mcp は別のホスト型 ドキュメントサーバーです。それ以外の場合は、上記のスキルを使用してください。 どちらの生データ取得方法にも X の認証情報が必要ですが、この統合スキルでは XAI_API_KEY を使用します。

使用する場面

このスキルを使用する場面：

• AI 分析を含む要約済みのリサーチ
• 時事問題や速報
• ソーシャル上の評判（「Y について開発者は何と言っていますか？」）
• X/Twitter のトレンドトピックやバズっている投稿
• まだドキュメントに記載されていない新しいツールやフレームワーク
• ベストプラクティスに関するコミュニティの意見

使用しない場面：

• 生のツイートデータ（x-user-timeline、x-tweet-search を使用）
• 特定のユーザーの投稿をそのまま取得する場合（x-user-timeline を使用）
• 十分にドキュメント化された API（代わりに WebFetch を使用）

セットアップ要件

API キーが設定されているか確認します。

if [ -z "$XAI_API_KEY" ]; then
  echo "ERROR: XAI_API_KEY is not set"
  echo "1. Get API key from https://x.ai/api"
  echo "2. Add to profile: export XAI_API_KEY=\"your-key\""
  echo "3. Restart terminal and Claude Code"
  exit 1
else
  echo "XAI_API_KEY is configured"
fi

利用できない場合は、このスキルを使用する前に XAI_API_KEY を設定する必要があることをユーザーに伝えてください。

API の概要

エンドポイント：https://api.x.ai/v1/responses

シェル呼び出しごとに、読み込まれたスキルのディレクトリを一度だけ解決し、そのリクエスト ラッパーを使用します。Claude Code プラグインでは、CLAUDE_PLUGIN_ROOT から導出します。 Codex では、読み込まれた SKILL.md の絶対ディレクトリを使用します。

X_RESEARCH_SKILL_DIR="${CLAUDE_PLUGIN_ROOT}/skills/x-research"
"$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON'
{"input":"[YOUR QUERY]","tools":[{"type":"web_search"},{"type":"x_search"}]}
JSON

XAI_RESEARCH_MODEL は未設定のままにするか、auto、latest、または grok-latest/grok-4-latest に設定すると、現在の API キーで利用できる最新の標準汎用 Grok モデルが選択されます。現在、このセレクターはそのポリシーを grok-4.5 に解決します。 xAI が新しい標準モデルを公開すると、自動的に更新されます。名前に latest が含まれている というだけでエイリアスを信用しないでください。最新のカタログでも、古いエイリアスが 残っている場合があります。意図的に固定する場合に限り、grok-4.5 のようなバージョン付き ID、 または grok-4.5-latest のようなバージョン付きエイリアスを設定します。セレクターは明示的な 固定指定を検証し、常に標準モデル ID を出力します。ラッパーはモデルの選択と呼び出しを 1 つのプロセスで行うため、別々のシェルツール呼び出しの間にモデルの選択が失われることは ありません。標準入力でリクエスト JSON オブジェクトを受け取り、埋め込まれた model を 上書きして、Responses API の生の JSON を返します。

利用可能な検索ツール：

• web_search - インターネットを検索し、ウェブページを閲覧します
• x_search - X の投稿を意味検索およびキーワード検索します

基本的な使い方

検索ツールを使ったシンプルなクエリ

"$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON' \
  | tr -d '\000-\010\013\014\016-\037' \
  | jq -r '[.output[] | select(.type=="message")][-1].content[0].text'
{
    "input": [{"role": "user", "content": "[YOUR QUERY]"}],
    "tools": [{"type": "web_search"}, {"type": "x_search"}]
}
JSON

使用量を追跡するクエリ（推奨）

RESPONSE=$("$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON'
{
    "input": [{"role": "user", "content": "[YOUR QUERY]"}],
    "tools": [{"type": "web_search"}, {"type": "x_search"}]
}
JSON
)

# Extract usage stats
TOOL_CALLS=$(echo "$RESPONSE" | jq -r '.usage.num_server_side_tools_used // 0')
COST_TICKS=$(echo "$RESPONSE" | jq -r '.usage.cost_in_usd_ticks // 0')
COST_USD=$(jq -n --argjson ticks "$COST_TICKS" '$ticks / 10000000000')
echo "Tool calls: $TOOL_CALLS | Estimated cost: \$$COST_USD"
echo ""
echo "$RESPONSE" | tr -d '\000-\010\013\014\016-\037' | jq -r '[.output[] | select(.type=="message")][-1].content[0].text'

検索ツールのパラメーター

ウェブ検索のオプション

"tools": [{
  "type": "web_search",
  "allowed_domains": ["github.com", "stackoverflow.com"],
  "excluded_domains": ["pinterest.com"],
  "enable_image_understanding": true
}]

• allowed_domains - 指定したドメインのみに制限します（最大 5 件）
• excluded_domains - 指定したドメインを除外します（最大 5 件）
• enable_image_understanding - 検索中に見つかった画像を分析します

X 検索のオプション

"tools": [{
  "type": "x_search",
  "allowed_x_handles": ["elikimonimus", "anthropaboris"],
  "excluded_x_handles": ["spambot"],
  "from_date": "2025-01-01",
  "to_date": "2025-01-16",
  "enable_image_understanding": true,
  "enable_video_understanding": true
}]

• allowed_x_handles - 指定したアカウントの投稿のみを含めます（最大 20 件）
• excluded_x_handles - 指定したアカウントの投稿を除外します（最大 20 件）
• from_date / to_date - ISO8601 の日付範囲（YYYY-MM-DD）
• enable_image_understanding - 投稿内の画像を分析します
• enable_video_understanding - 投稿内の動画を分析します

例

X/Twitter のトレンドトピック

"$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON' \
  | tr -d '\000-\010\013\014\016-\037' \
  | jq -r '[.output[] | select(.type=="message")][-1].content[0].text'
{
    "input": [{"role": "user", "content": "What is currently trending on X? Include viral posts and major discussions."}],
    "tools": [{"type": "x_search"}]
}
JSON

トピックに関する開発者の評判

"$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON' \
  | tr -d '\000-\010\013\014\016-\037' \
  | jq -r '[.output[] | select(.type=="message")][-1].content[0].text'
{
    "input": [{"role": "user", "content": "What are developers saying about [TOPIC] on X? Include recent discussions and opinions."}],
    "tools": [{"type": "x_search"}, {"type": "web_search"}]
}
JSON

ニュースとウェブのリサーチ

"$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON' \
  | tr -d '\000-\010\013\014\016-\037' \
  | jq -r '[.output[] | select(.type=="message")][-1].content[0].text'
{
    "input": [{"role": "user", "content": "Latest news and developments about [TOPIC]"}],
    "tools": [{"type": "web_search"}]
}
JSON

日付範囲を指定した過去のリサーチ

"$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON' \
  | tr -d '\000-\010\013\014\016-\037' \
  | jq -r '[.output[] | select(.type=="message")][-1].content[0].text'
{
    "input": [{"role": "user", "content": "What happened with [TOPIC] from January 9 through January 16, 2025?"}],
    "tools": [{
      "type": "x_search",
      "from_date": "2025-01-09",
      "to_date": "2025-01-16"
    }, {
      "type": "web_search"
    }]
}
JSON

応答構造

応答には次の内容が含まれます。

{
  "output": [
    {"type": "web_search_call", "status": "completed", ...},
    {"type": "custom_tool_call", "name": "x_semantic_search", ...},
    {
      "type": "message",
      "content": [{
        "type": "output_text",
        "text": "The actual response with [[1]](url) inline citations",
        "annotations": [{"type": "url_citation", "url": "...", ...}]
      }]
    }
  ],
  "citations": ["url1", "url2", ...],
  "usage": {
    "input_tokens": 11408,
    "output_tokens": 2846,
    "num_server_side_tools_used": 8,
    "cost_in_usd_ticks": 429052500
  }
}

コンテンツの抽出：jq -r '[.output[] | select(.type=="message")][-1].content[0].text' — 最後のMESSAGE要素を明示的に選択します。grok-4.5では、最後のoutput[]要素は推論ブロックであり、推論の要約に生の制御文字が含まれることがあります。これにより、ペイロード全体を厳密にJSON解析するとエラーが発生します。各例のtrによる除去処理は、grok-4.5の推論の要約に含まれることがある生の制御文字を取り除きます。これらの文字があると、jqが選択処理を行う前に、ペイロード全体の厳密なJSON解析が失敗します。

引用の抽出：jq -r '.citations[]'

料金

検索料金とトークン料金は、このスキルとは別に変更されます。正確な料金は response.usage.cost_in_usd_ticksから確認してください。xAIでは1 USDを 10,000,000,000 ticksと定義しています。今後のリクエストの見積もりを行う前に、 プロバイダーの料金ページを確認してください。

エラー処理

APIからエラーが返された場合：

1. XAI_API_KEYが設定され、有効であることを確認します
2. GET /v1/modelsで、現在のAPIキーでモデルを取得できることを確認します
3. レート制限を超えていないことを確認します
4. tools配列が適切な形式であることを確認します
5. APIの応答とともに、エラーをユーザーに報告します

一般的なエラー：

• "Internal error" - 通常、モデル名が誤っているか、リクエストの形式が不正です
• タイムアウト - リクエストに時間がかかりすぎています（エージェント型APIではまれです）

移行に関する注意事項

非推奨（2026年1月12日）：search_parametersを使用する従来のLive Search APIは非推奨になります。このスキルでは、より高速で高機能な新しいエージェント型ツール呼び出しAPIを使用します。

従来の形式（非推奨）：

{
  "model": "grok-4-latest",
  "messages": [...],
  "search_parameters": {"mode": "on"}
}

新しい形式（現在のモデルIDを確認してから使用してください）：

{
  "model": "<verified-current-model-id>",
  "input": [...],
  "tools": [{"type": "web_search"}, {"type": "x_search"}]
}

参考資料

• LLMs.txt（AI向けに最適化されたドキュメント）: https://docs.x.com/llms.txt
• xAI APIドキュメント
• 検索ツールガイド
• モデルリファレンス
• X.com API v2