Claude CodeのSKILL.mdの書き方と置き場所・frontmatter【Claude Codeスキル入門第2回】

「スキルを作ってみたいのですが、どこに置けばよいのでしょう。自分だけで使う場合と、チームで使う場合で場所は違いますか」
「SKILL.md を書いたのに、Claude が使ってくれません。直したあとは、再起動が要りますか」

第1回（スキルとは何か）で、スキルは指示と資料を入れたフォルダーで、中心は SKILL.md だと見ました。第2回は、その SKILL.md を実際に書きます。スキルの置き場所と使える範囲、SKILL.md の形、frontmatter のフィールド、本文の書き方、作って確かめる5つの手順、更新と削除を扱います。どう書けば Claude が発動するかは、第3回の「説明は2つの問いに答える」で詳しく扱います。

スキルの置き場所
SKILL.md の形
frontmatter のフィールド
本文の書き方
作って確かめる
1. 筆者が試したら
更新と削除
考えてみよう
まとめ
連載「Claude Codeスキル入門」全12回

スキルの置き場所

置き場所で、どのセッションがそのスキルを読み込むかが決まります。この連載では、次の4つを押さえます。

置き場所	パス	使える範囲
個人のスキル	`~/.claude/skills/<名前>/SKILL.md`	自分のすべてのプロジェクト（この PC）。Cowork・クラウドのセッションでは読まれない
プロジェクトのスキル	リポジトリの `.claude/skills/<名前>/SKILL.md`	そのリポジトリのセッション。コミットすればチーム全員。チームで共有するスキルはここ
管理設定で配られるスキル（Enterprise）	管理設定のフォルダー内の `.claude/skills/`	組織が配った全ユーザー。組織のプラン向けで、この連載では扱いません
プラグインのスキル	`<plugin>/skills/<名前>/SKILL.md`	プラグインを有効にした所。名前は `/plugin名:スキル名`

スキルの置き場所4つを、置き場所・パス・使える範囲の3列で並べた表の図。1行目「個人のスキル」のパスは ~/.claude/skills/<名前>/SKILL.md で、使える範囲は自分のすべてのプロジェクト（この PC）。Cowork・クラウドのセッションでは読まれない。2行目「プロジェクトのスキル」のパスはリポジトリの .claude/skills/<名前>/SKILL.md で、そのリポジトリのセッション。コミットすればチーム全員。3行目「管理設定で配られるスキル（Enterprise）」のパスは管理設定のフォルダー内の .claude/skills/ で、組織が配った全ユーザー。4行目「プラグインのスキル」のパスは <plugin>/skills/<名前>/SKILL.md で、プラグインを有効にした所。名前は /plugin名:スキル名。図の見出しは「スキルの置き場所（4つ）」。

自分だけで使うなら個人、リポジトリの全員で使うならプロジェクト（Git にコミットして共有する。第8回の「共有の3つの方法と、この連載の選択」）
個人のスキルは、Cowork とクラウドのセッションでは読まれません（公式の Skills のページ）。デスクトップのスケジュール実行のタスクは、手元で動くので ~/.claude/skills/ を読みます
プラグインのスキルは、/plugin名:スキル名 と名前空間が付くので、ほかの場所の同じ名前のスキルとは別になります（第8回の「優先順位と名前の付け方」）

公式の表には、この4つのほかに、次の行もあります。

入れ子（サブディレクトリ）：<subdir>/.claude/skills/<名前>/SKILL.md。その <subdir> かその下で始めたセッションで読み込まれます。上の階層で始めたセッションでは、Claude がそのディレクトリのファイルを読み書きしたときに初めて読み込まれます
追加ディレクトリ：--add-dir で渡したディレクトリの .claude/skills/。そのセッションだけです
claude.ai のアカウント：claude.ai のアカウントで有効にしたスキル。Cowork・クラウドのセッションと、そのアカウントでサインインした端末のセッションで読み込まれます

補足：Windows の個人のスキルは C:/Users/<ユーザー>/.claude/skills です（~ は %USERPROFILE%）。公式の設定のページに「Windows では ~/.claude は %USERPROFILE%\.claude を指す」とあります。Academy のレッスン1は C:/Users/<ユーザー>/.claude/skills と書いていて、同じ場所です。また、公式のデスクトップのページには、SSH セッションは PC ではなく、接続先のホストの ~/.claude/skills を読むとあります。筆者は SSH セッションでは確かめていません。出典は https://code.claude.com/docs/ja/skills と https://code.claude.com/docs/ja/desktop です。

SKILL.md の形

SKILL.md は、2つの部分でできています。

