スタディスト Tech Blog
🔍

Claude Code Skillは本当に効率的？ —— 鍵を握るPrompt Caching

yossuli
に公開
2026/02/02
prompt
Claude
AIエージェント
Claude Code
Agent Skills
tech

はじめに

こんにちは。最近はすっかりAI駆動開発にどっぷり浸かっているyossuliです。

最近は業務ではClaude Codeを、趣味ではAntigravityを使っています。

つい最近までClaude Codeは特にカスタマイズせず使っていました。しかしAntigravityがなかなか言うことを聞いてくれず(Student Proの無課金なので、できるだけ軽いことはGemini 3 Flashでやりたい)、どうにかするためにSkillを使い始めたところ感触が良く、Claude CodeでもSkillを使うようになりました。

そこでSkillを使っていると漠然と、作業の再現性が高かったり、応答が早いなどの漠然とした体感がありました。

本当にSkillを使うと効率的なのか？ それを確かめた結果をまとめたのが本記事になります。

検証環境と方法

環境

  • Claude Code: 2.1.12
  • モデル: claude-sonnet-4-5-20250929
  • 実行方法: ヘッドレスモード（claude -p "prompt"）
  • キャッシュの制御: DISABLE_PROMPT_CACHING=1環境変数で、Claude CodeのPrompt Caching挙動を抑制して計測（※ログ上のCACHEが必ず0になる、という意味ではありません。後述）

計測方法

