YAML Frontmatter（ヤムル・フロントマター）

自分でスキル（SKILL.md）を作ってみたいが、先頭の --- で囲む設定欄に何を書けばいいか分からない人向け

スキルを自分で作ろうと公式の手順を開くと、最初に出てくるのが SKILL.md の先頭。--- で囲まれた数行を書け、と言われます。ここで多くの人の手が止まります。何を書けばスキルが動くのか、どの行が必須でどの行が飾りなのか、見ただけでは分からないからです。

この --- で囲まれた設定欄が YAML frontmatter です。スキルの「いつ使うか・誰が呼べるか・何を許すか」を、Claude に伝える名札の役割を持ちます。

噛み砕くと、スキルの「名札と取扱説明の表紙」です

新しい職場に道具箱が1つ増えたと考えてみます。箱の中身（=スキル本体の指示文）を全部読まなくても、表紙のラベルさえあれば「これは何の道具で、どんなときに開けばいいか」が分かりますよね。

YAML frontmatter はその表紙ラベルです。Claude はセッション中、全スキルの中身を丸ごと覚えているわけではありません。覚えているのはこのラベル部分（とくに description）だけ。「レシピの体裁を整えて」と言われた瞬間、ラベルを見比べて「あ、この道具だ」と箱を開けます。

だからラベルの書き方ひとつで、呼ばれるか・スルーされるかが変わります。ここが地味に効きます。

大事な前提：設定欄に書ける項目は全部「任意」、ただし1つだけ実質必須

公式は frontmatter について、こう言い切っています。

All fields are optional. Only description is recommended so Claude knows when to use the skill.

全項目が無くてもエラーにはなりません。極端な話、設定欄を空っぽにしてもスキルは作れます。ただそれだと、Claude が「いつこの道具を開けばいいか」を判断できません。

なので実務では description の1行だけは必ず書く、と覚えておけば十分です。残りは「必要になったら足す」でいい。最初から15項目すべてを埋めようとしないこと。

書ける項目は全15種類（公式リファレンス全項目）

公式が定めている設定項目は全部で15個あります。代表だけ抜き出すと全体像を見誤るので、1つも省かず並べます。普段使うのは上の3〜4個で、残りは「こういう調整もできる」の引き出しです。

15個あっても、毎回触るのは name と description、たまに disable-model-invocation と allowed-tools。あとは「呼ばれ方を細かく調整したくなったら見にくる表」くらいの距離感でいいです。

「料理レシピ投稿サイト」のスキルで、設定欄を1行ずつ埋めてみる

料理レシピ投稿サイトを運営していて、投稿されたレシピの見出し・分量表記・手順番号がバラバラだとします。「材料」と書く人もいれば「使うもの」と書く人もいる。これを毎回手で直すのが面倒なので、体裁を整えるスキル recipe-formatter を作る前提で進めます。

ステップ1: スキルの置き場所を作る

まずスキル用のフォルダを1つ作ります。自分のどのプロジェクトからでも呼べる、個人用の置き場所に置きます。

$ mkdir -p ~/.claude/skills/recipe-formatter

このフォルダ名 recipe-formatter が、そのまま呼び出しコマンド /recipe-formatter になります。

ステップ2: SKILL.md を開いて、設定欄の枠だけ置く

そのフォルダに SKILL.md を作り、先頭に --- を2行置いて、設定欄の枠を作ります。この内側に項目を足していきます。

---

---

ここから下にClaudeへの指示文を書く

ステップ3: name と description を入れる（ここが本番）

名札になる2行を入れます。description が、このスキルが呼ばれるかどうかを決める一番大事な行です。

---
name: recipe-formatter
description: レシピ記事の見出し・分量表記・手順番号を統一する
---

一見よさそうですが、これだと弱い。ここで初心者がやりがちな勘違いがあります。「何をするか」だけ書いて満足してしまうこと。Claude が呼ぶか判断するのに必要なのは、「ユーザーがどんなときにそう言うか」の手がかりです。

ステップ4: description にきっかけの言葉を足す

「統一する」だけだと、ユーザーが「体裁を整えて」「フォーマット直して」と言ったときに反応しないことがあります。公式もトラブル対処でこう書いています。

Skill not triggering → Check the description includes keywords users would naturally say

そこで、ユーザーが自然に口にする言葉を description に混ぜます。

---
name: recipe-formatter
description: レシピ記事の見出し・分量表記・手順番号を統一する。ユーザーがレシピの体裁を整えたい、フォーマットを直したいと言ったとき使う
---

「体裁を整える」「フォーマットを直す」という言葉を入れた。これだけで発火率が変わります。逆に呼ばれすぎて困るなら、説明をもっと具体的に絞れ、というのが公式の対処です。

ステップ5: 勝手に動いてほしくない作業なら、自動起動を止める

体裁を整えるくらいなら自動で呼ばれて困りませんが、「公開ボタンを押す」「データを書き換える」ような取り返しのつかない作業は、Claude の判断で勝手に走られると怖い。そういうときは1行足して、手動だけにします。

---
name: recipe-formatter
description: レシピ記事の見出し・分量表記・手順番号を統一する
disable-model-invocation: true
---

これで Claude は自動で呼ばなくなり、自分が /recipe-formatter と打ったときだけ動きます。タイミングを自分で握りたい作業向けです。

ステップ6: 毎回の確認をスキップしたいツールを許可する

