Claude Media
CLAUDE_CODE_SYNC_SKILLSの2つのタイムアウト変数を使い分ける
Claude CodeAgent SDKTips

CLAUDE_CODE_SYNC_SKILLSの2つのタイムアウト変数を使い分ける

CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MSとCLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MSは効く局面が違います。既定値と超過時の挙動を分けて見ます。

読了目安 約10分

CLAUDE_CODE_SYNC_SKILLSの2つの子変数

CLAUDE_CODE_SYNC_SKILLSは、非対話モード(-pフラグ)でclaude.aiアカウントに有効化されているSkillsをダウンロードし、最初のクエリを実行する前にその一覧を待つ設定です。claude.ai認証が前提になります。

この待機には、性質の異なる2つのタイムアウトが関わります。

  • CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS — セッション開始時、最初のクエリがSkills一覧を待つ上限(既定値5000ミリ秒)
  • CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS — Agent SDK上に構築されたアプリがセッション途中でSkillsを再読み込みするとき、その再同期処理を待つ上限(既定値30000ミリ秒)

同じ「Skillsのダウンロード待ち」でも、片方はセッション開始時、もう片方はセッション途中のAgent SDK再読み込み時という別の局面を指します。名前が似ているため、片方だけを設定して意図した動作にならないケースが起きやすいポイントです。

それぞれのタイムアウトが効く場面

変数既定値効く局面超過時の挙動
CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS既定値5000ms効く局面CLAUDE_CODE_SYNC_SKILLS設定時、セッション開始の最初のクエリ超過時の挙動到着済みのSkillsだけで最初のクエリを実行する
CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS既定値30000ms効く局面Agent SDKを使うアプリがミッドセッションでSkillsを再読み込みするとき超過時の挙動到着済みのSkillsだけで再読み込みを続行する

どちらも、タイムアウトを過ぎてもダウンロード自体はバックグラウンドで継続します。そのSkillを実際に呼び出す時点でダウンロードが終わっていなければ、Claude Codeはそこで完了を待ちます。タイムアウトは「一覧が揃うまで待つ上限」であって、ダウンロードそのものの制限時間ではありません。

設定のやり方

シェルで直接設定する場合です。

export CLAUDE_CODE_SYNC_SKILLS=1
export CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS=8000
export CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS=45000
claude -p "レビューを実行して"

.claude/settings.jsonのenvブロックに書く場合も同じキー名を使います。

{
  "env": {
    "CLAUDE_CODE_SYNC_SKILLS": "1",
    "CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS": "8000",
    "CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS": "45000"
  }
}

シェルと設定ファイルの両方で同じ変数を設定した場合は、設定ファイル側の値が優先されます。Claude Codeはenvエントリをプロセス環境へ書き込み、シェルから継承した値を上書きします。数値はプレーンな桁数だけでなく、8e3のような指数表記や45_000のようなアンダースコア区切りでも読み取れます。プロジェクト設定・ローカル設定・管理設定で同じ変数が重複した場合は、管理設定が優先される設定ファイル間の優先順位に従います。

Pluginsの同期待ちには既定のタイムアウトが無い

同じenv-varsのリファレンスには、Pluginsのインストールを待つためのCLAUDE_CODE_SYNC_PLUGIN_INSTALLとCLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MSという一対の変数も載っています。CLAUDE_CODE_SYNC_PLUGIN_INSTALLを非対話モードで1に設定すると、最初のクエリの前にPluginsのインストール完了を待ちます。設定しなければPluginsはバックグラウンドでインストールされ、最初のターンでは使えないことがあります。対応するタイムアウト変数を超過すると、Claude CodeはPluginsなしで処理を進めてエラーを記録します。この変数には既定値がなく、設定しない限り同期インストールは完了まで待ち続けます。

Skills側のCLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS(既定5秒)・CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS(既定30秒)には既定値が用意されている一方、Pluginsのタイムアウトには既定値がありません。設計上、Skillsは「時間内に揃わなければ後から追いつけばよい」という前提で既定値が振られ、Pluginsは「揃わないまま進めるとエラーになるおそれがある」ため無期限待機がデフォルトになっている、と読み取れます。同じ「同期を待つ」仕組みでも、対象がSkillsかPluginsかで既定の振る舞いが違う点は、設定を移植するときに見落としやすいところです。

Agent SDKのミッドセッション再読み込みで待つ理由

CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MSが対象にするのは、env-varsのリファレンスが「Agent SDK上に構築したアプリがセッションの途中でSkillsを再読み込みする」と説明する処理です。ターミナルでclaude.aiアカウントにログインしたセッションは、この変数を設定していなくても~/.claude/skills/synced/へSkillsをダウンロードし、約10分ごとに再同期します。ただしAgent SDKのドキュメント側には、この再読み込みに対応する呼び出しが見当たりません。どの呼び出しでこのタイムアウトが発火するかは、env-varsの説明以上には確認できませんでした。SDK経由でSkillsを使っていて、この再同期に時間がかかっている場合の調整値、という範囲で理解しておくのが安全です。

syncedというフォルダ名は、この同期の仕組みのために予約されています。v2.1.227より前はSkillsが~/.claude/skills/へ直接ダウンロードされていましたが、それ以降は~/.claude/skills/synced/が専用の置き場所になりました。同期されたSkillsには、通常のターミナルセッションで本文中の!コマンドを実行しない、@参照によるファイル添付をしない、${CLAUDE_PROJECT_DIR}と${CLAUDE_SESSION_ID}のプレースホルダーを置換しない、という3つの追加制限がかかり、いずれもClaudeにはそのまま文字列として渡ります。frontmatterのallowed-toolsは通常どおり有効になりますが、descriptionなど表示用のテキストは制御文字が除去され、山括弧がエスケープされます。

