導入

朝7時、Claude Codeに「モーニングコーヒー・スキルを実行してください」と入力します。エージェントはカレンダーを確認し、プロジェクト管理ツールから今週のタスクを取得し、四半期目標の進捗率をチェックした上で、今日の一日のスケジュールを提案します。同時に別のウィンドウでは「最近のYouTubeコメントを分析してください」と送信し、さらに別のウィンドウでは「チームの脈拍チェックを実行してください」と送信しました。

3つのエージェントが並列で動作しています。それぞれが異なるスキルを実行中です。これらすべてを入力するのにかかった時間は約1分ですが、手動で行った場合、少なくとも25分はかかっていた作業です。

これがスキル（Skill）の世界です。

スキルとワークフローの関係

前節では、WAT フレームワークにおけるワークフローについて取り上げました。マークダウンで記述された作業指示書であり、エージェントが読み実行する SOP（標準作業手順）です。スキルは、このワークフローと本質的に同じものです。

名称が異なるだけです。「ワークフロー」という言葉が「一度きりの作業の流れ」というニュアンスを与えるのに対し、「スキル」は「繰り返し使用できる熟練した技術」という響きを持ちます。ワークフローにはツールとして Python スクリプトが付随しており、スキルにも Python スクリプトが付随します。ワークフローはマークダウンファイルでしたが、スキルもマークダウンファイルです。構造は同一です。

違いがあるとすれば、スキルには YAML フロンマターが追加される点です。ファイルの先頭に「---」で囲まれた領域があり、その中にスキルの名前（name）と説明（description）が記述されます。このフロンマターにより、エージェントのスキル検索効率が劇的に向上します。エージェントはすべてのスキルファイルの全文を読むわけではありません。

フロンマターの名前と説明だけをざっと確認し、現在の要求に合ったスキルを選択した後、選択されたスキルの本文のみを詳細に読みます。これを「段階的コンテキストローディング」と呼びます。

スキルをワークフローの進化形と捉えることも、同じ概念に対する別の名称と捉えることもできます。重要なのは、どちらも「エージェントに対する自然言語による指示書」であり、人間が読み、人間が修正できる点です。プログラミング言語ではなく、日常言語によってエージェントの行動を定義します。

.claude/skills ディレクトリにスキルファイルを作成する

スキルファイルの物理的な場所は、プロジェクトの .claude/skills/ ディレクトリです。各スキルはサブフォルダで区別され、フォルダ内の skill.md ファイルが核心となります。

[図 12-1] .claude/skills ディレクトリ構造の例

スキルフォルダ内には、skill.md のほか補助ファイルも配置できます。例えば、Python スクリプトを scripts/ フォルダに、参照文書を references/ フォルダに格納するといった方法です。このようにスキル内部にすべての要素を収める方式を、自己完結型（Self-Contained）構造と呼びます。

別の方法もあります。スクリプトや参照ファイルがプロジェクト内の別の場所に存在する場合です。例えば、YouTube 分析スキルの skill.md で ../../references/youtube_channel.md を参照するようパスを指定すれば、ファイルがスキルフォルダの外にあっても問題ありません。エージェントは skill.md に記述されたパスに従って必要なファイルを読み取ります。

これを外部参照（External Reference）構造と呼びます。

どちらの場合でも、核心となる原則は一つです。skill.md 内に正しいパスが記載されていればよいのです。

スキルを初めて作成する際、直接 Markdown ファイルを書くわけではありません。エージェントとの対話を通じて作成します。計画モードで「リサーチスキルを作成してください。Perplexity API を使用し、.env ファイルに API キーの場所も用意してください」と依頼すると、エージェントがフォルダ構造を設計し、skill.md を作成し、必要なスクリプトを生成し、CLAUDE.md を更新して新しいスキルの存在を登録します。

なぜこのプロセスを手動ではなくエージェントに任せるのでしょうか？それは、エージェントがフロントマター形式、ファイルパスのルール、モデルが効率的に処理するテキストの構造といったベストプラクティスを既に知っているからです。ただし、エージェントが常に完璧な構造を作成するわけではありません。YAML フロントマターなしで純粋な Markdown のみでスキルを生成する場合もあります。

そのような場合は、直接フロントマターを追加するか、Anthropic の公式ドキュメント URL をエージェントに提示して「このドキュメントを参考に、ベストプラクティスに沿って作成してください」と指示すればよいのです。

skill.md の推奨長さは 500 行以内です。詳細な参照資料は別ファイルに分離することで、モデルが消費するトークン数を節約できます。

スキル説明書の作成方法

スキルが正しく機能するためには、エージェントがそのスキルを検出できる必要があります。エージェントがユーザーの要求を分析し、数十のスキルの中から適切なものを選ぶ際、説明書（Description）が決定的な役割を果たします。

段階的コンテキスト読み込みの第一段階では、エージェントは各スキルの名前と説明書のみを読み取ります。この段階で消費されるトークン数はスキルあたり約 100 個程度です。説明書が曖昧だと、エージェントが誤ったスキルを選択したり、適切なスキルを見逃したりする可能性があります。

優れた説明書には、以下の三つの条件が必要です。

トリガーとなる状況を明示します。「ユーザーが一日の計画を立てる際や、モーニングコーヒーと言った際にこのスキルが呼び出される」ように、このスキルが呼び出されるべき具体的な状況を記述します。これは、エージェントがユーザーの自然言語によるリクエストと説明文を照合して、一致するかどうかを判断するためです。