このスキルが、レシピファイルを読んで中身を探す動きをするとします。実行のたびに「読んでいい？」と確認が出ると面倒です。そこで、このスキルが動いている間だけ確認を省くツールを指定します。

---
name: recipe-formatter
description: レシピ記事の見出し・分量表記・手順番号を統一する
disable-model-invocation: true
allowed-tools: Read Grep
---

レシピ記事の体裁を、次のルールで統一してください。
1. 見出しは「材料」「作り方」に揃える
2. 分量は「大さじ1」「200g」の表記に統一
3. 手順は1から始まる連番をつける

ここまでが、公式が示している最小の設定欄の形そのものです。公式の例も name / description / disable-model-invocation / allowed-tools の4行で、まさにこの構成です。

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---

つまり YAML frontmatter は何をしてくれるのか

• やってくれる: スキルがいつ・誰に呼ばれるか、何を許すかをClaudeに伝える。とくに description でスキルを正しく発火させる
• やってくれない: スキル本体の処理そのものは書けない。実際の作業手順は --- の下の本文に書く。設定欄はあくまで名札
• 意味が薄い場面: description を書かずに設定欄を空にすると、Claude が呼ぶ判断材料を失う。動くけど、ほぼ自動では呼ばれない名無しの道具になる

使いどころ3シナリオ（料理サイト運営で再現）

シナリオ1: 投稿レシピの体裁を毎回そろえたいとき

料理サイトに毎週20件レシピが投稿され、見出しや分量表記がバラバラ。これを手で直すのが苦痛なら、recipe-formatter のように description へ「レシピの体裁を整える、フォーマットを直す」と書いておきます。次から「このレシピ整えて」と言うだけで Claude が箱を開けて整形してくれます。同じ指示を毎回貼り直す手間が消えます。

シナリオ2: 公開直前のチェックだけは手動で走らせたいとき

「公開前チェック」スキルを作って、画像の抜けや材料の単位ミスを点検させるとします。ただし公開作業は自分のタイミングで握りたい。そこで disable-model-invocation: true を足して、Claude が会話の流れで勝手にチェックを走らせないようにします。自分が /publish-check と打った瞬間だけ動く。取り返しのつかない作業はこの形が安心です。

シナリオ3: 特定のファイルを触るときだけ自動で起こしたいとき

レシピは recipes/ フォルダの .md ファイルで管理しているとします。このフォルダのファイルを編集するときだけ整形スキルを起こしたいなら、paths に recipes/*.md と書きます。すると、関係ないトップページのファイルを触っているときには起きず、レシピファイルを開いたときだけ自動で立ち上がります。発火の精度が上がって、邪魔になりません。

初心者が踏みやすい落とし穴

• description を「整える」だけで終わらせる。「何をするか」しか書かないと発火しません。「ユーザーが体裁を整えたい・フォーマットを直したいと言ったとき」のように、人が実際に口にする言葉を入れること。
• name に大文字や日本語を入れる。name は小文字・数字・ハイフンのみ、最大64文字。RecipeFormatter や レシピ整形 は通りません。recipe-formatter の形にします。
• description を長く盛りすぎる。when_to_use と合わせて1,536文字で切り詰められます。後ろに書いた肝心な用途が消えることがあるので、一番大事な用途を先頭に置きます。
• 全15項目を最初から埋めようとする。実質必須は description だけ。残りは必要になってから足す。最初から全部埋めると、かえって意図がぼやけます。
• 取り返しのつかない作業に自動起動を許したまま。公開・送信・削除のような作業は disable-model-invocation: true で手動だけにする。Claude が「準備できてそう」と判断して勝手に走るのを防ぎます。
• 設定欄に本体の処理を書こうとする。整形ルールや手順は --- の下の本文に書きます。設定欄は名札であって、作業内容を書く場所ではありません。
• 名前を付けずにフォルダ名と食い違わせる。name を省くとフォルダ名が名前になります。name を別の文字列にすると混乱のもとなので、付けるならフォルダ名とそろえます。
• 全スキルに共通するルールを frontmatter に書こうとする。コード規約・応答の言語指定・ファイル命名規則など「どのスキルを使っているときも守ってほしい」内容は、そのスキル専用の frontmatter ではなく、プロジェクト全体に効く CLAUDE.md に書きます。frontmatter に書いたルールは、別のスキルには効きません。

書き方

---
name: スキル名（小文字・数字・ハイフンのみ、最大64文字）
description: 何をして、いつ使うか
---

やってみるとこうなる

入力

---
name: recipe-formatter
description: レシピ記事の見出し・分量表記・手順番号を統一する。ユーザーがレシピの体裁を整えたい、フォーマットを直したいと言ったとき使う
disable-model-invocation: true
allowed-tools: Read Grep
---

出力例

上記のSKILL.mdを ~/.claude/skills/recipe-formatter/ に置くと、/recipe-formatter で手動呼び出しできるスキルが1つ増える。description に書いたきっかけの言葉とユーザーの発言が噛み合うと発火する（disable-model-invocation: true を付けた場合は手動のみ）

関連項目

• Progressive Disclosure（プログレッシブ・ディスクロージャー）
• Skills（スキルズ）
• Subagent Types（サブエージェントタイプス）
• Plugins（プラグインズ）
• CLAUDE.md Hierarchy（クロード・エムディー・ハイアラーキー）
• description の書き方（ディスクリプション）

公式ドキュメント

https://code.claude.com/docs/en/skills