小さいタスクもSkill化すべき? —— 手動定義、自動生成、直接入力の比較
はじめに
こんにちは。最近はAI駆動開発にどっぷり浸かっているyossuliです。
このシリーズでは、「Skillを使うとトークン効率がよい(ようにみえる)」ことと、その正体がPrompt Cachingと強く関係しているのではないか、という話をしています。
これまでの記事では、Skillのトークン効率とPrompt Cachingの関係について検証してきました。
この記事では、もっと素朴な疑問に答えます。
「JSDocを足す」みたいな小さいタスクまで、Skill化する意味ある?
結論は"Yes寄り"ですが、「Skill化」と言ってもやり方が複数あるので、そこを切り分けた上で判断基準を作ります。
ざっくりとした結論
- 1回限り〜数回なら、まずは 直接入力でOK(最小コスト)。
- 繰り返す前提なら、(手間をかけて)手動でSkillを定義することでIN(New)を抑えられる傾向がある。
- 一方で 自動Skill化(本稿では
/create-skillという自作Skillで検証)は「手間をトークンで買う」機能であって、短期のトークン効率目的だと不利になり得る(今回の検証範囲ではそうだった)。
検証環境と指標(最短)
- Claude Code: 2.1.12
-
実行方法: ヘッドレスモード(
claude -p "prompt") -
計測方法: ログ(
~/.claude/projects/*/**.jsonl)を自作スクリプトで集計 -
対象指標:
-
IN(New): 新規に投入された入力トークン(ここを主に見る) -
CACHE: ログ上のキャッシュ由来トークン(0にならないこともある)
-
検証1:小タスク(JSDoc追加)で「手動Skill vs 直接入力」
JSDoc追加という小タスクで、次の3パターンを比較しました。
-
jsdoc_detailed: 詳細な手順を手動Skillに書く -
jsdoc_simple: 簡潔なSkill -
jsdoc_inline: 直接入力(Skillの中身と完全に同じ内容をチャットに送信)
キャッシュあり(外れ値込みの平均)
| グループ | 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)が最も少ないという結果でした。
外れ値の根拠(結果から引用)
reports/raw_data/benchmark_data/jsdoc_cached.md
jsdoc_inline セッション ed19cce2-2272-4827-88f2-8368ed0fbf9e は備考が **外れ値**: Edit複数リトライ となっており、CALLS=19・IN(New)=10,537 まで跳ねています。
キャッシュなし(外れ値込みの平均)
| グループ | IN(New) | CACHE | OUT |
|---|---|---|---|
| jsdoc_inline_no_cache | 64,488 | 78,683 | 9 |
| jsdoc_simple_no_cache | 50,115 | 72,855 | 6 |
| jsdoc_detailed_no_cache | 124,151 | 154,453 | 18 |
キャッシュなしでは、外れ値の影響で平均値に乱れの生じる(=「常にSkill使用が得」とは言い切れない)結果になりました。
外れ値の根拠(結果から引用)
reports/raw_data/benchmark_data/jsdoc_no_cache.md
jsdoc_detailed_no_cache セッション ea56f2ac-e10b-43b2-bb1d-38e290b16d82 は備考が **外れ値**: Edit複数リトライ+Write となっており、IN(New)=211,806。
また jsdoc_inline_no_cache 外れ値 #1 には明示的に **原因**: インライン指示にも関わらずスキルを呼び出してしまった とあります。
ここまでで言えるのは、だいたいこの2つです。
- キャッシュが効く状況では、(手動で丁寧に書いた)詳細Skillが有利になり得る
- ただし現実にはリトライ等のブレが混ざるので、"平均で常勝"というより、判断基準を持つのが大事
検証2:自動Skill化は「トークン効率の近道」なのか?
ここが今回の追加で一番重要なポイントです。
「小さいタスクをSkill化する」ならSkill作成Skillで自動生成して使うのがラクそうですが、これは "トークン効率"ではなく"手間削減"のための仕組み になりやすいです。
reports/05_direct_vs_skill_comparison.md
なぜ自動Skill化は「効きにくい」ように見えたのか
本稿では完全に指示した内容をそのままSKILL化した単純な場合で比較したかったので/create-skillというSkillを自作しました。
また、ワンショットの入力でSkill作成→実行まで行って欲しかったというところもあります。
自作の /create-skill では最終的に new_simple_skill.sh を実行することで SKILL.md を生成しています。
生成されるSkillは基本的に 「手動で書いた指示(user_instruction)を、そのままSkill本文に入れる」 形になっています。
API利用でガシガシClaude Codeを並列で回している石油王の方、Claude公式が提供する
/skill-creatorを用いた検証をお待ちしております。
僕の方ではコスト的にこれ以上の検証はちょっと...といった感じなので。
/create-skill の実装詳細(SKILL.md)
---
name: create-skill
description: 指定されたタスクを実行し、再利用可能なSkill定義を生成
argument-hint: [ファイル名(IDE接続によって省略可能)] [シンボル名(IDE接続によって省略可能)] [作業内容]
model: claude-sonnet-4-5-20250929
context: standard
user-invocable: true
allowed-tools: Read, Write, Grep, Glob, StrReplace, Update, Bash
---
# create-skill
指定されたタスクを実行し、その作業内容に基づいて再利用可能なSkill定義ファイル(SKILL.md)を生成します。
## 使い方
/create-skill $ARGUMENTS
ユーザー(私)によって`$ARGUMENTS` = 「$ARGUMENTS」には以下の内容が渡されます。
- <file_name>作業対象のファイル名(ここに含まれず、IDE接続機能によってシステムリマインダー経由であなたに提示される場合もあります)
- <symbol_name>作業対象のシンボル名(ここに含まれず、IDE接続機能によってシステムリマインダー経由であなたに提示される場合もあります)
- <user_instruction>作業内容(必ず含まれるべきです。)
もし`$ARGUMENTS` = 「$ARGUMENTS」が空の場合は間違えてコマンドを実行した可能性があります。
- 何もせずに、送信ミスかどうか確認をとってください
## 実行方針
1. **タスクの実行**: 指定されたタスクを実際に完了させる
- タスク実行中に使用したツールは<used_tools>として記憶してください
- 形式は`Read,Write,Grep,Glob,StrReplace,Update,Bash`のようにカンマ区切りです
- 実行後、この手順の適切なSkill名を<skill_name>として記憶してください
- タスク実行中にエラーが発生するなど今後の知見になることは<notice>として記憶してください
2. **Skill作成**:
```bash
./.claude/scripts/new_simple_skill.sh <skill_name> <user_instruction> <used_tools> <notice>
重要:簡潔さの原則
- Skillは最小限の内容で作成する(目安:20行以内)
- 説明は1-2行で十分。詳細な手順や例は不要
- 注意事項は初回作成時には含めず、実行時にエラーが発生した場合のみ追記
- AIが自明に判断できる手順は明示しない(例:「Readツールでファイルを読む」など)
-
allowed-toolsは実際に使用したツールのみを含める(最小限) - Skill名はタスクの内容から適切に命名する(例:
add-jsdoc,type-to-interface) - 作業効率の悪化を防ぐため、SKILL.mdを作成して良いかは聞かないでください
new_simple_skill.sh(Skill生成スクリプト)
Skill_name=$1
user_instruction=$2
used_tools=$3
notice=$4
mkdir -p .claude/skills/$Skill_name
echo "---
name: $Skill_name
description: $user_instruction
allowed-tools: $used_tools
---
# $Skill_name
$user_instruction
# 注意事項
$notice
" > .claude/skills/$Skill_name/SKILL.md
ポイント: ユーザーの指示(user_instruction)がそのままSkill本文になるため、指示の質がそのままSkillの質に直結します。
つまり今回の検証の範囲では、以下のような違いがあります。
- create: 「タスクを実行する」+「Skillファイルを作る」という追加作業が入る(ここが多くのトークンを消費する)
-
use: 中身はcreateでの指示に依存し、そこを工夫しないと直接入力より劇的に短く/安定するとは限らない(少なくとも
/で呼び出すことによる多少のオーバーヘッドを回収できるような工夫が必要)
という構造になっていて、「トークン効率の近道」になりにくかった、という読み方ができます。
ざっくり結論(数字だけ)
Skill作成とその使用、および比較として直接入力を繰り返した場合の平均IN(New)は以下の通りです。
直接入力と比較して、Skill使用の場合、平均で859トークンが余分に投入されました。
| 平均IN(New) | |
|---|---|
| Skill作成(create) | 103,951 |
| 作ったSkillを使用(use) | 5,492 |
| 直接入力を繰り返し(direct_cached) | 4,633 |
つまり、今回の検証範囲では:
- 自動Skill化Skillを用いるコストはかなり高い
- 単に命令をそのままSkill化した場合、作った後に使う(use)も直接入力(direct_cached)より安いとは言えなかった
たくさん回すなら話が変わるかもしれない(外れ値とキャッシュ)
今回の自動Skill化の検証は3〜4回程度の比較です。
しかし別の記事には、直接入力側に外れ値の混入しやすいケースがあると書きました。回数を重ねると、その影響で平均値の上昇する傾向があります。
このあたりは「相当数こなすなら、Skill化(=同じ命令プレフィックスを繰り返す)でキャッシュが効いて、安定してくるかも」という見立てが立ちます。
補足すると、記事Aの検証は "完全に同じ文言"をSkillとして登録して繰り返し実行しているので、この観点(同一プレフィックスの反復・外れ値の出方)とはかなり相性が良いです。
一方で自動Skill化は「作成コスト(create)」が別途乗ること、また「生成されるSkill本文のテンプレ品質」によって use 側の効き方が変わり得るため、どの程度の回数でトレードオフが逆転するかは追加検証が必要です。
手動指示だと「余分な変更」が混ざることがある
これは今回の集計には入っていない話ですが、試行錯誤の過程では、手動で指示すると意図しない変更が混ざってしまうケースがありました。(ここを再検証しようとするとClaude Codeのコストが跳ね上がるので、今回は省略します。ごめんなさい…!)
Skill化して指示を固定すると、その手のブレが減る可能性はあります。ただ、そこまで厳密に"検証結果として"出すには追加の実行回数が必要で、Claude Codeのコストが無視できなくなるので、本稿では「観測としての補足」に留めます。
おわりに
「小さいタスクもSkill化すべき?」の答えは、個人的にはこうです。
- 直接入力で始めてOK(小さく始める)
- 何度も同じことをするなら、手動Skillで"資産化"する
- Skill作成Skillは、効率目的というより 作業コストを下げるために使う(トレードオフとして扱う)
検証に使ったリポジトリはこちらで公開しています。
関連記事
- Claude Code Skillは本当に効率的? —— 鍵を握るPrompt Caching
- Skillの中でSkillを呼びたい! —— vs 同内容でのネスト呼び出しによるトークン消費の悪化
- Claude Codeのprompt caching —— 仮説、および上手にハックできないかの提案
共同執筆
- cursor:
- 執筆: GPT-5.2
- データ分析・精査: GPT-5.2 codex
- ChatGPT:
- 草案作成
- DeepResearch
Discussion