2つの部分：先頭の --- で挟んだ frontmatter（name・description）と、その下の本文（指示）
ファイル名：SKILL.md（SKILL は大文字、md は小文字）。名前を付けたフォルダーの中に置く
例：個人のスキル commit-message-ja（日本語のコミットメッセージを書く）

---
name: commit-message-ja
description: 日本語でコミットメッセージを書く。コミットを作るとき、
  「コミットメッセージを書いて」と頼まれたときに使う。
---
# コミットメッセージ（日本語）
1. git diff --staged で変更を確かめる
2. 1行目に、何をしたかを50字以内で書く
3. 空行のあと、なぜ変えたかを書く
4. 書き終えたら、メッセージを示して止まる（コミットは人が行う）

補足：形は、Academy のレッスン2（pr-description の例）を、筆者の例に置き換えたものです。出典は https://academy.claude.com/ja/courses/introduction-to-agent-skills/creating-your-first-skill です。

公式は、frontmatter を読むのは、開きの --- がファイルの1行目にあるときだけと書いています。YAML が壊れていても、スキルは読み込まれますが、設定が空になり、/スキル名 では呼べても、Claude は description と照らし合わせられません。

frontmatter のフィールド

フィールド	意味	筆者の書き方
`name`	`/名前` の元。省略するとフォルダー名	フォルダー名と同じにして書く
`description`	何をするか＋いつ使うか。発動の判断に使う	必ず書く（第3回の「説明は2つの問いに答える」）
`allowed-tools`	動いている間、書いたツールを事前承認	`Bash` は絞って書く（第5回の「allowed-tools で事前承認する」）
`model`	動いている間のモデルを変える（そのターンだけ）	使い分けは連載「Claude Codeサブエージェント入門」第5回の「model に書ける値」、第6回の「公式の推奨と筆者の例」
`disallowed-tools`	動いている間、書いたツールを使えなくする	必要なときだけ
`disable-model-invocation`	`true` で Claude は自動で使わない。人が `/名前` で呼ぶ	副作用のある作業向け

補足：公式（https://code.claude.com/docs/ja/skills）は「すべて任意、description だけ推奨」と書きます。オープン標準の仕様（agentskills.io）と、Academy のレッスン3の動画は、name と description を必須とします。筆者の例では、name をフォルダー名と同じにし、description を必ず書く、を決まりにします（公式の必須ではなく、筆者の決まりです）。字数の上限は資料で違うので、短く書きます。

字数と名前の決まりは、次のとおりです。

name：小文字・数字・ハイフンだけで、最大64字。仕様（agentskills.io）・Academy のレッスン3・Platform のベストプラクティスの3つが、そう書いています。仕様と Academy は、フォルダー名と一致させるとも書きます。公式の Claude Code のページには name の長さの記述は見つからず、.claude/skills/deploy-staging/SKILL.md の中で name: deploy と書いて /deploy にする例があります。Platform は、anthropic・claude の語を name に含めることを禁じています
description：Academy・仕様・Platform は最大1,024字です。公式の Claude Code のページは、スキルの一覧に載せるとき、description と when_to_use を合わせて1,536字で切り詰めると書きます。測っているものが違う別々の数字なので、どちらにせよ、大事な使いどころを先頭に書き、短くまとめます

表に無いフィールドも、公式の frontmatter の表にあります。

model：公式の書き方は「このスキルが動いている間のモデル。上書きはそのターンの残りの間だけで、設定には保存されない。次のプロンプトを送ると、セッションのモデルに戻る。/model と同じ値、または現在のモデルを保つ inherit を書ける」です。Academy のレッスン3は「スキルに使用するモデルを指定」と書くだけで、範囲には触れません
effort：動いている間の Effort（low・medium・high・xhigh・max。使える段階はモデルによる）
argument-hint・arguments：引数の補助
user-invocable：false にすると、Claude だけが呼べる（人は /名前 で呼べない）。背景知識のようなものに使う
when_to_use：description に付け足す。頼まれ方の言い回しの例などを書く
context・agent：context: fork で、分けたサブエージェントの中で動かす（連載「Claude Codeサブエージェント入門」第7回の「スキルと担当の組み合わせ方2つ」）
background：context: fork のときだけ効く。既定は true で、分けたサブエージェントはバックグラウンドで動く。false にすると、スキルを呼んだターンの中で結果を待つ
hooks・paths・shell・metadata・license・compatibility：フック、対象のパス、シェル（bash が既定、powershell も選べる）など
公式は、知らないフィールドはエラーにせず無視すると書いています

