この記事でやること
- Claude Code の Skills がどのように選択・呼び出されるかを解説
- Description のベストプラクティスを公式ドキュメントから紹介
- 自作 Skill と Skill Creator で生成した Skill を比較
この記事により解決すること
- 「Skillを作ったのに呼び出されない」問題の原因がわかる
- 呼び出されやすい Skill の書き方がわかる
前提
- Claude Code をインストール済み
- Skills の基本的な概念を理解している
Skills の仕組み
Claude がスキルを選択する流れ
Claude Code の Skills は model-invoked です。
つまり、ユーザーが明示的に呼び出さなくても、Claude が自律的に使用を判断します。
公式ドキュメントには以下のように記載されています：
Skills are model-invoked—Claude autonomously decides when to use them based on your request and the Skill's description.
では、Claude はどのように「このスキルを使うべきか」を判断しているのか？
name と description だけが読み込まれる
重要なポイントは、Skill の全内容がシステムプロンプトに読み込まれるわけではない ということです。
起動時に読み込まれるのは YAML frontmatter の name と description のみです：
---
name: my-skill
description: ここに書いた内容だけが最初に読み込まれる
---
公式ドキュメントでも以下のように強調されています：
The description field is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills.
つまり、description の書き方がスキル選択のすべてを決める と言っても過言ではありません。
参照元: https://code.claude.com/docs/en/skills.md
ここまでは割と皆さんご存知の！といった内容かと思います。
私もここまでは存じてました。
nameとdescriptionはちゃんと定義しないとな。
commandとかと違って、コンテキストの読み込みの節約になりそう！と思ったはず。
Description のベストプラクティス
公式ドキュメントで推奨されている Description の書き方を紹介します。
私は全く読んでませんでした。
1. 三人称で記述する
Description はシステムプロンプトに注入されます。一人称や二人称で書くと、文脈が不自然になります。
# 良い例
description: Processes Excel files and generates reports
# 悪い例
description: I can help you process Excel files
description: You can use this to process Excel files
2. 「Use when...」を含める
「いつ使うか」を明示的に記述することで、Claude が適切なタイミングで選択しやすくなります。
description: Extract text from PDF files. Use when working with PDF files or when the user mentions document extraction.
3. 具体的なキーワードを含める
ユーザーが言及しそうな用語を description に含めておくと、マッチしやすくなります。
# 良い例（キーワード豊富）
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing .xlsx files, tabular data, or spreadsheets.
# 悪い例（曖昧）
description: Helps with documents
4. 曖昧な表現を避ける
Helps with... や Does stuff with... のような曖昧な表現では、Claude がスキルの用途を正確に理解できません。
参照元: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.md
自作 Skill の紹介
私が Claude Code に作成させた Rust コードレビュー用の Skill です。
frontmatter
name: code-review
description: Rustプロジェクトのコードレビューを実施。ユーザーがレビューを依頼した時、変更規模に関わらず使用。
ディレクトリ構成
code-review/
└── SKILL.md
問題点
ベストプラクティスと照らし合わせると、いくつかの問題があります。
| 観点 | 自作 Skill の状態 | ベストプラクティス |
|---|---|---|
| スキル名 |
code-review（汎用的） |
言語・用途を明示すべき（例: rust-code-review） |
| 記述言語 | 日本語 | 英語・三人称が推奨 |
| トリガー表現 | 「レビューを依頼した時」 |
Use when... 形式が推奨 |
| キーワード | 少ない（Rust、レビュー程度） | 具体的な用語を網羅すべき（clippy, fmt, test など） |
| 構成 | md ファイル 1 つのみ | Progressive Disclosure 推奨 |
特に description が日本語で書かれている点と、具体的なキーワードが少ない点が、呼び出されにくい原因と考えられます。「レビューして」というプロンプトでは、code-review という汎用的な名前と曖昧な description では、Claude が確信を持って選択できない可能性があります。
Skill Creator の紹介
Skill Creator は Anthropic が提供する Skill 生成ツールです。
- GitHub: https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md
- ベストプラクティスに沿った Skill を自動生成
- 参照ファイルやスクリプトも含めた構成を作成
Skill Creator で生成した Skill の紹介
同じ「Rust コードレビュー」という目的で、Skill Creator を使って生成した Skill です。
frontmatter
name: rust-code-review
description: Comprehensive Rust code review for PRs and diffs. Covers security, performance, idiomatic Rust patterns, and automated checks (clippy, fmt, test). Use when reviewing Rust code changes, pull requests, or performing code quality assessments on Rust projects.
ディレクトリ構成
rust-code-review/
├── SKILL.md
├── references/
│ ├── performance-checklist.md
│ ├── rust-idioms.md
│ └── security-checklist.md
└── scripts/
└── run_checks.py
優れた点
| 観点 | Skill Creator 版の状態 | なぜ良いか |
|---|---|---|
| スキル名 | rust-code-review |
言語が明示されている |
| 記述言語 | 英語・三人称 | システムプロンプトとの一貫性 |
| トリガー表現 | Use when reviewing Rust code... |
明確なトリガー条件 |
| キーワード | PRs, diffs, security, performance, clippy, fmt, test など多数 | 様々なプロンプトにマッチしやすい |
| 構成 | references/ + scripts/ 分離 | Progressive Disclosure パターン |
description に Use when... が含まれ、具体的なキーワードが豊富に含まれています。「Rust のコードをレビューして」「PRを確認して」「clippy を実行して」など、様々なプロンプトでマッチする可能性が高くなっています。
また、ディレクトリ構成も Progressive Disclosure パターンに従っています。これは「必要な時だけファイルを読み込む」という設計思想で、SKILL.md から参照ファイルへのリンクを張り、Claude が必要に応じてチェックリストを読み込む構成になっています。
まとめ
| 項目 | 自作 Skill | Skill Creator 版 |
|---|---|---|
| 呼び出されやすさ | △ | ○ |
| description の質 | 曖昧、キーワード不足 | 具体的、トリガー明示 |
| 構成 | シンプル | Progressive Disclosure |
結論:
- Skill が呼び出されるかは description の書き方次第
-
Use when...と 具体的なキーワード を含めることが重要 - 自作する場合はベストプラクティスを意識する必要がある
- Skill Creator を使えば自動的にベストプラクティスに沿った Skill が生成される
自作のSkillをSkill CreatorのSkillに置き換え、果たして自律的な使用率が上がるのか今後試していこうと思います。
英語圏の方でもClaudeCodeがSkillを使ってくれないと悩んでました。
その方はHooksで都度Skillを使用するべきか判断させるフェーズを設けていて面白かったです。