Zilmac ブログ
← 技術実践に戻る

Claude CodeでカスタムSkillsを作成する方法:SKILL.mdの作成、ディレクトリ設定から実際の呼び出しまでの完全チュートリアル

AIDevelopment ·約 12 分で読めます

Skillを作成したのにClaude Codeで見つからない、または意図した手順で動かない。
解決の要点は、仕様に沿ったSKILL.mdを対応ディレクトリへ置き、実際のタスクで認識と呼び出しの両方を確かめることです。ディレクトリやメタデータ、呼び出しの仕様は変更される可能性があるため、作業前にClaude CodeのSkills公式ドキュメントで現行ルールを確認してください。

この記事は、Claude Codeで繰り返し行う作業を再利用可能なSkillにしたい開発者向けです。
個人用とプロジェクト用の置き分けに迷う場合や、AI Agentの作業手順が安定して呼び出されるか確認したい場合にも役立ちます。

Claude CodeのカスタムSkills作成は「検出・実行」で完了

>

作成の完了条件は、次の確認がすべて済んでいることです。

  • SKILL.mdにSkillの用途と実行指示が書かれている。
  • ファイルが、用途に合ったClaude CodeのSkillsディレクトリに置かれている。
  • 明示的な呼び出し、または条件に合う依頼で認識され、出力が指示に沿っている。

ファイルを保存しただけでは、利用可能かどうかは判断できません。ディレクトリ階層やYAMLの書式が正しくても、descriptionが曖昧なら自動選択されないことがあります。公式の仕様と実際の出力を分けて確認すると、原因を絞りやすくなります。

第一歩:用途に合わせてディレクトリを選ぶ

>

Claude Code Skillsは、プロジェクト単位とユーザー単位で配置先を分けられます。プロジェクトの規約や作業手順をチームで共有するならリポジトリ内、個人の複数プロジェクトで使うならユーザー用の場所が候補です。

適用範囲 配置先 選ぶ場面
プロジェクト単位 .claude/skills/<skill-name>/SKILL.md リポジトリと一緒に管理し、プロジェクト固有の手順を共有する
ユーザー単位 ~/.claude/skills/<skill-name>/SKILL.md 個人用の作業手順を複数のプロジェクトで使う

パスはClaude Code公式ドキュメントに記載された標準的な配置例です。Skill名のディレクトリを作り、その中にSKILL.mdを置く構造を確認してください。ファイルを.claude/skills/直下へ置いた場合や、ファイル名の大文字・小文字が異なる場合は、意図したSkillとして認識されない可能性があります。公式の配置先と読み込み規則を参照し、現在の設定で利用できる範囲を照合します。

プロジェクトの共有ルールをすべてSkillへ移す必要はありません。常に参照させるプロジェクト情報と、特定の作業で起動する指示は役割が異なります。前者の整理には公式のプロジェクトメモリ説明も参考になります。

第二歩:SKILL.mdを小さく、条件つきで書く

>

SKILL.mdは、YAML形式のfrontmatterと本文で構成します。frontmatterでは、Skill名のnameと用途を示すdescriptionを中心に設定し、本文に具体的な実行手順を記します。フィールドの仕様や追加項目は更新される可能性があるため、公式のSkills仕様で有効な項目を確認してください。

---
name: review-change
description: 差分のレビューを依頼されたときに、変更点と関連テストを確認する
---

# 変更差分をレビューする

1. 変更されたファイルと差分を確認する。
2. 既存のテストや関連コードを参照する。
3. 再現可能な問題を、対象箇所と理由を添えて報告する。
4. 問題が見つからない場合は、確認した範囲と未確認事項を明記する。

これは説明用の例であり、実環境での結果を保証するものではありません。実際の作業に合わせ、適用条件、参照すべきファイル、出力の形式、作業を止める条件を追加してください。特定のリポジトリに依存する前提を明示すると、別のプロジェクトで誤って適用されるリスクを抑えられます。

descriptionは単なる短いタイトルではなく、自動選択に関わる説明です。「コードを確認する」のような広い表現より、「差分レビューを依頼されたとき、変更点と関連テストを確認する」のように作業と条件を示すほうが意図が伝わります。公開されているSkill作成例も、構成を考える際の参考資料になります。

第三歩:設定を照合してから呼び出す

>

作成したSkillが想定どおりに使えるか、次の順で確認します。

  1. 対象範囲を決めます。 チーム内で共有するならプロジェクト用、個人の作業に限るならユーザー用を選びます。
  2. ディレクトリを作成します。 Skill名のフォルダーを用意し、その中にSKILL.mdを配置します。
  3. frontmatterを点検します。 YAMLの区切り、キーと値の書式、Skill名、descriptionに欠落や記述ミスがないか確認します。
  4. 指示の範囲を整えます。 どの依頼に適用し、何を確認し、どの形式で結果を返すかを本文に書きます。
  5. 明示的に呼び出します。 /review-changeのようにSkill名を指定して実行し、期待する確認項目が出力に反映されるか確かめます。実際に利用できる表記は、現行の公式仕様に照合してください。
  6. 自動選択も別に試します。 Skillのdescriptionに合う依頼を入力し、必要な条件が揃ったときに適用されるか確認します。
  7. 修正後に同じ依頼を再実行します。 変更前後の出力を比べ、意図した指示が反映されたか記録します。

明示的な呼び出しと自動選択は、同じ確認方法ではありません。明示的に実行できるのに自動で選ばれないなら、まずdescriptionと依頼内容の一致を見直します。自動選択を抑止するfrontmatter設定などを使う場合は、その項目の現在の意味もSkills公式説明で確認してください。