disable-model-invocation と user-invocable の違いは、誰が呼べるかです。公式は、disable-model-invocation: true を「副作用のある作業や、実行のタイミングを自分で決めたい作業向け。/commit・/deploy・/send-slack-message のようなもの」としています。Claude が、コードが仕上がったように見えるだけでデプロイを決めては困るからです。

本文の書き方

本文は、スキルが使われたときに Claude が従う指示です。次の6つが勘所です。

手順は番号付きで、確かめられる形に：実践入門第4回「守られる書き方」と同じです。「ベストプラクティスに従う」ではなく、コマンドと期待する結果を書く
全体に当てはまる言い方に：本文は一度会話に入ると残り、後のターンで読み直されない（公式）。「テストを実行する」ではなく「編集のたびにテストを実行する」
完了と報告を書く：何が済んだら完了か、報告に含めるものを決める
してはいけないことと止まる所：ansible-verify なら、本実行と prod はしない。差分確認の結果を見せて止まる
大事な指示は先頭に：圧縮（compact）のあとは、スキルの先頭部分だけが残ることがある（公式）
500行未満：超えたら reference に分ける（第4回の「段階的開示：SKILL.md は目次」）

補足：出典は https://code.claude.com/docs/ja/skills （Skill content lifecycle）と https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices （以下、Platform のベストプラクティス）です。

公式の Skills のページは、圧縮のあとのことを具体的に書いています。自動の圧縮（auto-compaction）では、Claude Code は呼び出したスキルの最新の1回分を、要約の後に付け直します。付け直すのは、各スキルの最初の5,000トークンまでです。付け直したスキルは合計25,000トークンの予算を分け合い、最近呼び出したスキルから順に詰めるので、1つのセッションでたくさんのスキルを呼ぶと、古いスキルは圧縮のあとに完全に落ちることがあります。だから、大事な指示は SKILL.md の先頭近くに書きます。また、公式のトラブルシュートは、途中から従わなくなったときは、もう一度スキルを呼び出すと全文が戻る、と書いています。

500行未満の目安は、公式の Skills のページ・Platform のベストプラクティス・仕様（agentskills.io）の3つが書いています（「SKILL.md は500行未満に。詳しい資料は別のファイルへ」）。Platform は、「この段落はトークンのコストに見合うか」を自問するよう勧めています。

作って確かめる

手順	すること	注意
①作る	フォルダーと SKILL.md を作る（Claude に作らせてもよい）	`.claude/skills` も保護されたパスで確認が出る（公式）。出る選択肢は下の補足を参照（Code タブの画面は確かめていない）
②反映	新しいセッションを始める	公式は再起動なし、動画は必ず再起動。Code タブは確かめていない
③一覧	「利用可能なスキルは？」と聞く	出ないときは第9回の「症状別チェックリスト」で点検
④発動	普段の言い方で頼む（「検証して」など）	発動したか、手順どおり動いたかを見る
⑤確認の画面	確認が出たら内容を読んで選ぶ	出るかどうかは、第1回の「読み込みの3段階」の最後の段落を参照（Code タブの画面は確かめていない）

補足：出典は、Academy のレッスン2・6と https://code.claude.com/docs/ja/skills です。Claude にスキルを作らせるときも、作られた SKILL.md を読んでから使います。

