【ITニュース解説】Writing effective Claude Code skills

Claude Codeにおける「スキル」とは、開発者が日常的に行う様々なタスクを自動化し、効率化するための機能である。これは単なるコマンド実行に留まらず、複雑な思考プロセスやワークフローをClaudeに実行させるための指示書のようなものだと考えると良い。スキルは基本的に一つのフォルダで構成され、中に「SKILL.md」というファイルが必須となる。このSKILL.mdファイルは、スキルのメタデータ（名前や説明）を記述するYAML形式のヘッダーと、具体的な手順や指示を記述するMarkdown形式の本文を組み合わせたものである。スキルフォルダには、詳細なドキュメントを置く「references/」、実行可能なスクリプトを置く「scripts/」、テンプレートや静的ファイルを置く「assets/」といったオプションのサブフォルダを含めることができる。この構造はAnthropic社が提唱したオープンスタンダードであり、Claude Codeだけでなく、他のエージェント製品でも利用できる。

スキルを効果的に活用するためには、Claudeがスキルをどのように読み込むか、つまり「プログレッシブ・ディスクロージャー（段階的な情報開示）」というメカニズムを理解することが極めて重要である。このメカニズムは3つのレベルに分かれている。 まず「レベル1：検出」では、セッション開始時に全ての有効なスキルの名前と説明文（SKILL.mdのフロントマター部分）のみがシステムプロンプトに注入される。これによりClaudeは、どんなスキルが存在し、どのような場合に適用されるかを知る。この段階で消費されるトークンは、スキル一つあたり約100トークンと非常に少ない。何十ものスキルがあっても、全体で数千トークン程度であり、Claudeの巨大なコンテキストウィンドウから見れば無視できる量である。 次に「レベル2：起動」では、ユーザーの要求が特定のスキルの説明文と一致した場合に、そのSKILL.mdの本文全体がClaudeに読み込まれる。ここに詳細な指示、ステップバイステップのワークフロー、チェックリストなどが記述される。この段階で消費されるトークンは最大で5,000トークン程度である。このため、SKILL.mdの本文は5,000トークン以下に保つべきだ。あまりに本文が長いと、必要ない場合でも数千トークンが無駄に消費され、コンテキストを圧迫してしまう。 そして「レベル3：実行」では、レベル2の指示に基づいて、Claudeが必要な時に限って「references/」フォルダ内のファイルや「scripts/」フォルダ内のスクリプトを読み込み、実行する。これにより、必要な情報だけをオンデマンドで読み込むことで、コンテキストを最大限に効率よく利用できる。

SKILL.mdの具体的な構成において、特に重要なのがYAML形式で記述されるフロントマターである。この中の「description（説明文）」は、Claudeがスキルを起動するかどうかを判断する唯一の手がかりとなるため、スキル全体で最も重要な部分だ。「ルーター」の役割を果たすと言える。名前は小文字とハイフンのみで1〜64文字に制限され、親フォルダ名と完全に一致させる必要がある。また、無効なYAML形式はサイレントにスキル読み込みを失敗させるため注意が必要である。 効果的な説明文には、スキルが「何をするのか」と「いつ使うのか」という2つの要素を明確に含めるべきだ。特に「いつ使うのか」については、ユーザーが口にするであろう具体的なトリガーフレーズを複数、多言語でリストアップすることが重要である。例えば「commit & push」だけでなく、「pousse ca」（フランス語で「それをプッシュして」）のような自然なフレーズも盛り込むことで、スキルの起動率が格段に向上する。 SKILL.mdの本文は、Claudeが従うべきワークフローを記述する。ここでは、詳細な説明や冗長な文章は避け、簡潔かつ明確な手順を示すことが肝要である。Claudeは一般的なプログラミングの知識やツールの使い方をすでに理解しているため、基本的な説明は不要である。ワークフローは箇条書きで分かりやすく記述し、起こりうるエラーとその対処法（エラーハンドリング）も具体的に記述しておくことで、Claudeは予期せぬ問題に遭遇しても適切に対処できるようになる。また、最終的な成果物の形式を指示する出力フォーマットも明確に記述する必要がある。

スキルのデザインには大きく分けて2つの哲学がある。一つは「パターンA：ツールラッパー」である。これは、スキルがCLIツールや決定的なスクリプトの薄いラッパーとして機能するパターンである。具体的なロジックはスクリプト自体にあり、スキルはそれらのスクリプトの実行を調整する役割を担う。例えば、Rustのリンティングを行う「/lint-check」スキルが「cargo fmt」「cargo clippy」などのコマンドの実行を順序立てて行う場合がこれにあたる。 もう一つは「パターンB：コグニティブ・ディシプリン」である。これは、スキルが特定の思考プロセスや方法論をClaudeに実行させるパターンである。スクリプトを実行するのではなく、純粋にプロンプトエンジニアリングによって、エージェントが従うべき「考え方」をコード化する。例えば、5ステップのデバッグ手法を強制する「/systematic-debugging」スキルなどが該当する。