確認方法 主に分かること 結果が期待と違う場合
スラッシュコマンドで呼び出す Skillの配置、名前、明示実行の可否 パス、ファイル名、frontmatter、呼び出し名を確認する
条件に合う依頼を入力する descriptionと依頼内容の一致、自動選択の傾向 対象タスクと適用条件をdescriptionに具体化する

テストでは、結果の違いが見える依頼を使います。たとえば差分レビュー用Skillなら、「変更点、関連テスト、確認できなかった項目を分けて報告する」と指示し、出力にそれぞれが含まれるか確認します。成功したように見える文章だけで判断せず、SKILL.mdに書いた確認項目が実際に出ているかを見ます。

自動選択の結果だけで配置の正しさを判断しないでください。説明の曖昧さと読み込みの問題は別の原因なので、明示的な呼び出しも併用すると切り分けやすくなります。

反応しないときは原因別に戻って確認する

>

明示的な実行も自動選択もできない場合は、まずファイルの場所と名前を見直します。次に、SKILL.mdがSkill名のディレクトリ内にあるか、frontmatterの区切りとYAML記法が崩れていないかを確認してください。Claude Codeの設定やバージョンによって挙動が異なる可能性もあるため、公式の設定項目と構成方法を参照し、環境ごとの差を切り分けます。

明示的な呼び出しはできるのに自動で適用されない場合は、Skill自体の配置よりもdescriptionの条件を先に調整します。逆に呼び出し後の出力が指示から外れるなら、手順を短い単位に分け、参照資料や完了条件を明記します。Skillをプラグイン経由で配布する構成では、通常のプロジェクト配置と別の仕組みが関係するため、公式プラグイン構成の説明を確認してください。

原因を一度に複数変更すると、どの修正が効いたか分からなくなります。ディレクトリ、frontmatter、description、本文の順に一項目ずつ直し、同じ依頼を再実行するのが安全です。

作業環境を変える前にSkillの再現性を確かめる

>

まずは、日常の開発で繰り返す作業を一つ選び、Skillの指示と出力の対応を確かめてください。毎回同じプロジェクト環境で作業できるなら、ローカル設定を保つ方法が扱いやすい一方、別の端末や環境を準備する作業が負担なら、リモート開発環境が候補になります。ただし、物理接続が必要な作業や、常時稼働の安定した負荷が前提の用途は、利用条件を先に確認する必要があります。

必要なときだけ別のMac環境を使う選択肢を検討するなら、ZilmacのクラウドMac環境と仮想デスクトップMacの案内で、実際の提供内容や接続方法を確認できます。Skillの検証に必要な環境要件と照らし合わせ、手元の環境で十分なら無理に移行せず、再現性が必要な期間だけ利用する形が適しています。

よくある疑問

>

SKILL.mdには何を記載しますか?

対象となる作業と適用条件、実行の順序、参照すべき情報、完了時に返す内容を分けて記述します。別のタスクまで巻き込まないよう、適用条件は具体的にします。frontmatterの項目や形式は変わる場合があるため、記述前に公式の現行仕様を確認してください。

プロジェクト用の配置先はどこですか?

プロジェクト単位で使うSkillsは、リポジトリ内の.claude/skills/<skill-name>/SKILL.mdに置きます。個人用は~/.claude/skills/<skill-name>/SKILL.mdが標準例です。どちらを選ぶかは共有範囲で決め、設定中のClaude Codeが認識するパスと階層を公式資料で照合します。

自動選択の動作はどう検証しますか?

descriptionに書いた条件と合う依頼を用意し、明示的に呼び出した場合と分けて試します。明示的な実行で指示どおりの出力になることを先に確認すると、Skillの内容と自動選択の問題を切り分けられます。自動選択されない場合は、依頼の表現とdescriptionの適用条件を見直します。

Skillが認識されないときは何を確認しますか?

配置階層、SKILL.mdの綴り、frontmatterのYAML記法、nameとdescriptionの順に確認します。明示的な実行が失敗するなら読み込みや名前を、自動選択だけ失敗するなら適用条件の説明を優先して調整してください。修正後は同じ依頼を再実行し、変化を確認します。

よくある質問

SKILL.mdにはどんな内容をまとめればよいですか?

Skillの説明には、対象タスク、適用する条件、実行手順、完了時に確認する項目を含めます。リポジトリ全体で共有したい規約ではなく、特定作業で繰り返す手順に絞ると、ほかの依頼へ過剰に適用されにくくなります。

プロジェクト内のSkillsはどこに置けばよいですか?

プロジェクト単位で共有する場合は、リポジトリ内の .claude/skills/ にSkill名のディレクトリを作り、その中へSKILL.mdを配置します。個人用の設定とは適用範囲が異なるため、チームで使うものか個人だけで使うものかを先に決めてください。

作成したSkillが自動で使われるか確認する方法はありますか?

descriptionに書いた作業条件に合う依頼と、明示的なスラッシュコマンドの両方を試します。自動選択は説明と依頼内容の一致に左右されるため、認識だけを確かめたい段階では明示的に実行し、出力を確認してから自動適用を検証します。

Skillsが一覧に出ない、または指示どおりに動かない場合は?

まずSKILL.mdのファイル名と配置階層、YAML frontmatterの書式、nameとdescriptionを確認します。明示的な呼び出しも失敗するなら読み込み条件を、自動適用だけされないならdescriptionと依頼内容のずれを疑い、修正後に同じテストを再実行します。

Zilmacで、macOS開発に使える専用環境を用意しませんか

M4搭載の専用クラウドMacで、macOS上の開発作業やビルドを進められます。

フルmacOS環境にSSHまたはVNCで接続し、用途に合わせた作業環境を構築できます。 — プランを見る

期間限定

Zilmac

M4搭載の専用クラウドMacで、macOS上の開発作業やビルドを進められます。

ホームに戻る
期間限定 プランを見る