Claude CodeのSkill（プラグイン）を最小構成で自作する手順

「Claude CodeのSkillを自作したいけれど、何を書けばいいか分からない」——実はこの状態から抜けるのはそれほど難しくありません。最小構成はMarkdownファイル1つです。中身は、名前・説明文・Claude Codeに実行してほしい手順だけで始められます。この記事では、その最小構成をWindows環境で実際に作り、動かし、他の人に渡すところまでを1本道で進めます。

この記事でやること

この記事では、Claude CodeのSkill（プラグイン）を最小構成で自作する手順を紹介します。

具体的にはざっくり次のあたりを扱います。

Skillの最小構成（SKILL.md1ファイル＋ディレクトリ1つ）を知る
実際に動くSkillを手順通りに作る
descriptionの書き方で起動率を上げるコツを掴む
テンプレート等の補助ファイルを同梱する
動作確認し、起動しない場合の対処法を知る
GitHubで他者に配布する

前提として、Windows 10/11環境で進めます。Mac/Linux向けの手順は含めません。

事前に必要なもの

始める前に、次の準備が整っていることを確認してください。

Claude Codeがインストール済み：ターミナルで claude と入力して起動できる状態
テキストエディタ：メモ帳でも構いません。VS Codeがあると編集が楽です
Windows 10 または 11：この記事はWindows前提で書いています

Claude Codeがまだ入っていない場合は、先にインストールを済ませてから読み進めてください。

Skillの最小構成を知る

Skillの正体は、SKILL.mdというMarkdownファイル1つです。配置場所は決まっていて、プロジェクトの .claude/skills/ フォルダの下に、1スキルにつき1ディレクトリを作ります。

最小のディレクトリ構成は次のようになります。

.claude/
└── skills/
    └── my-first-skill/
        └── SKILL.md

my-first-skill/ の部分は好きな名前で構いません。半角英数字、ハイフン、アンダースコアあたりが無難です。「1スキルにつき1ディレクトリ」だけ押さえておけば大丈夫です。

SKILL.mdの中身は、YAML形式のfrontmatter（ファイル冒頭の --- で囲まれた部分）と、その下に続く本文で構成されます。

frontmatterの必須項目は2つだけです。

項目	役割
`name`	Skillの名前。管理上の識別子として使われる
`description`	Skillの説明。起動条件として機能する

これだけ分かっていれば、次のセクションで実際に作れます。

配置場所にはもう1つ選択肢があります。ホームディレクトリ直下の ~/.claude/skills/ に置くと、すべてのプロジェクトで共通して使える「グローバルスキル」になります。

まずはプロジェクト別（.claude/skills/）で試すのがおすすめです。グローバルに置くのは、複数プロジェクトで使い回すようになってからで構いません。

最小構成のSkillを作ってみる

それでは実際に作ります。ターミナル（PowerShellまたはコマンドプロンプト）を開いて、プロジェクトのディレクトリに移動してください。

ディレクトリを作る

New-Item -ItemType Directory -Force -Path ".\.claude\skills\hello-skill"

SKILL.mdを作る

テキストエディタで .claude/skills/hello-skill/SKILL.md を新規作成し、次の内容を貼り付けます。

---
name: hello-skill
description: |
  挨拶を生成するスキル。ユーザーが「挨拶して」「hello」などを
  入力した時に起動する。
---

# 挨拶スキル

ユーザーの依頼:
- $ARGUMENTS

## 手順

1. ユーザーの名前を確認する（指定されなければ「あなた」とする）
2. 挨拶のメッセージを生成する
3. 結果を表示する

保存して完了

ファイルを保存したら、Skillの作成は終わりです。たったこれだけです。

これで hello-skill という名前のSkillが .claude/skills/hello-skill/SKILL.md にできました。frontmatterの name と description、そして本文の3つだけで構成されています。

descriptionの書き方で起動率を上げる

Skillを作っただけでは終わりません。descriptionの書き方次第で、Claude CodeがそのSkillを自動起動するかどうかが大きく変わります。ここが一番つまずきやすいポイントなので、少し丁寧に説明します。

descriptionは、Claude Codeが「このSkillを起動すべきか」を判断する材料になります。曖昧に書くと起動してくれず、具体的に書くと起動しやすくなります。

起動しやすいdescriptionの例：

description: |
  Markdownファイルの目次を自動生成するスキル。
  ユーザーが「目次を作って」「TOCを生成」等を
  入力した時に起動する。

ポイントは「何をするスキルか」と「どんな言葉で起動するか」の両方を書いている点です。

もう1つ例を挙げます。

description: |
  指定したディレクトリ内のファイル一覧をMarkdownの
  表形式で出力するスキル。ファイル数や拡張子の集計も
  含む。「ファイル一覧」「ディレクトリの中身」等の
  入力で起動する。

起動しにくいdescriptionの例：

description: |
  ファイル関連のスキルです。

これだと「ファイル関連」が広すぎて、どのタイミングで起動すればいいか判断できません。

悪い例を修正すると次のようになります。