Claude Codeが出力するログファイル（~/.claude/projects/*/**.jsonl）を自作スクリプトで解析しました。
与えたSkillなどは以下のリポジトリで公開しています。

https://github.com/yossuli/claude_test_pub

本記事で使うトークン指標は、ログのusageから以下のように集計しています：

  • IN(New): input_tokens + cache_creation_input_tokens（新規に投入された入力トークン）
  • CACHE: cache_read_input_tokens（キャッシュから読み出された入力トークン）
  • OUT: output_tokens

この関数を用いて各条件で複数回実行し、トークン消費量を集計しています：

  • 基礎検証：各条件 n=20回
  • 実用的検証：各条件 n=5回
python3 count_tokens.py ~/.claude/projects/<ProjectName> -c ./sessions_config.json -A <グループ名>

なお、検証の際は各グループを交互に呼び出すことで、時間帯やキャッシュ状態などの外部要因による偏りを最小限にしています。

検証結果のサマリー

まず結論から言うと、Skillを使うと確かに効率的だったのですが、その理由が意外でした。

基礎検証の結果

Skillを使った場合と直接プロンプトで指示した場合を20回ずつ実行して比較したところ：

グループ IN(New) 差分（IN(New)）
Skill使用 3,444 -
直接入力 4,208 +764

詳細なデータ

詳細なセッションデータはreports/01_skill_division_efficiency.mdで公開しています。

今回の検証では、Skill使用の方に IN(New)が少ない（=新規入力トークンを抑えられる）傾向が見られました。

当初、効率的である理由はSkillで明示的に呼ぶことによるClaude APIの内部的な思考の発散を防止するなど、特殊な挙動の行われているものと考えていました。

しかし、そうではなかった

「Skillが効率的なのは、Skillが賢く最適化されているからだろう」と思っていたのですが、実行結果を時系列ごとに並べたところ、初回のみInputが膨大になっていました。

そこでキャッシュを無効化（DISABLE_PROMPT_CACHING=1）して同じ検証をしてみたところ：

グループ IN(New) 差分（IN(New)）
Skill使用（キャッシュOFF） 55,795 -
直接入力（キャッシュOFF） 51,597 -4,198

詳細なデータ

詳細なセッションデータはreports/01_skill_division_efficiency.mdで公開しています。

効率差が消失どころか逆転してしまいました。

つまり、おそらくですがSkillはPrompt Cachingと組み合わさることで、（直接プロンプトで実行することと比べて）効率性が安定しやすいと言えるのではないかと思います。(これはProgressive Disclosure等を発動させることによる作業の効率性向上とは別です)

以下、詳しい検証結果を見ていきます。

Anthropic Prompt Cachingについて

「Prompt Cachingって何？」を、あらためて説明します。

Anthropic APIが提供する機能で、繰り返し使われるプロンプトをキャッシュし、トークンコストを削減する仕組みです。

キャッシュヒット時はcache_read_input_tokensとして計上され（本記事の表ではCACHE列）、通常の入力トークンと比べて大幅なコスト削減となります。

Claude Codeではプロンプトキャッシングが自動的に使用され、パフォーマンスの最適化とコスト削減が行われています。今回の検証ではDISABLE_PROMPT_CACHING=1環境変数を使用してPrompt Caching挙動を抑制しました。

補足：DISABLE_PROMPT_CACHING=1を付けても、ログ上のCACHE（= cache_read_input_tokens）が常に0になるとは限りません。本稿では主にIN(New)の増減に注目し、キャッシュOFF条件でIN(New)が大きく増えていることから、意図した比較としては概ね成立していると判断しています。

詳細な検証結果

検証1: Skill使用 vs 直接入力（キャッシュあり）

まず、キャッシュが有効な状態で比較してみました。

比較したのは以下の2パターンです：

  • Skillを使用: 最初から最後まで細かく指示したプロンプトをSkillファイルに記述
  • 直接入力: プロンプトで同じ内容を直接指示

それぞれ20回ずつ実行した結果がこちら：

グループ 処理時間 IN(New) CACHE OUT
expanded_in_skill 18.1s 3,444 147,119 21
inline_skill 18.1s 4,208 158,370 24

使用したスキル定義と詳細データ

使用したスキル定義や詳細なセッションデータはGitHubリポジトリで公開しています。

20回の実験をした結果、今回の検証ではSkillを使った方が IN(New)を764トークン少なく抑えられた（=新規入力トークンが抑えられる）という差が出ました。

セッション単位で見ると面白いことがわかる

全20回のセッション単位で見てみると、興味深いパターンが見えてきます。

初回（#1）は両者ほぼ同等（約5,200トークン）なのですが、#2以降、Skill使用はキャッシュ効果で安定して低い値（平均3,444トークン）を維持しています。

一方、直接入力は#12, #15, #16でかなり大きな外れ値が発生していて、全体としてばらつきが大きいです（平均4,208トークン）。

セッション単位の詳細データ
# Skill使用 IN(New) 直接入力 IN(New) 差
1 5,232 5,158 +74
2 1,571 1,708 -137
3 2,314 1,851 +463
4 1,957 1,983 -26
5 2,531 2,607 -76
6 2,362 2,549 -187
7 2,520 2,945 -425
8 2,864 3,256 -392
9 2,772 3,240 -468
10 2,958 3,122 -164
11 3,457 3,256 +201
12 2,137 6,202 -4,065
13 2,279 3,714 -1,435
14 3,881 3,741 +140
15 4,452 5,915 -1,463
16 3,825 16,734 -12,909
17 4,539 4,898 -359
18 8,440 4,308 +4,132
19 4,299 2,760 +1,539
20 4,488 - -
平均 3,444 4,208 -764

太字は外れ値を示しています。

外れ値の原因を調べてみた

外れ値が発生したセッションをツール呼び出しパターンで確認してみると：

  • #12 (6,202トークン): Edit失敗 → リトライ → Read再読み込み → Edit
  • #15 (5,915トークン): Edit後にBash(tail)で確認 → 追加Edit
  • #16 (16,734トークン): Read(offset:80)で再読み込み → トークン急増

# 15,16で以前と違う動きをしているのは、キャッシュの期限切れなどの理由で行動にブレが生じたためと考えられます。
つまりSkillを使った方が再現性があるのではないかと推測します。

検証2: キャッシュOFFでの比較

DISABLE_PROMPT_CACHING=1

グループ 処理時間 IN(New) CACHE OUT
expanded_in_skill_no_cache 24.0s 55,795 94,158 121
inline_skill_no_cache 21.3s 51,597 88,553 132

詳細なデータ

詳細なセッションデータはreports/01_skill_division_efficiency.mdで公開しています。

むしろ直接入力の方がわずかに有利という結果になりました。

なぜこうなるのか

この結果から、以下のような考察が成り立ちます。

  • Skillを使うと、スキルファイルのメタデータがオーバーヘッドになる
  • キャッシュがないと、そのコストがそのまま効いてくる
  • Skillが効率的なのは、キャッシュヒット率が高いから

つまり、「Skillが賢く最適化されている」わけではなく、短い命令で行動を起こさせられるのでキャッシュのヒット率が高いということでしょう。

検証3: より実用的なタスクでも確認してみる

以下の2つのタスクでも検証してみました：

  1. JSDocコメント追加: 関数にドキュメントコメントを追加
  2. Gitコミットフロー: リポジトリの状態を確認してコミットを作成

JSDoc検証（キャッシュあり）

グループ IN(New) CACHE OUT
jsdoc_detailed 4,652 160,990 11
jsdoc_simple 5,640 231,785 20
jsdoc_inline 5,667 187,314 26

使用したスキル定義と詳細データ

今回の検証では、詳細Skill（jsdoc_detailed）の方が IN(New)を少なく抑えられるという傾向が見られ、基礎検証とほぼ同等の結果でした。

Git検証（キャッシュあり）

より複雑なタスクとして、Gitコミットフロー（git diff→git status→git add→git commit→git logという一連の流れ）でも検証しました。

グループ 処理時間 IN(New) CACHE OUT
git_commit_flow 37.8s 7,411 306,332 56
manual_short 32.4s 7,125 295,604 41
manual_detailed 36.8s 7,706 327,018 75

使用したスキル定義と詳細データ

こちらはほぼ同等ですが、より複雑なタスクでもSkillが不利にならないことが確認できました。

キャッシュなしの結果

JSDoc検証・Git検証ともに、外れ値を除くといずれのグループも基礎検証とほぼ同等でした。

やはり、キャッシュなしでは効率差がほぼ消失します。タスクの複雑さに関わらず、同じ傾向が確認できました。

おわりに

いかがでしたでしょうか。

今回は「Skillって効率的だよね」という漠然とした体感を、ログ解析で定量的に検証してみました。

今回の発見のまとめ

  • Skillが効率的なのは、Prompt Cachingのおかげ
  • キャッシュヒット率を高める単純化されたユーザーからの入力もSkillの価値の1つ
  • 繰り返すタスクはSkill化すると、トークン効率が大幅UP
  • ログ解析で定量的に検証できる

関連記事

今回の検証で気になったことがいくつかあったので、続編として以下のテーマでも記事を書いています：

もしこの記事が役に立ったと思ったら、いいねやコメントをいただけると嬉しいです！

改めて、検証に使ったリポジトリはこちらになります。
正直なところ計測スクリプトには自信がないので、(感覚的には合っている気はしますが)もし間違っている部分があったら教えていただけると幸いです！

最近話題のClaude Codeの公式ベストプラクティスにも積み重ねて直感を磨きましょうとあります。
内部構造を深く知ることでClaude Codeをより活用する手助けになればと思っております。

ここまで読んでいただきありがとうございました！

共同執筆

  • cursor:
    • 執筆: sonnet 4.5, GPT-5.2
    • データ分析・精査: GPT-5.2 codex
  • ChatGPT:
    • 草案作成
    • DeepResearch
スタディスト Tech Blog
スタディスト Tech Blog

Discussion