【ITニュース解説】How to Build a Claude Code Skill That Loads Itself (5-Minute SKILL.md Setup)

システムエンジニアを目指す初心者にとって、AIアシスタント「Claude Code」を使った開発作業を効率化する「スキル」という概念は非常に役立つ。このスキルは、開発作業中に繰り返し行うタスクや、チームで共有すべき共通の知識をClaude Codeに自動的に学習させる仕組みである。例えば、新しい開発セッションが始まるたびに、コードレビューのチェックリストやチームのAPI規約、リリースプロセスなどをClaude Codeに毎回説明し直す手間を省ける。スキルを設定しておけば、AIが一般的な回答に頼ることなく、常に設定されたルールや知識に基づいて最適なアシストを提供してくれる。

スキルは、SKILL.mdという名前のファイル一つを格納するフォルダとして作成される。このファイルに、Claude Codeに教えたい特定のタスクや知識を記述する。Claude Codeは、このSKILL.mdファイルの内容を読み込み、ユーザーの質問や指示に関連すると判断した場合に、手動で呼び出すことなく自動的にそのスキルを適用する。これにより、繰り返し同じ指示を出す必要がなくなり、開発プロセスがスムーズになる。この記事では、このスキルを約5分で作成する具体的な方法が説明されている。

スキルには主に二つの種類がある。一つは「個人用スキル」で、ユーザーのホームディレクトリに保存され、そのユーザーがどのプロジェクトを開いても適用される。もう一つは「プロジェクト用スキル」で、特定のプロジェクトのルートディレクトリに保存され、そのプロジェクトで作業するすべての開発者に適用される。チーム全体で守るべきAPI規約などにはプロジェクト用スキルが適しており、個人の開発習慣やよく使うコマンドなどには個人用スキルが適している。

スキルを手動で作成する基本的な手順は次の通りだ。まず、スキル専用のフォルダを作成し、その中にSKILL.mdというファイルを作成する。例えば、API規約に関するスキルであれば、~/.claude/skills/api-conventionsというフォルダを作り、その中にSKILL.mdを配置する。

次に、作成したSKILL.mdファイルに内容を記述する。ファイルの冒頭には「フロントマター」と呼ばれる設定ブロックを記述する。これは三つのハイフン（---）で始まり、三つのハイフンで終わるYAML形式のブロックで、スキルの名前（name）と、Claude Codeが自動でスキルを適用するかどうかを判断するための説明文（description）が含まれる。特にdescriptionは重要で、ユーザーが普段どのようにそのタスクを依頼するか、自然な言葉で具体的に記述することが推奨される。例えば、「APIの設計規約」ではなく「私たちのサービスのREST API設計規約」といった表現が望ましい。フロントマターの下には、実際にClaude Codeが従うべき具体的な命令文や知識を記述する。例えば、URLパスはケバブケースを使用する、JSONプロパティはキャメルケースを使用するといった具体的な規約を箇条書きで示せる。

オプションとして、フロントマターにdisable-model-invocation: trueを設定すると、スキルは自動適用されず、ユーザーが/スキル名（例: /api-conventions）のように明示的に呼び出したときのみ動作するようになる。また、allowed-toolsというフィールドを使って、スキルが有効なときにClaude Codeが使用できるツールを制限することも可能だ。

スキルを作成したら、正しく動作するかテストする。Claude Codeのセッションを開始または再起動し、スキルのdescriptionに合致するような質問をしてみる。例えば、API規約に関するスキルであれば、「APIの設計規約について教えて」といった質問をすると、Claude Codeがスキルを自動で読み込み、その内容に基づいて回答するはずだ。強制的にスキルを呼び出したい場合は、/スキル名と入力する方法もある。

スキル作成のプロセスは、Claude Code自身に任せることも可能だ。特定のプロンプトを与えることで、AIがスキルに関する質問を投げかけ、その回答に基づいてフォルダ作成、SKILL.mdファイルの書き込み、さらには作成されたファイルが正しく解析できるかの検証までを自動で行ってくれる。これにより、手動での設定作業を大幅に削減できる。

スキルのインストールが正しく行われたかを確認するには、ターミナルでlsコマンドを使ってSKILL.mdファイルが存在することを確認し、claude plugin validateコマンドを実行してフロントマターが正しく解析されているかを検証する。この検証は非常に重要で、たとえ手動でスキルを呼び出せたとしても、フロントマターにエラーがあると自動適用が機能しない場合があるため、必ず行うべきだ。Claude Codeセッション内で「利用可能なスキルは？」と尋ねることで、登録されているスキルの一覧を確認することもできる。

スキル作成時によくある間違いとして、フロントマターの開始を示す三つのハイフン（---）がファイルの最初の行にない場合、フロントマターが正しく解析されないことが挙げられる。また、descriptionが曖昧すぎると、Claude Codeがスキルを自動適用する機会が減ってしまう。一つのフォルダに複数のSKILL.mdファイルを配置することも誤りであり、各スキルは専用のフォルダに収める必要がある。プロジェクトのサブディレクトリに配置されたスキルが自動でロードされないことや、手動での呼び出しが成功したからといって、自動適用も問題なく動作すると過信するのも間違いである。必ずclaude plugin validateコマンドで検証することが推奨される。

スキルは、Claude Codeセッションを次回開始する際に自動的に読み込まれるため、毎回手動で再起動する必要はない。また、スキルはデフォルトでセッション内の他のツールと同じツールアクセス権を持つため、必要に応じて他のツールを呼び出すことも可能だ。スキルとスラッシュコマンドの主な違いは、スキルがdescriptionに基づいて自動的にトリガーされうる点に対し、スラッシュコマンドはユーザーが明示的に入力した場合のみ実行される点にある。プロジェクト用スキルをリポジトリにコミットすることで、チームメンバーと簡単にスキルを共有し、チーム全体の開発プロセスを標準化することも可能だ。

このスキル機能は、開発者が日常的に直面する繰り返しの作業をAIに任せ、より本質的な開発業務に集中できるようにするための強力なツールである。適切にスキルを活用することで、開発効率を大幅に向上させることができる。