description: |
  指定したディレクトリ内のファイル一覧をMarkdownの
  表形式で出力するスキル。ファイル数や拡張子の集計も
  含む。「ファイル一覧」「ディレクトリの中身」等の
  入力で起動する。

ざっくり言うと、次の3つを押さえておけば安心です。

具体的な動詞：「生成する」「出力する」「変換する」等の動きを明示する
対象を書く：「Markdownの目次」「ファイル一覧」等、何を扱うかを書く
起動条件を書く：ユーザーがどんな言葉を入力した時に起動するかを記載する

最初はこの3つを意識して書いてみて、起動しなければ少しずつ言葉を足していくのが実践的な進め方です。

補助ファイルを同梱する

最小構成から一歩進んで、テンプレートやスクリプトなどの補助ファイルをSkillに同梱したい場合があります。やり方はシンプルです。Skillのディレクトリにファイルを置くだけでOKです。

.claude/
└── skills/
    └── report-generator/
        ├── SKILL.md
        └── template.md

このように template.md を同じディレクトリに置いた場合、SKILL.mdの本文から次のように参照できます。

## 手順

1. `template.md` を読み込む
2. ユーザーの指定内容で変数を置換する
3. 結果を出力する

Claude Codeは同じディレクトリ内のファイルを読み取れるため、「template.mdを読み込む」と書けば認識してくれます。

補助ファイルは何個置いても構いません。テンプレート、設定ファイル、サンプルコードなど、Skillに必要なものを同じディレクトリにまとめておけば管理しやすくなります。

動作確認とトラブル対処

Skillを作ったら、正しく認識されているか確認します。

確認方法：

Claude Codeを起動して、Skillに関連する言葉を入力してみます。hello-skill なら、まずは「挨拶して」と入力して試します。反応しない場合は、/hello-skill のようにSkill名を直接入力して確認すると分かりやすいです。

起動しない場合のチェック手順：

配置場所の確認：.claude/skills/ の下にディレクトリがあり、その中に SKILL.md があるか
frontmatterの書式：--- で正しく囲まれているか。インデントにズレがないか
descriptionの見直し：曖昧な表現になっていないか。具体的な動詞と起動条件が書いてあるか
ファイル名：SKILL.md になっているか（skill.md は動作しない可能性がある）

Skillが正しく動作しない場合、エラーの原因特定と解決の手順を参考にしてください。

ここで一番よくあるのが description の曖昧さです。前のセクションのポイントを参考に、具体的な言葉に書き直してから再度試してみてください。

Windows環境ではパスの区切り文字に注意してください。PowerShellとコマンドプロンプトでは、使える書き方が少し違います。うまく作れない場合は、上のコマンドをコピーして使い、.claude\skills\hello-skill の階層ができているか確認してください。

作ったSkillを配布する

完成したSkillを他の人に渡す方法として、GitHubを使った配布が一般的です。

配布の流れ：

Skillのディレクトリ（例：hello-skill/）をGitHubリポジトリにpushする
README等で「.claude/skills/ の下に配置してください」と案内する
相手がクローンまたはダウンロードして、所定の場所に置けば使える

配布時のポイントとして、相手の環境（Windowsかどうか、Claude Codeがインストール済みか）は相手側の前提になるため、READMEに書いておくと親切です。

Skillは標準的なファイル構成（SKILL.md ＋任意の補助ファイル）なので、zipで固めて配布しても構いません。相手が .claude/skills/ 以下に展開すれば動きます。

最後に確認すること

ここまでの手順で、Skillの自作から動作確認まで一通りできたはずです。最後にざっくりと確認ポイントを整理します。

SKILL.md に name と description が書かれている
.claude/skills/スキル名/SKILL.md の場所に配置されている
Claude Codeを起動して関連する言葉を入力すると、Skillが自動起動する
description は具体的な動詞と起動条件を含んでいる

これらが揃っていれば、最小構成のSkillとしては完成です。

次に試すこととしては、次の方向があります。

allowed-tools を追加する：Skillが使えるツール（Read、Write、Bash等）を制限・許可するオプション項目です。実行環境を絞りたい場合に便利です。詳しくはスキル機能の自動化事例で紹介しています
argument-hint を追加する：Skillの引数の書き方をユーザーに伝える項目です。引数付きで起動するSkillを作る時に役立ちます
より複雑なSkillへの拡張：複数ステップの処理を記述したり、他のSkillと連携させたりすることも可能です

まずは name と description と本文だけの最小構成で動かしてみて、慣れてきたらオプション項目を足していくのがおすすめです。

まとめ

Skillの最小構成は「SKILL.md1ファイルを1ディレクトリに置く」だけです。frontmatterにnameとdescriptionを書き、本文に手順を書けば、動くSkillが完成します。

特にdescriptionの書き方に気をつけると、Claude Codeが必要な場面でSkillを見つけやすくなります。最初はシンプルなものから始めて、動かしながら機能を増やしていくのがおすすめです。

Claude Codeでどこまでできる？