①の保護されたパス：.claude/ の下への書き込みは、「手動」でも「編集を受け入れる」でも確認になります。公式の permission-modes のページは、permissions.allow のルール（たとえば Edit(.claude/**)）は、保護されたパスへの書き込みを事前承認しないと書いています。確認の画面には、そのセッションの間だけ .claude フォルダーの編集を許す選択肢が出ることがあります（公式の文言は「Yes, and allow Claude to edit files in this project’s .claude folder for this session」）
一覧の確かめ方：公式のトラブルシュートは、「利用可能なスキルは？」（What skills are available?）と聞いて、スキルが出るか確かめるよう書いています。/skills で一覧とトークン数を見ることもできます（Code タブで使えるかは、公式に記述が見つからず、筆者は確かめていません）

筆者が試したら

CLI の claude -p（非対話。Claude Code 2.1.289、モードは「手動」、モデルは既定）で、Claude に ansible-verify のスキルを作らせました。-p では、確認の画面が出る操作は「承認が要る」として止まります（画面なら確認が出る所です）。

作成：.claude/skills/ansible-verify/SKILL.md への書き込みは、「手動」でも「編集を受け入れる」でも承認待ちになりました。.claude/skills への書き込みを allow のルールに足しても、承認待ちのままでした（allow を足して試したのは、第11回の手順5です）
一覧：新しいセッションで「利用可能なスキルは？」と聞くと、「このプロジェクト専用」の見出しの下に、ansible-verify が名前と説明つきで出ました。/skills は -p では使えませんでした
反映：-p は毎回新しいセッションなので、同じセッションの中での反映は確かめていません

くわしい手順と結果は、第10回の手順1・2で扱います。

更新と削除

更新：SKILL.md を編集する
削除：スキルのフォルダーを消す
反映のタイミング：公式は、編集を同じセッションで拾い、再起動は要らないと書く（詳しくは下の補足）。動画は「必ず再起動」。Code タブでの動きは、筆者は確かめていない
変更は差分を見てコミット：ほかのファイルと同じ（実践入門第4回「間違いはCLAUDE.mdのバグとして直す」）
Git で共有しているスキル：変更はレビューを通してから取り込む（第8回の「チームで使うときの運用ルール（筆者の例）」）

補足：出典は https://code.claude.com/docs/ja/skills と Academy のレッスン2です。公式と動画の言い方が違うので、迷ったら新しいセッションで確かめてください。

公式の文言は、次のとおりです。「~/.claude/skills/、プロジェクトの .claude/skills/、--add-dir で渡したディレクトリの .claude/skills/ の下のスキルを追加・編集・削除すると、Claude Code は再起動なしで、現在のセッションの中でその変更を拾う」。ただし、次の2点に注意してください。

変更の検知の対象は、SKILL.md の本文だけと書かれています。frontmatter や補助のファイルの変更が拾われるかは、この文には書かれていません
セッションの開始時にまだ無かったトップレベルの skills ディレクトリを作ったときは、Claude Code はまだそこを監視していないので、/reload-skills で読み込みます。その後の変更のたびにも /reload-skills が要ります

スキルを削除すると、公式によると、Claude Code は現在のセッションの /skills からも外します。すでに会話に読み込んだ内容は、前の節（本文の書き方）のライフサイクルに従って残ります。

考えてみよう

自分の作業で、スキルにしたい手順を1つ選んでください。個人のスキルとプロジェクトのスキルの、どちらに置きますか。理由も考えてください
その手順を SKILL.md にするとき、frontmatter の name・description に何を書きますか。本文の最初の3行は、どう書きますか
「本番には流さない」「結果を見せたら止まる」を、本文のどこに書きますか。大事な指示を先頭に書くのは、なぜでしたか

ヒント：1は「スキルの置き場所」の節、2は「frontmatter のフィールド」と「SKILL.md の形」の節、3は「本文の書き方」の節（圧縮のあとの付け直し）を見直してください。

まとめ

置き場所は、個人（~/.claude/skills/、自分のすべてのプロジェクト）とプロジェクト（.claude/skills/、コミットすればチーム全員）が基本。プラグインは /plugin名:スキル名。個人のスキルは Cowork・クラウドのセッションでは読まれない
SKILL.md は、frontmatter（name・description）と本文の2つの部分。ファイル名は大文字の SKILL.md。名前を付けたフォルダーの中に置く
公式は、フィールドは「すべて任意、description だけ推奨」。筆者の例は、name をフォルダー名と同じにし、description を必ず書く。model はそのターンだけ、disable-model-invocation: true は副作用のある作業向け
本文は、番号付きで確かめられる形に、全体に当てはまる言い方に、完了と報告を、してはいけないことと止まる所を、大事な指示は先頭に、500行未満に
作って確かめるのは、①作る ②反映 ③一覧 ④発動 ⑤確認の画面。.claude/skills への書き込みは保護されたパスで、確認が出る
更新は SKILL.md の編集、削除はフォルダーを消す。公式は再起動なしで拾うと書き、動画は再起動を勧める。迷ったら新しいセッションで確かめる

次回は、Claude が発動する説明の書き方を扱います。description に何を書くか、頼み方の言い回し、言い回しを変えて試す方法、似たスキルの分け方と名前です。

連載「Claude Codeスキル入門」全12回

全回の目次と、読む順番・目的別の読み方は、Claude Codeスキル入門の入口のページにまとめています。

スキルとは何か
SKILL.mdを書く（この記事）
発動する説明を書く
複数のファイルに分ける
スクリプトとallowed-tools
検証スキルを作る（前編）
検証スキルを作る（後編）
Gitでチームに共有する
うまく動かないとき
演習（前編）：作る・確かめる・発動させる
演習（中編）：分ける・事前承認
演習（後編）：共有と振り返り

【Claude Codeスキル入門第2回】SKILL.mdを書く ― 置き場所、frontmatterのフィールド、本文の書き方、作って確かめる手順、更新と削除