Claude Code 実践検証 Day 12｜Skills発火条件の真実―公式と実態のギャップ
昨日の疑問、実際に検証してみました。
結論から言うと、公式ドキュメントの「semantic matching」は現時点では機能していません。でも、確実に発火させる方法は見つかりました。しかもHeadlessモードでも使えるパターンがあったんです。
検証結果まとめ
| 検証項目 | 結果 | 補足 |
|---|---|---|
| スキル検出 | ○ | ユーザー/プロジェクト両方で認識される |
| 日本語キーワードで発火 | × | 「コミットを作成して」では発火しない |
| 英語キーワードで発火 | × | 「create a git commit」でも発火しない |
| スキル名明示で発火 | ○ | 「〇〇スキルを使って」で確実に発火 |
| 「skill」キーワードで発火 | ○ | 「skill 〇〇」でも発火する |
| Headlessモード | △ | 「skill 〇〇」形式なら発火する！ |
意外だったのは、公式が言う「descriptionに基づいて自動発火」が全く機能しなかったこと。でも「skill」キーワードを使えばHeadlessでも動くのは嬉しい発見でしたね。
検証1：日本語キーワードでの発火
まずは公式ドキュメントが主張する「semantic matching」を検証。commit-helperスキルには以下のdescriptionが設定されています。
description: Use this skill when the user asks you to create a git commit,
commit changes, or save their work with version control.
やったこと
以下のプロンプトを試しました。
- 「コミットを作成して」
- 「git commitして」
- 「変更をコミットしてください」
結果
3パターンすべてで、commit-helperスキルは発火しませんでした。
> コミットを作成して
● I'll help you create a git commit. Let me first check the current state...
● Bash(git status)
...
Skillツール（● Skill(commit-helper)）の呼び出しは表示されず、直接Bashでgitコマンドが実行されました。
正直に告白すると、ここで30分くらい「なんで発火しないんだろう」と悩みました。descriptionには「create a git commit」って書いてあるのに。
わかったこと
日本語プロンプトから英語descriptionへの「意味的マッチング」は、少なくとも現バージョン（v2.0.64）では機能していないようです。
検証2：英語キーワードでの発火
日本語がダメなら英語ならどうか。descriptionに含まれるキーワードそのものを使ってみました。
やったこと
create a git commit
descriptionに「create a git commit」という文言が含まれているので、これなら発火するはず…
結果
発火しませんでした。
> create a git commit
● I'll help you create a git commit. Let me first check the current state of the repository.
● Bash(git status)
...
これは予想外でした。descriptionの中にある文言をそのまま使っても発火しないんです。
わかったこと
部分一致では発火しません。「create a git commit」というキーワードが含まれていても、descriptionの「一部」だけでは認識されないようです。
検証3：確実に発火させる方法
では、どうすれば発火するのか。いくつかパターンを試しました。
やったこと
- スキル名を明示：「commit-helperスキルを使って」
- 「skill」キーワード：「skill コミット作成」
- description完全一致：「Use this skill when the user asks you to create a git commit」
結果
3パターンすべてで発火成功。
> commit-helperスキルを使って
● Skill(commit-helper)
⎿ Loading…
Use skill "commit-helper"?
Claude may use instructions, code, or files from this Skill.
確認ダイアログが表示され、Yesを選択するとSKILL.mdの内容が読み込まれます。
発火パターンの比較
| プロンプト | 発火 | 備考 |
|---|---|---|
| 「コミットを作成して」 | × | 日本語 |
| 「create a git commit」 | × | 英語キーワード |
| 「commit-helperスキルを使って」 | ○ | スキル名明示 |
| 「skill コミット作成」 | ○ | 「skill」キーワード |
| description完全一致 | ○ | 全文コピペ |
「skill」というキーワードを含めると発火しやすくなる、というのは発見でしたね。
検証4：Headlessモードでの動作
スクリプトやバッチ処理で使えるか確認しました。
やったこと
# パターン1：スキル名明示
claude -p "data-analyzerスキルを使ってデータを分析して"
# パターン2：「skill」キーワード
claude -p "skill 日本語の文法チェック"
結果
パターン1は発火せず、パターン2は発火成功！
$ claude -p "skill 日本語の文法チェック"
<command-message>japanese-skill is running…</command-message>
日本語スキルを起動しました。日本語の文法チェックや文章の校正をお手伝いします。
...
これは嬉しい発見でした。Headlessモードでも「skill」キーワードを使えばSkillsが使えます。
Headlessモード発火条件
| プロンプト | 対話モード | Headlessモード |
|---|---|---|
| 「〇〇スキルを使って」 | ○ | × |
| 「skill 〇〇」 | ○ | ○ |
スクリプトからSkillsを呼び出したい場合は、claude -p "skill 〇〇" 形式を使いましょう。
公式ドキュメントとの比較
| 項目 | 公式の説明 | 実際の動作 | 差異 |
|---|---|---|---|
| 発火方式 | semantic matching | 文字列マッチング | 大きな差異 |
| キーワード発火 | descriptionのキーワードで発火 | キーワードだけでは発火しない | 大きな差異 |
| 発火例 | 「コミットメッセージを生成して」で発火 | 発火しない | 大きな差異 |
| Headlessモード | 記載なし | 「skill」キーワードで発火可能 | 発見 |
公式ドキュメントには「descriptionに基づいて自動的に発火する」と書いてあるんですが、実際にはかなり限定的。semantic matchingは機能していないと考えた方がいいですね。
ただ、「skill」キーワードでHeadlessモードでも使える、というのは公式には書いてない発見でした。これは使える情報だと思います。
実務での推奨設定
検証結果を踏まえて、確実にSkillsを発火させる方法をまとめます。
推奨するやり方
# 対話モード
「commit-helperスキルを使ってコミットを作成して」
# Headlessモード
claude -p "skill コードレビュー src/main.ts"
ポイント
- スキル名を明示的に指定する - 「〇〇スキルを使って」形式が最も確実
-
Headlessでは「skill」キーワードを使う -
claude -p "skill 〇〇"形式 - description matchingに頼らない - semantic matchingは機能していない
避けた方がいいこと
- 「コミットして」など暗黙的な依頼でSkillが発火することを期待する
- descriptionを工夫すれば自動発火すると思い込む
- Headlessモードで「〇〇スキルを使って」形式を使う（動かない）
まとめ
今回の検証で分かったこと。
- semantic matchingは現時点では機能していない - 公式ドキュメントの「期待される動作」と実態には差がある
- 確実に発火させるにはスキル名の明示が必要 - 「〇〇スキルを使って」または「skill 〇〇」
- Headlessモードでも「skill」キーワードなら使える - スクリプトからの呼び出しにも対応
公式ドキュメントを読んで「Skillsって便利そう！」と思った人、私もそうでした。でも実際に使ってみると、ちょっと期待と違う部分があります。
ただ、使い方さえわかれば便利な機能です。同じところで悩んでる人の参考になれば。
この検証結果を使うと
Skillsの発火条件を正確に把握したことで、「いつもの手順」を確実に呼び出せるようになりました。1月からの実践編では、コードレビューやドキュメント生成などの定型タスクをSkillsで自動化するエージェントを構築します。
付録：検証で使用したスキルの例
今回の検証で使用したSKILL.mdファイルを参考として掲載します。
commit-helper/SKILL.md（英語description）
---
description: Use this skill when the user asks you to create a git commit, commit changes, or save their work with version control. This skill provides a consistent commit message format.
---
# Commit Helper Skill
## Purpose
This skill helps create consistent git commit messages following conventional commit format.
## Commit Message Format
<type>(<scope>): <subject>
### Types
- `feat`: A new feature
- `fix`: A bug fix
- `docs`: Documentation only changes
- `refactor`: Code refactoring
- `chore`: Maintenance tasks
## Instructions
1. Check `git status` to see changes
2. Check `git diff --staged` to understand what's being committed
3. Generate a commit message following the format above
4. Ask user for confirmation before committing
japanese-skill/SKILL.md（日本語description）
---
description: 日本語でドキュメントを作成したり、文章を校正したりする際に使用するスキル。日本語の文法チェックや表現の改善を行います。
---
# 日本語ドキュメント作成スキル
## 目的
日本語でのドキュメント作成と文章校正を支援します。
## 機能
1. **文法チェック**
- 敬語の使い方
- 主語と述語の対応
- 句読点の配置
2. **表現改善**
- 冗長な表現の削除
- より適切な言い回しの提案
## 使用例
- 「このドキュメントを日本語で書いてください」
- 「この文章を校正してください」
descriptionに「Use this skill when...」や「〜する際に使用するスキル」と書いても、それだけでは自動発火しません。明示的にスキル名を指定するか、「skill」キーワードを使う必要がある、というのが今回の検証結果でした。
シリーズを追いかける
12月25日まで毎日更新。フォローしておくと通知が届きます。「うちではこう動いた」などのコメントもお待ちしてます。
Discussion