レッスン2: Skill の解剖学: SKILL.md ファイル

学習目標:

• SKILL.md の 2 部構成を理解する
• YAML フロントマターの必須フィールドを把握する
• 実際に機能する description の書き方を学ぶ
• instructions セクションの組み立て方を理解する

前提: << レッスン1 | 次: レッスン3 >>

Skill ファイルの見た目

どの Skill を開いても、同じ形をしています。¹

このファイルは 2 つの部分でできています。

1. YAML フロントマター（--- マーカーで挟まれた部分すべて）: この Skill の基本情報を Claude に伝えるメタデータ
2. Markdown の instructions（それ以降すべて）: Claude が何をすべきかを伝える実際の指示

YAML フロントマター: Claude があなたの Skill を見つける仕組み

フロントマターは、ファイルの一番上にある --- で囲まれたブロックです。ここでは、最も重要な 2 つのことを Claude に伝えます。^{2 3}

name: Skill の一意な識別子

• ルール: 小文字、数字、ハイフンのみ。スペースは使えません。
• 役割: name はそのまま /task-organizer のようなコマンドになります。
• アドバイス: 説明的で、短く、一目で意味がわかる名前にしましょう。

良い名前:

• meeting-notes
• code-review
• changelog-generator

悪い名前:

• my-skill-1（何も伝わらない）
• super_amazing_task_helper（長すぎるうえ、アンダースコアは使えない）
• taskOrganizer（camelCase — 小文字とハイフンにする必要がある）

description: 最も重要なフィールド

この 1 文が、次の 3 つを決めます。⁴

1. Claude がこの Skill を自動的に読み込むかどうか
2. ユーザーが Skill 一覧で目にする内容
3. Claude がこの Skill を何のためのものだと理解するか

だからこそ、ファイルの中の何よりも丁寧に書く価値があります。⁴

"The description is the single most important field in your frontmatter. A bad description means your skill either never triggers or triggers on everything. The formula: What it does + When to use it + Key capabilities."

（description はフロントマターで最も重要なフィールドであり、これがまずいと Skill はまったく発動しないか、何にでも発動してしまいます。公式は「何をするか + いつ使うか + 主な機能」です。）

良い description:

悪い description:

任意フィールド（ここではなくレッスン6で扱います）

• model: 使用するモデルを選ぶ
• allowed-tools: この Skill が触れられるツールを制限する
• version: バージョン番号

最初の Skill には、name と description があれば十分です。³

Markdown の instructions: Claude にやり方を伝える

フロントマターより後ろはすべて、Claude が読んで従うために書かれています。¹

良い instructions には 3 つの共通点があります。

1. 明確なセクション

見出しを使って、パートを分けます。

2. 具体的なステップ

弱い書き方:

強い書き方:

3. 例

出力フォーマットが重要なら、1 つ見せましょう。

例が 1 つあれば、Claude はどう並べればよいかを正確に把握します。説明するより見せるほうが効きます。サンプル出力 1 つは、フォーマットについての 3 段落の説明より多くの仕事をします。

2 つの部分がどう連携するか

フロントマターは発見の仕組み、instructions は実行のガイドです。^{5 6}

1. あなたが /task-organizer と入力する、あるいは単に「このタスクを整理して」と言う
2. Claude がフロントマターの name と description を読み、この Skill を読み込むか判断する
3. 読み込むなら、Claude は instructions 全体を読む
4. Claude は書かれたとおりに手順を進める
5. 出力は、instructions が指定したフォーマットに一致する

だからこそ description が優れていなければならないのです。Claude がこの Skill を使うかどうかを判断するとき、それが唯一の手がかりだからです。⁴

「タスクを手伝う」と書けば、Claude はどんな状況で使えばよいのかわかりません。「散らかった ToDo リストを優先度と期限でグループ分けする」と書けば、リクエストに含まれる「並べ替える」「ToDo」「タスク」といった言葉だけで、この Skill を呼び込むのに十分です。

実例: コードレビュー Skill を分解する

実際に使われている Skill を見てみましょう。

分解してみましょう。

• フロントマターの description: 何をするか（コードをレビューする）と、何をチェックするか（規約、バグ、パフォーマンス）を述べている
• instructions は 3 つのチェックリストに分かれている: 規約、バグ、パフォーマンス。それぞれに見るべき具体的な項目がある
• 出力フォーマットが明示されている: すべての問題に、場所・問題・提案を付けなければならない

このように書かれた Skill は、一発で正しく動きます。

まとめ

• SKILL.md は 2 部構成: YAML フロントマター（メタデータ）と Markdown の instructions（指示）
• 必須のフロントマターフィールド: name（小文字、ハイフン、一意）と description（自動発動を左右する）
• description の公式: 何をするか + いつ使うか + 主な機能
• 良い instructions の 3 つの特徴: 明確なセクション、具体的なステップ、作り込まれた例
• 各部分の噛み合い方: フロントマターで Claude が Skill を見つけ、instructions で Claude がそれを実行する

次のレッスンでは、何もないところから始めて、完全な Skill を最初から最後まで書き上げます。

>> レッスン3: 実践: 最初の Skill を書く

Footnotes

1. Claude Code 公式ドキュメント: Extend Claude Code with skills — https://code.claude.com/docs/en/skills ↩ ↩²

2. Anthropic エンジニアリングブログ: Equipping agents for the real world with Agent Skills — https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills ↩

3. Anthropic ヘルプセンター: How to create custom skills — https://support.claude.com/en/articles/12512198-how-to-create-custom-skills ↩ ↩²

4. Building skills for Claude, ハンズオン: YAML frontmatter とテスト — https://sjramblings.io/building-skills-for-claude-part-2/ ↩ ↩² ↩³

5. Anthropic プラットフォームドキュメント: Agent Skills overview — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview ↩

6. Claude Skills 徹底解説（第一原理の視点） — https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/ ↩