スキルの段階的な読み込み

• スキルは SKILL.md を置いたディレクトリで、起動時は説明だけを読み、呼び出されると本文を読む
• description と when_to_use の合計は、スキル一覧で 1,536 字に切り詰められる
• SKILL.md は 500 行未満に抑え、詳しい資料は別ファイルに分けることが勧められている

スキルとは

Claude Code Docs のスキルのページによると、スキルは SKILL.md を置いたディレクトリです。先頭に YAML のフロントマターを置き、続けて Markdown で指示を書きます。

置き場所は、個人の ~/.claude/skills/、プロジェクトの .claude/skills/、プラグインの skills/ です。/スキル名 で直接呼べます。

段階的な読み込み

同じページによると、起動時は説明だけを読み、呼び出されると本文を読みます。補助ファイルは、必要になったときだけ読みます。

Anthropic のエンジニアリング記事（2025 年 10 月 16 日公開）にも、同じ流れの説明があります。起動時は name と description だけを読み、関連すると判断したら SKILL.md の全文を、さらに必要なら追加ファイルを読みます。この記事は、利点として次の 2 つを挙げています。

• 必要な情報だけを文脈に載せて節約できる
• スクリプトで決まった処理を再現性よく動かせる

含められるのは、指示文、Python などの実行できるスクリプト、参照用のファイルです。

書くときの数字

スキルのページによると、フロントマターの項目は全部任意で、推奨されているのは description です。description と when_to_use の合計は、スキル一覧では 1,536 字で切り詰められます。また、SKILL.md は 500 行未満に抑え、詳しい資料は別ファイルに分けることが勧められています。

なお、エンジニアリング記事は name と description を読むと書き、スキルのページは項目が任意だと書いています。食い違いなのか、見ている粒度の違いなのかは、2 つの情報源からは確かめられません。

対応環境

エンジニアリング記事によると、対応環境は Claude.ai、Claude Code、Agent SDK、Claude Developer Platform です。同じページには、2025 年 12 月 18 日にオープンな標準として公開された、ともあります。

試し方の考え方

ここからは Ruleru の推測です。

• 一覧で切り詰められても意味が通るように、大事な言葉を description の先頭に置く
• 最初は 1 つの作業に絞り、description を丁寧に書いたスキルを 1 つ作る
• 読まれ方を見てから、本文や補助ファイルを足す。本文が長くなったら、別ファイルに分ける

仕様は更新されるため、実際に書く前に最新の公式ドキュメントを確認してください。