結果物を明示します。「カレンダー、タスク、目標を総合して、時間ブロックが割り当てられたスケジュール表を出力する」ように、スキル実行の結果物が何であるかを記述します。これは、ユーザーの期待と一致しているかどうかをエージェントが確認するための根拠となります。

範囲を限定します。「このスキルはスケジュール計画のみを扱い、コンテンツ作成やリサーチは含まない」ように境界を設定します。これは、類似したスキルが複数存在する際に、エージェントが混乱しないように支援するためです。

[図 12-2] 段階的コンテキストローディングの 3 つの段階：フロントマタースキャン → スキル本文の読み込み → 参照ファイルの読み込み

スキルの呼び出し方法は二つあります。第一に、スラッシュコマンドです。「/morning-coffee」と入力すると、該当するスキルが即座に実行されます。第二に、自然言語です。「今日一日の計画を立てて」と話しかけると、エージェントが説明文を検索してモーニングコーヒーのスキルを見つけ出します。

スラッシュコマンドは高速かつ正確です。解釈プロセスがないため、即座に実行されます。自然言語は柔軟です。スキル名を知らなくても、意図を伝えるだけで十分です。通常は両方を有効にしますが、スキルが意図せず頻繁に呼び出される場合は、YAMLのフロントマターに disable_model_invocation: true を設定して自然言語トリガーを無効化し、スラッシュコマンドでのみ呼び出せるように制限できます。

スキルが呼び出されない問題が発生した場合、その原因の多くは説明文にあります。「有用なスキル」のような抽象的な説明では、どのようなリクエストとも一致しません。「ユーザーがインフォグラフィックの作成を依頼したり、視覚的コンテンツが必要になったりした際に、Krea AIのNano Bananaモデルを呼び出して、ブランドガイドラインに準拠したPNG画像を生成する」のように具体的に記述するほど、精度は向上します。

GitHubにコミットしてチームと共有する

スキルが .claude/skills/ フォルダに存在する限り、そのスキルは該当プロジェクト内でのみ有効です。プロジェクトフォルダをGitHubにプッシュすれば、チームのメンバー誰でもこのリポジトリをクローンして、同じスキルを利用できるようになります。

これが意味するところを考えてみましょう。ある一人がリサーチスキルを作成し、数十回にわたって繰り返し実行しながら洗練させてきました。プロンプトを調整し、出力形式を改善し、不要なAPI呼び出しを減らすための最適化を施しました。その成果物をGitHubにコミットする瞬間、チーム全員が同じ品質のリサーチを遂行できるようになります。一人の学習曲線が、チーム全体の能力へと転換されるのです。

コミットと共有の手順は簡単です。プロジェクトで「git init」を実行して Git リポジトリを初期化するか、エージェントに「このプロジェクトを GitHub にアップロードしてください」と依頼します。エージェントがリポジトリを作成し、コミットしてプッシュします。その後、スキルを修正するたびにコミットを残せば、バージョン管理が自動的に実行されます。どのバージョンのスキルが優れているかを比較でき、問題が発生した場合は以前のバージョンに戻すことも可能です。

[図 12-3] スキルの共有フロー：個人作成 → Git コミット → GitHub プッシュ → チームメンバーによるクローン

スキルの保存場所については、もう一つの選択肢があります。それは「プロジェクト用スキル」と「グローバルスキル」の区別です。

プロジェクト用スキルは「.claude/skills/」ディレクトリに配置され、そのプロジェクト内でのみ機能します。チームメンバーと共有可能です。フロントエンドのデザインスキルが特定の Web 開発プロジェクトでのみ必要であれば、プロジェクト用スキルとして保存するのが適切です。

グローバルスキルはホームディレクトリの「~/.claude/skills/」に配置され、どのプロジェクトを開いても使用可能です。ただし、チームメンバーとは共有されません。個人専用のスキルや、すべてのプロジェクトで共通して使用されるスキルがこれに該当します。フロントエンドのデザインスキルがあらゆるプロジェクトで必要であれば、グローバルに保存する方が便利です。

スキルの真の価値は、完成したスキルそのものにあるのではありません。フィードバック・ループにあります。スキルを実行し、エージェントの作業過程を観察し、「この部分は不要な API 呼び出しだった」「出力形式が気に入らない」といった修正意見を伝え、エージェントが skill.md を修正します。

この循環を十回、二十回と繰り返すうちに、最初はぎこちなかったスキルが、自らの業務スタイルにぴったりの道具へと変貌します。エージェントに最初から完璧なスキルを期待するのは非現実的です。完璧さは反復から生まれます。

スキルの最適化過程で見出されるパターンがあります。エージェントが毎回同じデータを検索して時間を浪費するなら、頻繁に参照する ID やパスを skill.md にハードコードします。エージェントが一度に読み込む範囲を過度に消費するなら、重い処理を補助エージェントに委譲するようスキルに指示を追加します。

エージェントが外部 API ドキュメントを毎回検索するなら、そのドキュメントをウェブ情報収集して参照用マークダウンファイルとして保存します。マークダウンファイルを読むことは、API ドキュメントをクロールするよりもはるかに高速で低コストです。

これらすべての最適化の方向性は一つです。スキルを実行した後に他の作業を行い、10 分後に戻って完成した結果を確認する。その境地に達すれば、一人が四つのエージェントを同時に操り、一日分の業務を午前中に完了させる光景が、非現実的な夢ではなく日常となります。

そして、これらのスキルが相互に連携し、補助エージェントが互いを呼び出し、外部サービスが MCP を介してエージェントと対話し始めると、個人用アシスタントの域を超えた何かが生まれます。