第1章では、SkillがSKILL.mdという1枚のファイルであることを説明しました。ここからは、そのファイルをどこに置けば動くのか、そしてAIがどうやってそのSkillの存在を知るのかを見ていきます。
プロジェクト用とユーザー全体用の2種類
Skillの置き場所は主に2つあります。
- プロジェクト用:
.claude/skills/{skill名}/SKILL.md。そのプロジェクトのフォルダ配下だけで使えます。チームで共有したい業務手順や、そのリポジトリ固有の作業（デプロイ手順、命名規則の確認など）に向いています。 - ユーザー全体用:
~/.claude/skills/{skill名}/SKILL.md。どのプロジェクトを開いていても使えます。文章の校正ルールや、個人がいつも使う定型作業など、プロジェクトを問わず使い回したいSkillに向いています。
プロジェクトの場合
myproject/.claude/skills/deploy-check/SKILL.md
ユーザー全体の場合
~/.claude/skills/writing-norms/SKILL.md同じ名前のSkillが両方に存在する場合はプロジェクト側が優先されます。個人の共通ルールをユーザー全体用に置きつつ、特定のプロジェクトだけ挙動を上書きしたいときに使える構成です。
プラグイン経由で導入する方法もある
自分でSKILL.mdを書く以外に、プラグインとしてパッケージ化されたSkillを導入する方法もあります。この場合はプラグインのインストール手順に従うだけで、複数のSkillがまとめて使えるようになります。社内やチームで統一した作業手順を配布したいときは、個別ファイルのコピーよりもプラグイン化しておくほうが更新の管理が楽になります。
descriptionがAIの判断材料になる
SKILL.mdの冒頭にはnameとdescriptionを書きます。このうちdescriptionは、そのSkillを人間向けに説明するためだけの項目ではありません。AIが「今の作業にこのSkillを使うべきか」を判断する唯一の手がかりです。
---
name: deploy-check
description: 本番デプロイ前に接続確認とバックアップの有無をチェックする。「デプロイして」「本番反映」と言われたときに使う
---悪い例は「デプロイ関連の作業」のような抽象的な一文です。これではAIが、ユーザーの発言のどの場面でこのSkillを思い出せばいいのか判断できません。良い例は、具体的な作業内容と、どんな発言のときに使うべきかのトリガーになる言葉を含めることです。descriptionが曖昧だと、Skillを作ったのに一度も呼ばれないという事態が起きます。
同梱ファイルは必要なときだけ読まれる
SKILL.mdと同じフォルダには、参考資料やスクリプトを同梱できます。テンプレートファイル、チェックリスト、変換用のPythonスクリプトなどです。
.claude/skills/article-draft/
SKILL.md
reference/style-guide.md
scripts/word-count.pyここで重要なのは、これらの同梱ファイルは常にAIに読み込まれるわけではないという点です。Skillが呼び出された時点でSKILL.md本体は読み込まれますが、reference以下の資料やscripts以下のコードは、SKILL.mdの手順の中で「必要になったら読む」という形で参照されて初めて読み込まれます。長大な資料をすべて常時AIに渡すと、それだけでコンテキストを消費してしまいます。同梱という仕組みは、必要な情報を必要なタイミングだけ渡すための設計です。
呼び出しは2通りある
Skillの呼び出し方には2つの経路があります。
- スラッシュコマンドによる明示的な呼び出し:
/deploy-checkのように、ユーザーが名前を直接指定して起動します。確実にそのSkillを使わせたいときに使います。 - AIによる自律的な選択: ユーザーが会話の中で「本番に反映して」と発言しただけで、AIがdescriptionを見て該当するSkillを自分で選び、呼び出します。ユーザーはSkillの存在を意識しなくても、意図した手順が自動的に実行されます。
後者が機能するかどうかは、前述のdescriptionの書き方に懸かっています。呼び出されるSkillを作りたいなら、手順の中身を練る前に、まずdescriptionが具体的なトリガーになっているかを確認してください。
置き場所と呼び出しの仕組みが分かったところで、次はSKILL.mdの中身、つまり手順そのものをどう書けば実際に機能するのかを見ていきます。