Claude Codeの仕組み講座（講師のためのエンジニア水準）
区分3 拡張の仕組み★★★スキルは、フォルダの中の SKILL.md というファイルに書いた「やり方の手順書」です。SKILL.md の先頭には、名前や説明を書く決まった欄があります。これを frontmatter（フロントマター。ファイル冒頭の設定欄）と呼びます。
事務所で考えると分かりやすいです。CLAUDE.md（No.08）は、毎朝全員の机に置かれる社内規程集です。スキルは、棚にしまってある業務マニュアルで、棚の背表紙だけが見えています。「請求書を作って」と言われた時に、はじめて棚から出して読みます。
| 机に出る時機 | 向いている物 | |
|---|---|---|
| CLAUDE.md | 毎回の最初 | いつも守る決まり |
| スキル | 必要になった時 | 特定の作業の手順 |
| フック（No.10） | AIの判断と関係なく決まった瞬間 | 必ず起こしたい自動処理 |
「机」はコンテキスト（AIが一度に見渡せる範囲）のことです。スキルに長い手順を移すと、普段の机が空きます。「トークン」はその大きさを測る単位で、文字をAIが数える時の細かい区切りのことです。
スキルの仕組みの中心は、読み込みが3段階に分かれていることです。
会話を始めた時、机に置かれるのは、各スキルの名前と description（説明文）だけです。本文はまだ読まれていません。
説明文は、長すぎると途中で切られます。公式では、description と when_to_use（使う場面の補足欄）を合わせて1,536文字が上限です。だから、使う場面は説明文の前の方に書きます。
使うと決まったら、SKILL.md の本文が1通のメッセージとして会話に入ります。一度入った本文は、その後の会話にもずっと残ります。同じスキルをもう一度呼んでも、全文はもう一度は置かれず、「読み込み済み」の短い知らせが入ります。
本文は呼ばれた後の毎回の会話で机を使い続けます。公式は、SKILL.md を500行以内にして、細かい資料は別ファイルに分けることを勧めています。
同じフォルダに、見本・台本・スクリプトを置けます。
my-skill/
├ SKILL.md 手順の本体（必須）
├ reference.md 必要な時だけ読む資料
├ examples.md 必要な時だけ読む見本
└ scripts/
└ helper.py 実行される。中身は机に出ない
SKILL.md に「詳しくは reference.md を見る」と書いてあれば、AIはその時に開きます。スクリプト（パソコンに実行させる小さなプログラム）は実行されるだけで、プログラムの中身は机に出ません。結果だけが返ります。
○ 受講生によく聞かれる質問：「スキルをたくさん入れると、会話が重くなりませんか」
→ 答え方：呼ばれていないスキルは名前と説明文しか机にありません。ただし説明文は毎回の机にあるので、数百個を入れれば無視できなくなります。使わない物は、自動で呼ばれない設定（第2章②）にすれば、説明文も机から消えます
○ 講義で使える図のたとえ：棚の背表紙＝名前と説明文、棚から出した1冊＝本文、その1冊に挟んだ別冊＝付属ファイルです。
○ 関係する単元：No.05 コンテキストウィンドウの中身（机が埋まる話）
SKILL.md は、最初の行を --- で始めて、設定を書き、もう一度 --- で閉じます。
その下が本文です。冒頭の行が --- でないと、設定欄として読まれません。
---
name: deploy
description: 本番に公開する時の手順。公開・リリース・デプロイと言われた時に使う
disable-model-invocation: true
---
ここから本文（手順）
公式で確かめた主な項目は、次の表の通りです。
| 項目 | 役割 |
|---|---|
name |
呼び出す名前（/名前）。省略するとフォルダ名 |
description |
AIが「いま使うか」を決める説明文。省略すると本文の最初の行が代わりに使われる |
when_to_use |
使う場面の補足。description に足されて、合計1,536文字まで |
disable-model-invocation |
true にするとAIが自分では呼ばなくなる（自分の /名前 だけ） |
user-invocable |
false にすると、/ の一覧から隠す。AIだけが呼べる |
allowed-tools |
そのスキルの間、許可の確認なしで使える道具を指定 |
context |
fork にすると、別の会話（サブエージェント。No.12）で動かす |
paths |
指定したファイルの形（例：src/api/**/*.ts）に当てはまるファイルを読んだ時だけ、AIが自動で読み込む、という条件 |
argument-hint |
/名前 の入力欄に出る、引数（スキルに渡す追加の言葉）の書き方のヒント |
書き間違えた項目は、エラーにならず無視されます。設定が効かないときは、まず綴りを疑ってください。
| 設定 | 自分が /名前 で呼ぶ |
AIが自動で呼ぶ | 説明文は机にある |
|---|---|---|---|
| 何も書かない | できる | できる | ある |
disable-model-invocation: true |
できる | できない | ない |
user-invocable: false |
できない | できる | ある |
送信や削除のような副作用のある手順は、disable-model-invocation: true にします。
AIが勝手に呼ばなくなり、説明文も机から消えます。
| 範囲 | 場所 |
|---|---|
| 組織全体 | 組織が管理する設定フォルダの .claude/skills/ |
| 自分の全作業場 | ~/.claude/skills/スキル名/SKILL.md |
| その作業場 | .claude/skills/スキル名/SKILL.md |
| プラグイン | プラグインの skills/スキル名/SKILL.md。呼び名は /プラグイン名:スキル名 |
同じ名前が複数あるときは、組織 → 自分 → 作業場の順で強い方が使われます。プラグインのスキルは名前にプラグイン名が付くので、ぶつかりません。ほかの機能との強さの順番は、機能ごとの比較として No.15 にまとめています。
あなたの環境では、~/.claude/skills/（~ は自分のホームフォルダ）に、手元で確かめた時点で30個のフォルダがあります。たとえば course-builder を開くと、先頭の name と description が見えます。この講座を作る手順も、この中に入っています。
AIが自動でスキルを使うかどうかは、特別な判定プログラムが決めているのではありません。あなたの依頼と、机に並んでいる説明文を見比べて、AIが自分で選んでいます。だから、次のことが起きます。
確実に使いたい時は、/名前 で直接呼びます。/名前 をメッセージの先頭に書くと、そのスキルが直接動きます。「このまま /deploy して」のように文の途中へ書いた場合は、すぐには動きません。そのメッセージの間だけ、AIが「そのスキルを使ってよい」と受け取り、頼まれたかどうかを文面から判断します。使わせたくない時は、スラッシュを付けずに名前だけを書きます。
長い会話は途中で要約されます（No.06）。その時、呼ばれたスキルの本文は、直近の分から順に、各スキルの先頭5,000トークンまでを、全体で25,000トークンまで戻されます。たくさんのスキルを呼んだ後の古い物は、戻されないことがあります。細かい数字は版で変わるので、「要約の後でも一部は戻る」とだけ覚えておけば十分です。
○ 受講生によく聞かれる質問：「スキルを作ったのに呼ばれません」
→ 答え方：まず説明文を見ます。「どんな時に使うか」が、自分（スキルを使う人）が普段使う言葉で書かれているかが決め手です。確かめたいときは /名前 で直接呼んで、中身が動くかを先に見ます
○ 受講生によく聞かれる質問：「CLAUDE.md とスキル、どちらに書きますか」
→ 答え方：毎回必ず守らせたい決まりは CLAUDE.md、特定の作業の長い手順はスキルです。公式の目安は、CLAUDE.md を200行以内にして、長くなったらスキルへ移すことです
○ 講義で使える図のたとえ：説明文は「棚の背表紙」です。背表紙に「請求書」と書いてあれば、新人は迷わず取り出せます
○ 関係する単元：No.08 CLAUDE.md と記憶、No.12 サブエージェント
スキル＝名前と説明文だけ常に机に置き、呼ばれたら本文が出て、付属ファイルは指された時だけ。呼ばれるかは説明文しだい。確実に使うなら /名前。
問1 普通に作ったスキル（disable-model-invocation は使っていない）を30個入れた直後、会話を始めた時点で机に置かれているのは？
問2 「送金の手順」のスキルを、AIが勝手に呼ばないようにしたい。どうする？
問3 作ったスキルが、合うはずの依頼で使われません。まず見直す所は？
問4 スキルの本文が机に置かれた後、その本文はどうなる？
出典：Claude Code 公式ドキュメント「Extend Claude Code with skills」（https://code.claude.com/docs/en/skills）／「Extend Claude Code」（https://code.claude.com/docs/en/features-overview）／手元の ~/.claude/skills/ の実物