こんにちは、Lenaです。最初に SKILL.md ファイルを設定したとき、少しだけ違和感がありました。間違っているわけではないけれど、思っていたものとは少し違ったんです。手順は読み、正しいディレクトリに置き、Claude もそれを認識しました。でもそのあとで、私は考え込みました。いったい私は何を与えたのだろう、と。知識なのか。習慣なのか。ほかへ引き継げる何かなのか。
私はこの問いを、しばらく抱えたままにしてきました。以下は、その中で見えてきた観察です。
Claude Skills とは何か
Claude Skills は、Claude エージェントにドメイン固有の指示、文脈、必要に応じたスクリプトを与えるための、モジュール化された再利用可能な能力バンドルです。フォルダとして整理され、その中心には SKILL.md ファイルがあります。
Claude Code や Claude API で何かを作っているなら、このパターンにはすでに触れているか、近いうちに触れることになるはずです。
SKILL.md の仕組み
各スキルは 1 つのディレクトリに収まります。その中にある SKILL.md ファイルは、上部の YAML frontmatter ブロックと、その下の Markdown 本文という 2 つの部分でできています。
frontmatter は最小限です。そこには、スキル名と、いつ使うべきかが書かれます。Claude は起動時にこの短い description を読みます。実際の指示が書かれるのは Markdown 本文のほうです。何をするか、どんな出力形式にするか、どのエッジケースに注意するか、どの補助ファイルを読み込むか。そうした実装の中身はここにあります。
起動時、エージェントはインストール済みスキルすべての名前と description だけを system prompt に事前ロードします。このメタデータは、段階的開示の最初の層です。各スキルをいつ使うべきかを Claude が判断するのに必要な分だけを与え、内容すべてを最初から文脈に載せることはしません。
この部分は、本当によく考えられていると感じました。Claude は最初からスキル全文を読むのではなく、frontmatter だけを見ます。スキルが関係しそうだと判断したときにだけ、詳細を読み込みます。だから、多くのスキルをインストールしても、常にコンテキストウィンドウを消費し続けることにはなりません。
どんな振る舞いをエンコードできるか
実際、かなり幅があります。スキルには次のようなものを持たせられます。
- 手順ベースの指示 — 特定のファイル種別、レビューの流れ、出力形式をどう扱うか
- ドメイン規約 — 命名基準、プロジェクト固有のルール、推奨ライブラリ
- 補助ファイル — テンプレート、出力例、Claude が実行できる Python スクリプト
- 条件付きサブドキュメント — Claude が関連ありと判断したときだけ読み込む、より深い参照資料
スキルは、Claude に問題を直接解かせるものではなく、問題を解ける状態に整えるものです。結果を返す従来のツールとは、ここが根本的に違います。
この違いは私にはかなり重要に思えました。スキルは実行されません。指示を与えるだけです。推論するのはあくまで Claude です。
Claude Skills の設定と使い方
ファイルの置き場所と形式
全プロジェクトで使う個人用スキルは、個人用の skills ディレクトリに置きます。Git で共有するプロジェクト単位のスキルは、プロジェクト側の skills ディレクトリに置きます。各スキルには専用のサブディレクトリが必要で、その中に SKILL.md ファイルを置きます。
形式そのものはシンプルです。スキルは、YAML frontmatter と指示を含む SKILL.md ファイルを置いた 1 つのフォルダとして作れます。出発点として使える template skill に加え、Claude に組み込まれた PDF、Word、PowerPoint 処理を支える source-available な document creation skills も、Anthropic の公式 skills リポジトリ on GitHub で公開されています。
Claude がスキル指示をどう読み、どう適用するか
スキルがインストールされると、Claude は受け取ったタスクをスキルの description と照らし合わせます。一致しそうなものがあれば、SKILL.md の内容をコンテキストへ読み込み、そこから先はその指示に従って進みます。
スラッシュコマンドで手動呼び出しすることもできますし、タスク文脈に応じて Claude に自動判断させることもできます。内部的には、どちらも同じ仕組みで動いています。
ここで私は少し面白いことに気づきました。Claude はスキルを使うとき、ただ「知っている」のではなく、毎回あらためて読み直しているんです。文書を参照するように。その点には、あとで戻ってきます。
Claude Skills がうまく機能する場面
ドメイン知識とプロジェクト規約
おそらく、いちばん分かりやすく効くのはここです。チームに固有のコーディング標準、好みのデバッグフロー、特定の出力要件があるなら、それをスキルファイルへエンコードしておけば、毎回同じ文脈を繰り返さなくても Claude が一貫して適用してくれます。
私はいくつかのプロジェクトでこれを試しました。一貫性は、CLAUDE.md の指示だけに頼る場合や、毎回プロンプトで同じことを言い直す場合より、目に見えて良くなりました。Claude はスキルを読み、それに従い、出力の形がより予測しやすくなります。
一貫した出力フォーマット
構造化された出力、たとえば技術文書、コードレビュー、API ドキュメントのようなものでは、スキルはフォーマット契約としてうまく機能します。期待する構造を定義しておけば、Claude がそれを読み込み、出力はより安定してその形に寄っていきます。
Claude Code のスキルは、複数の AI ツールで動く Agent Skills オープンスタンダード に準拠しています。Claude Code はその標準を、invocation control、subagent execution、dynamic context injection のような追加機能で拡張しています。
このクロスプラットフォーム互換性は見逃せません。複数のエージェントツールをまたいで構築しているなら、同じ SKILL.md 形式を使い回せます。
Claude Skills の限界が見え始めるところ
ここで、始める前に私が想像していたのとは少し違うものが見えてきました。
静的なファイルと動的な学習
SKILL.md ファイルは、人が書いてディスクへ保存するものです。自分で更新はしません。Claude がスキルを使ってタスクをうまくこなしても、その成功がスキルファイルに自動で戻ることはありません。次のセッションは、同じ静的な文書からまた始まります。
うまくいったやり方や、よくある失敗をスキルへ書き戻すよう Claude に頼むことはできます。けれど それは手動のステップです。 始めるのは人間であって、Claude が自分からやるわけではありません。
それを欠陥だと言いたいわけではありません。どちらかといえば、設計上の境界なのだと思います。
実行フィードバックループがない
Claude がスキルを適用して結果を出しても、そのシグナルがスキル自体へ戻ることはありません。どの指示が効いたのか、どれが無視されたのか、どれが問題を起こしたのか。その記録は残りません。スキルには、使われた記憶がありません。
この点は、エージェントを本番で長く回すほど重くなります。パターンはあなたの頭の中には蓄積されます。でも、ファイルの中には蓄積されません。
Skills はエージェントやチームをまたいで持続しない
Custom Skills は各ユーザー個人のものです。組織全体で共有されるわけではなく、管理者が一元管理することもできません。
つまり、あるチームメンバーが何か月も使ってスキルを磨いても、その改善版が自動でほかのメンバーへ伝播することはない、ということです。ローカルにとどまり、誰かがコピーして、コミットして、共有して、各自が更新しなければなりません。
何かが壊れているわけではありません。ただ、スキルの改善はゆっくり伝わるし、そのスキルを使うエージェントのネットワークが時間とともに自然に収束して、よりよい振る舞いへ近づくこともありません。
静的な Skills から継承可能な能力へ
SKILL.md を超えて、再利用できる検証済み能力とは何か
私はずっと考えています。もしスキルの成功した実行、たとえばあるエージェントが複雑なデバッグ手順をうまく完走したこと自体が、ほかのエージェントへそのまま継承できるものになったらどう見えるのだろう、と。コピーされたファイルではなく、監査証跡を持つ検証済みの解法として。
今のスキルは、どちらかといえばオンボーディング文書に近いです。誰かのその時点での最善の理解をもとに一度書かれ、手作業で配布される。そのモデルは、安定していて、よく理解された領域では十分にうまく機能します。
でも、本番でエージェントを動かしているチーム、失敗し、回復し、適応していくエージェントを扱うチームにとっては、「スキルに書いてあること」と「先週ほんとうに効いたこと」のあいだのズレが、静かに広がっていきます。
自己進化が必要になるとき
エージェントシステムを実際の運用の中で見るほど、私には 難しいのは知識を一度エンコードすることではなく、それを最新のまま保つことだ と思えてきます。スキルはエンコードの問題を解きます。鮮度の問題は、まだ開いたままです。
いま出てきているインフラレベルのアプローチの中には、検証済みのエージェントの振る舞いを共有可能な資産として扱うものがあります。静的なファイルではなく、系譜をたどれる検証済みの解法としてです。それは SKILL.md とは別のアーキテクチャであり、「再利用」とは何か、エージェントが絡むとき信頼をどう考えるべきか、という別の問いを生みます。
その線引きがどこにあるのか、私はまだ完全には分かっていません。
限界とトレードオフ
私が観察してきたことを、はっきり書いておくと。
Claude Skills は本当に役に立ちます。 繰り返しを減らし、一貫性を高め、ドメイン知識をセッション間で持ち運びやすくします。個人開発者や小さなチームにとっては、その場しのぎのプロンプトより一段ちゃんとした改善です。
限界が見えるのは、自己進化し、エージェント間を自動で渡り、実行結果の証拠を蓄積する能力がほしくなったときです。 それは、そもそも SKILL.md が担うよう設計された領域ではありません。
トレードオフはシンプルです。予測可能性か、適応性か。スキルが与えるのは予測可能性です。自分の履歴から学ぶエージェントは、設計上、そこには含まれていません。
FAQ
- Claude Code における SKILL.md ファイルとは何ですか。
SKILL.md ファイルは Claude skill の中核となる要素です。YAML frontmatter を持つ Markdown 文書で、Claude にドメイン固有の指示、文脈、メタデータを与えます。いつそのスキルを適用するか、適用されたときに何をするかを Claude に伝えるものです。スキルは Claude の VM 環境を活用し、単なるプロンプトでは届かない能力まで広げます。
- Claude Skills はどのように動きますか。
Claude は起動時にスキルのメタデータを読み、関連するタスクが来たとき、あるいはスラッシュコマンドで手動呼び出しされたときにだけ、完全な指示を読み込みます。この段階的な読み込みによって、コンテキスト消費は小さく保たれます。スキルディレクトリ内の補助ファイルも、Claude が必要としたタイミングでオンデマンドに読み込まれます。
- Claude Code 用のカスタムスキルはどう作ればいいですか。
プロジェクト内なら .claude/skills/、個人用なら ~/.claude/skills/ の下にディレクトリを作ります。そこへ、name と description を含む YAML frontmatter のあとに Markdown 指示を書く SKILL.md ファイルを置きます。関連すれば、Claude が自動的にスキルを見つけて適用します。テンプレートや実例を見たいなら Anthropic の skills GitHub リポジトリが参考になりますし、設定の全体像は Agent Skills のドキュメントが役立ちます。より技術的に深掘りしたいなら、Anthropic's engineering blog post on Agent Skills は丁寧に読む価値があります。SDK を使っているなら、Agent Skills in the SDK で skill discovery と tool access の仕組みが説明されています。
- Claude Skills は MCP ツールと同じですか。
まったく同じではありません。私自身、ときどき混同しそうになるのですが。MCP (Model Context Protocol) ツール は、Claude が実行時に呼び出す外部能力です。ファイルシステム、データベース、API、各種サービス。実行され、結果を返します。対して Claude Skills は指示的なものです。Claude に新しいツールを与えるのではなく、どう振る舞うか、どうタスクへ向き合うかを教えます。スキルは Claude にコードレビューの進め方を案内できますし、MCP ツールは実際にレビュー対象ファイルを取得できます。両者は併用できますが、解いている問題は別です。片方はアクセスを与え、もう片方は指針を与えます。
- Claude Skills はプロジェクト間で共有できますか。
部分的には共有できます。~/.claude/skills/ に置いたスキルは個人用で、そのマシン上のすべてのプロジェクトに適用されます。プロジェクトディレクトリ内の .claude/skills/ に置いたスキルは、そのプロジェクト専用で Git にコミットできます。つまり、リポジトリをクローンしたチームメンバーは同じスキルを自動的に受け取れます。ただし、それ以上の自動同期や自動伝播は起きません。あるプロジェクトでスキルを改善しても、その改善が勝手にほかへ流れていくことはないのです。共有は手動です。コピーして、コミットして、配る。個人や同じリポジトリで働く小規模チームには十分うまく機能しますが、異なる環境で複数のエージェントワークフローを回す大きな組織では、その摩擦が見え始めます。
この領域がどう変わっていくのか、これからも見ていこうと思います。静的な指示と、自己更新していくエージェント能力のあいだの距離は、ゆっくり、しかも必ずしも分かりやすくはない形で縮まっている気がします。まだ自分でも、どう受け止めるべきかははっきりしていません。では、また。