効果的なスキルに共通するパターンはいくつかある。 まず「Bashファースト、散文セカンド」という原則がある。エージェントが直接実行できるコードブロックは、何をすべきかを説明するだけの散文よりも常に優れている。「git statusを実行して未コミットの変更をチェックする」のように簡潔に書く方が、Claudeにとって明確で信頼性が高い。 次に「行動前の状態チェック」は必須である。何かを変更する前に、必ず現在の状態を確認するべきだ。「まずgit statusで作業ツリーがクリーンか確認し、次にgit logで現在のブランチを確認する」といった手順を踏む。 また「検証ループ」も重要である。各アクションを実行した後には、結果が正しいか検証し、次のステップに進む前に確認を行うべきだ。エラーが報告された場合は、修正し、再度実行するなどのループを設ける。 「プリミティブの組み合わせ」という考え方も重要だ。一つのスキルに全てのワークフローを詰め込むべきではない。代わりに、単一機能に特化したシンプルなスキルを複数作成し、それらを組み合わせてより複雑なワークフローを構築する。例えば、開発パイプラインスキルはリンティングの機能を「/lint-check」スキルに、コミットとプッシュの機能を「/commit-push」スキルに任せることで、全体のコード量を減らし、メンテナンス性を向上させる。 最後に「出力フォーマットの明記」も忘れてはならない。エージェントがどのような形式の成果物を生成すべきかを正確に指定する必要がある。「変更されたファイルリスト、テストの合否、Lintの結果詳細、使用されたコミットメッセージを含むサマリーを生成する」といった具体的な指示が求められる。

一方で、避けるべき「アンチパターン」も存在する。 「モデルが知っていることを再教育しない」ことだ。ClaudeはJSONとは何かを知っているため、その定義を説明するような不要な情報はコンテキストトークンの無駄である。 「漠然とした説明文を書かない」こと。曖昧なスキルはほとんどトリガーされないため、具体的で明確な説明文とトリガーフレーズを記述する必要がある。 「巨大なモノリススキルを作らない」こと。一つのスキルは一つの機能に限定すべきである。もしスキルの説明文に2つの独立した行動を示す「and」が含まれるなら、それはおそらく2つのスキルに分けるべきである。 「失敗モードを無視しない」こと。何がうまくいかないか、そしてどう対処するかを文書化しておくべきだ。これを怠ると、コマンドが失敗した際にClaudeは停止するか、独断で解決策を「発明」してしまう可能性がある。 最後に「絶対パスを使用しない」こと。スキルの可搬性を確保するため、スキルディレクトリからの相対パスを使用するべきだ。

最も強力なスキルは、特定のプロジェクトに合わせて調整されたものである。例えば、Netirプロジェクト向けの「/netir-cpm」スキルは、汎用的なコミット・プッシュスキルとは異なり、担当者、レビュアー、ラベルなどのNetirプロジェクト固有のGitLabマージリクエストの慣習をハードコードしている。また、「/netir-qa-swarm」スキルは、アーキテクチャ、セキュリティといった異なる焦点を設定した複数のレビューエージェントを並行して起動させ、それぞれのコードベース固有の慣習に基づいたレビューを行わせることができる。

スキルの開発においては、テストが不可欠である。最も重要なテストは、さまざまな自然なフレーズでスキルがトリガーされるかどうかを確認することだ。ユーザーは厳密なコマンドではなく、「コミットしてプッシュして」といった日常的な言葉を使う。これらの自然なフレーズでスキルが起動しない場合は、説明文の改善が必要である。また、実際のプロジェクトでスキルを実行し、期待通りの結果が得られるかを確認することも重要である。 新しいスキルを公開する前に、いくつかの最終チェック項目がある。スキルの名前がフォルダ名と一致しているか、説明文に多言語のトリガーが含まれているか、SKILL.mdの本文が5,000トークン以下か、詳細な情報は「references/」に移動されているか、失敗モードが文書化されているか、出力フォーマットが指定されているか、機密情報や絶対パスが含まれていないか、破壊的なコマンドはユーザーの確認で保護されているか、そして複数のフレーズで十分にテストされているか、これら全てを確認する必要がある。

これまでの経験から学んだ重要な教訓は、説明文こそがスキルの「ルーター」であるということだ。完璧な指示が含まれていても、曖昧な説明文のスキルは決してトリガーされないため、説明文に本文と同じくらい時間をかけるべきである。また、コードが散文よりも常に優れている。タスクに単一の正しい答えがある場合は、ロジックをMarkdownではなくスクリプトに記述するべきだ。最も安価なコンテキストは、読み込まないコンテキストである。段階的な情報開示の原則を理解し、コンテキストの無駄を省くべきだ。そして、ユーザーはきれいなコマンドを打つとは限らないため、実際のフレーズでテストを行うことが不可欠である。スキルを適切に活用することで、Claude Codeは汎用的なアシスタントから、個々の開発者の具体的なワークフローに完全に適応した強力なツールへと変貌を遂げるのである。