背景
Claude Codeのカスタムスキル（SKILL.md）を作成するハンズオンで、descriptionフィールドの役割を正しく理解していないと期待通りに動かないという発見がありました。スラッシュコマンドの3分類とあわせて整理します。
1. スラッシュコマンドはビルトイン・バンドルスキル・カスタムスキルの3種類に分かれる
/clear → ビルトインコマンド（Claude Code本体の機能）
/code-review ★ → バンドルスキル（Anthropic公式提供、17個）
/pre-pr-check → カスタムスキル（自分で作成）
/skillsコマンドで現在利用可能なスキル一覧を確認でき、Anthropic公式のバンドルスキルには★マークが付きます。カスタムスキルはこのバンドルスキルと同じSKILL.md形式で実装できるため、公式スキルの実装が参考になります。
2. カスタムスキルはフォルダを作ってSKILL.mdを置くだけ
mkdir -p .claude/skills/pre-pr-check
touch .claude/skills/pre-pr-check/SKILL.md
フォルダ名がそのままスラッシュコマンド名になります。特別なビルドや登録作業は不要で、/reload-skillsを実行するかセッションを再起動するだけで有効になります。
3. descriptionは「いつ使うか」をClaudeに教えるためのテキスト
# 悪い例：何をするかだけ書いている
description: PRのチェックを実行する
# 良い例：いつ使うかが明確
description: PRを出す前の事前チェックを実行する。Use when the user wants to
prepare a pull request or review code before submitting.
descriptionは人間向けの説明文ではなく、Claudeが「このスキルを自動的に呼び出すべきタイミング」を判断するための材料です。英語でUse when...の形式で具体的に書くほど、意図したタイミングでの自動提案の精度が上がります。
4. プロジェクトレベルとユーザーレベルは保存場所だけが違う
.claude/skills/ → プロジェクトのみ有効、gitで管理してチーム共有可能
~/.claude/skills/ → 全プロジェクトで有効、個人設定（共有不可）
プロジェクト固有の手順（デプロイ先・テストコマンド）はプロジェクトレベルに、どのプロジェクトでも使う汎用的な作業はユーザーレベルに置きます。迷ったらまずプロジェクトレベルで作り、後からユーザーレベルに移動する方が、チーム共有の観点では扱いやすいという運用上のヒントもあります。
5. カスタムスキルは同名のバンドルスキルより優先される
.claude/skills/code-review/SKILL.md を作成
→ Anthropicの /code-review バンドルスキルより優先して呼び出される
意図的にバンドルスキルをカスタマイズしたい場合は有効ですが、誤って上書きしてしまうケースもあるため、命名の際は注意が必要です。
まとめ
descriptionフィールドが「いつ呼び出すか」の判断材料である、という理解が、カスタムスキルを狙い通りに動かすための最重要ポイントでした。CLAUDE.mdは常時読み込み・SKILL.mdは呼び出し時のみ読み込み、という使い分けの原則も、コンテキスト消費を抑える上で意識しておく価値があります。