v2.1.273より前は、ターミナルセッションでのSkillsダウンロードはCLAUDE_CODE_SYNC_SKILLSを設定した-p実行時に限られていました。現在は、claude.aiアカウントでログインしたセッションであれば、この変数の有無にかかわらずバックグラウンドでの自動ダウンロードと定期的な再同期が動きます。CLAUDE_CODE_SYNC_SKILLSを設定する意味は、「最初のクエリの前に一覧が揃っているかどうか」を保証したい場面に絞られます。

落とし穴

フィーチャーフラグの取得が止まっていると、タイムアウトを調整しても効果がありません。DISABLE_GROWTHBOOK / DISABLE_TELEMETRY / DO_NOT_TRACK / CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICのいずれかを設定しているセッション、Amazon BedrockやGoogle CloudのAgent Platformなどサードパーティ経由のセッション(ホスト側がCLAUDE_CODE_PROVIDER_MANAGED_BY_HOSTを設定していない場合)、Claude apps gatewayのセッションでは、Anthropicからのフィーチャーフラグ取得自体が省略されます。この取得が止まっていると、claude.aiアカウントに有効化されたSkillsとPluginsをターミナルセッションへ同期する機能そのものが動きません。タイムアウトの値を伸ばす前に、まずフラグ取得が有効なセッションかどうかを確認する必要があります。

もう1点、CLAUDE_CODE_SYNC_SKILLS自体がclaude.ai認証を前提にしている点も見落としやすいところです。Console(APIキー)アカウントや、認証していないセッションでは、そもそも同期対象のSkills一覧が存在しないため、2つのタイムアウト変数を設定しても待つ対象がありません。

タイムアウトを伸ばしても症状が変わらないときは、次の順で切り分けると原因を絞りやすくなります。

  1. claude.aiアカウントで認証しているか — Consoleアカウントでは同期対象自体が存在しない
  2. フィーチャーフラグ取得がオフになる条件に該当していないか — DISABLE_GROWTHBOOK / DISABLE_TELEMETRY / DO_NOT_TRACK / CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、サードパーティプロバイダー経由、Claude apps gatewayのいずれか
  3. 狙った局面と変数が合っているか — セッション開始時の遅延ならWAIT_TIMEOUT_MS、Agent SDKのミッドセッション再読み込みならINSTALL_TIMEOUT_MS

この3つを確認してから値を調整すると、「タイムアウトを伸ばしたのに何も変わらない」という手戻りを避けられます。

インストール後の初回セッションや、新機能を追加したバージョンへのアップグレード直後のセッションでは、フラグゲートされた機能が一時的に欠けることがあります。Skillsの同期もフラグゲートされた機能の一つなので、この状態ではCLAUDE_CODE_SYNC_SKILLSを設定していても一覧が空のまま返ることがあります。非対話セッション(claude -p・Agent SDK・VS Code拡張)では、権限モードを選ぶより前にフラグを取得できる場合がありますが、この挙動は保証された仕様というより実装上の余地として書かれています。

既定5秒と30秒の差は-p実行の体感速度を優先した結果

CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MSの既定5秒に対し、CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MSの既定は30秒です。6倍の開きがある理由は、どちらの待機がユーザーの体感速度を直接左右するかで説明できます。

セッション開始時の待機は、-p実行の最初のクエリそのものをブロックします。バッチ処理やCIパイプラインでは、この待ち時間がそのまま処理全体の所要時間に上乗せされるため、5秒という短い既定値は「多少Skillsが揃っていなくても早く動き出す」方を優先した設定です。

一方、セッション途中の再読み込みは最初のクエリほど直接には待ち時間として表に出にくい局面です。30秒という長めの既定値は、一覧が揃わないまま先へ進むのを避ける側に寄せた設定です。

この非対称性を踏まえると、-p実行を高速化したい場合はCLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MSをさらに短く、逆にAgent SDKアプリでSkillsの取りこぼしを避けたい場合はCLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MSを長めに、という調整の方向性が見えてきます。両方を同じ値に揃える設定は、片方の局面では過剰に待ち、もう片方では足りない、という結果になりやすい組み合わせです。

対話セッションでは2つの変数を設定しても挙動が変わらない

ここまでの2つの変数は、いずれも非対話的な実行と結びついています。CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MSはCLAUDE_CODE_SYNC_SKILLSと組み合わせて-p実行の最初のクエリに効き、CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MSはAgent SDKアプリがセッション途中でSkillsを再読み込みするときに効きます。

通常のターミナルで対話的にclaudeを起動し、claude.aiアカウントでログインしている場合は、これらの変数を設定しなくても~/.claude/skills/synced/へのダウンロードと約10分ごとの再同期がバックグラウンドで動きます。対話セッションの最初のクエリは、この自動ダウンロードの完了を明示的に待つ仕組みを持ちません。つまり、対話的な利用だけをしていて-p実行もAgent SDKアプリの組み込みもしていない場合、この2つのタイムアウト変数を設定しても挙動は変わりません。設定する価値があるのは、CI・バッチ処理での-p実行と、Agent SDK上に構築したアプリの2つの局面に限られます。

まとめ

CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MSはセッション開始時の初回クエリが待つ時間(既定5秒)、CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MSはAgent SDKアプリのミッドセッション再読み込みが待つ時間(既定30秒)です。CIやバッチ処理でAgent SDK経由のSkillsを使い、セッション途中の再読み込みに時間がかかる場合は後者を、-p実行の最初のクエリで最新のSkills一覧を確実に使いたい場合は前者を調整します。Skillsが検出されないときの切り分けを先に済ませてから、タイムアウト値の調整に進むのが手戻りの少ない順序です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →