YAML Frontmatter

YAMLフロントマターとは何ですか？通常のファイル内容とどう違いますか？

YAMLフロントマターは、Markdownファイルの最も先頭に置かれる独立したブロックで、一対の---マーカーで囲まれ、名前・説明・バージョン・ライセンスなど、そのファイルに関するメタデータをYAML形式で記述する。ファイル本体との違いは、本体が読者（あるいはClaude）が読んで理解するための実質的な内容であるのに対し、フロントマターは「この内容は何であるか」を示す構造化されたラベルであり、通常はユーザーに直接表示されず、システムがインデックス作成、フィルタリング、あるいはファイルを読み込むかどうかの判断に使う点にある。

ClaudeCodeのSkillファイルでは、冒頭の---がファイルの本当に最初の行である場合にのみフロントマターが正しく解析される。それより前に他のテキストがあると、ファイル全体がフロントマターを持たないものとして扱われ、すべての内容が通常の説明文として処理される。

YAMLフロントマターはなぜ存在するのですか？どんな問題を解決していますか？

フロントマターがなければ、システムがあるファイルが「何であるか」を判断する唯一の方法は、内容全体を読み込んで分析することになる——ファイル数が少なければ許容できるが、システムが同時に数十個のSkillを搭載している場合、起動のたびに各Skillの完全な内容を読んで関連性を判断していては、大量の不要なコンテキスト空間を消費してしまう。

フロントマターが解決するのはまさにこの問題だ。「これは何で、いつ使うべきか」を数十トークンのメタデータに凝縮することで、システムは起動段階でこの小さなブロックを読むだけで初期判断ができ、実際にあるSkillが必要になったときにのみ完全な本体を読み込む。これがSkillアーキテクチャで言うところの3層段階的開示の第1層にあたる——メタデータは常に読み込まれ、本体はトリガー時に読み込まれ、拡張ファイルは実際に必要なときにのみ読み込まれる。

YAMLフロントマターは実際にはどのように動作しますか？

ClaudeCodeのSkill標準では、フロントマターで公式標準が認識するフィールドは実質6つしかない。必須のname（小文字、ハイフン区切り）とdescription（このSkillが何をし、いつ使うべきかを説明する）、そして任意のlicense、compatibility、metadata、allowed-toolsだ。ClaudeCodeは起動時に各Skillのnameとdescriptionのみを読み込む。このステップで消費されるトークン数は極めて小さく、大量のSkillを同時に搭載していても目立った負担にはならない。

注目すべきは、descriptionフィールドが他のどのフィールドよりもはるかに重要だという点だ。これはシステムがあるSkillをトリガーするかどうかを判断する唯一の照合基準であり、記述が十分具体的でなければ、本体の内容がどれほど完璧であっても、Claudeは関連性を判断できずそのSkillを一度もトリガーしないことがある。これが、多くのオーサリングガイドが同じ点を強調する理由でもある——フロントマターで最も磨き込む価値があるのは、多くの場合フィールドの数ではなく、このdescriptionという一文がどれだけ的確に書かれているかだ。

YAMLフロントマターの動作ロジックを理解することは、実際にSkillを書く際にどう影響しますか？

最も直接的な影響は執筆の順序だ。まずdescriptionを的確に仕上げる——Claudeがひと目で「このリクエストは自分をトリガーすべきか」を判断できるほど具体的にする——そのうえで本体に何を書くかを考えるべきであり、その逆ではない。多くの初心者は本体をどれだけ詳細に書くかに力を注ぎがちだが、descriptionの判断精度が低ければClaudeはそもそも本体を読む段階にすら到達せず、本体をどれだけ丁寧に書いても活躍の場がないという点を見落としている。

もう一つ実務上陥りやすい落とし穴は、冒頭の---マーカーの位置を誤ることだ。例えばその前に空行やコメントを一行余分に入れてしまうと、フロントマターの解析が失敗し、ファイル全体がプレーンな内容として扱われてしまう。この場合、Skillは通常わかりやすいエラーを出さず、静かに機能しなくなる（認識されるnameがない状態になる）。Skillを書き終えたら、フォーマットを目視で確認するだけでなく、実際にClaudeが正しい状況でトリガーするかテストしてみることが望ましい。