実際に使える Claude Code Skill の構築方法（完全ガイド）

Claude を 1 週間使って、毎回同じことを入力していませんか？コードをコミットするたびに、コミット形式に関する 3 つのルールを貼り付けている。ドキュメントを書くたびに、自分のスタイルを再説明している。Claude はその場ではうまくやってくれるけど、チャットが終わるとすぐに忘れてしまい、翌日にはまた全部を入力し直している。

そういう問題を解決するのが「スキル」です。スキルとは、一度書けば Claude にワークフローを恒久的に教えられる小さなフォルダで、毎回のセッションでユーザーが頼まなくても自動で適用されます。

仕組みは一目瞭然です。スキルは 1 つのファイルが入ったフォルダです。Claude はそのスキルの 1 行の要約を常に表示しておき、リクエストが一致したときだけ完全な指示を読み込みます。これが全体の仕組みです。

このガイドでは、実際のスキルを 1 つ、ゼロから作成します。それが「commit-messages」です。このスキルは、あなたの指定した形式で git コミットを作成します。Claude がインストールされていれば、あとは何もなくてもすべての手順を実行できます。

完成イメージ

スキルの核は、1 つのフォルダと 1 つの必須ファイル「SKILL.md」です。スキルが成長するにつれて、3 つのオプションフォルダが後から追加されます。

1your-skill-name/
2├── SKILL.md          # 必須 - メインのスキルファイル
3├── scripts/          # オプション - 実行可能なコード
4├── references/       # オプション - ドキュメント
5└── assets/           # オプション - テンプレートなど

SKILL.md 自体には 2 つの部分があります。1 つは Claude に いつ スキルを使うかを伝える短いヘッダー、もう 1 つはその下に Claude に 何を するかを伝える指示です。この分割には理由があります。Claude はヘッダーを常に読み込むのでスキルの存在を常に認識していますが、リクエストが一致したときだけ指示を読み込みます。この違いを覚えておいてください。このガイドのほぼすべては、この点から派生しています。

作成する

スキルは、ホームディレクトリ内の「.claude/skills」というフォルダに保存されます。Claude Code とデスクトップアプリの両方がこのフォルダを読み取ります。これは隠しフォルダで、おそらくまだ存在していないので、スキル用のフォルダと一緒に作成する最も簡単な方法は、1 つのコマンドを実行することです。

Mac の場合、ターミナルを開いて次のコマンドを実行します：

1mkdir -p ~/.claude/skills/your-skill-name

Windows の場合、PowerShell を開いて次のコマンドを実行します：

1New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\your-skill-name"

フォルダ名は見た目の問題だけではありません。Claude はこれをスキルの識別子として使用します。そして、あるフォーマットルールが他の何よりも多くの人を悩ませています：

• ケバブケースを使用：notion-project-setup ✔
• スペースは不可：Notion Project Setup ✖
• アンダースコアは不可：notion_project_setup ✖
• 大文字は不可：NotionProjectSetup ✖

そのフォルダ内に、正確に「SKILL.md」という名前のファイルを作成し、テキストエディタで開きます。ここからの内容はすべて、そのファイルに記述します。

書く前に設計する

うまくいくスキルは、ファイルを 1 行も書く前に 2 つの決定を下すことから始まります。どちらもスキップできそうに感じられますが、どちらもスキップできません。

まず、スキルをいつ発動させるべきかを正確に決めます。ユーザーが実際に入力するであろう言葉で、2 ～ 3 つの実際の状況を書き出します：

• "commit these changes"
• "write a commit message for this diff"
• "stage and commit"

これは無駄な作業ではありません。これらのフレーズは、後で説明文やテストのための材料になります。これらを決めずに設計されたスキルは、あいまいになりがちで、まさにそのあいまいさが原因でスキルが発動しなくなります。

次に、スキルが機能していることをどうやって確認するかを決めます。何よりも重要な基準は、スキルに名前を指定しなくても、自動で読み込まれるかどうかです。毎回手動で呼び出さなければならないなら、スキルは技術的には動作していても、実際の仕事は失敗しています。それと同時に確認すべきことは、途中で修正しなくてもタスクを完了できるかどうか、そしてセッションが変わっても同じような結果が得られるかどうかです。

説明文が成功を左右する

ファイルの中でも、ヘッダー内の説明文が最も重要な役割を果たします。なぜなら、Claude がスキルを読み込むかどうかを判断する際に参照する唯一の部分だからです。指示が完璧でも意味がありません。説明文が一致しなければ、Claude は指示にたどり着けないからです。ほとんどの「うまくいかない」スキルは、実際にはここで失敗しています。

優れた説明文は、1 つの文で 2 つの質問に答えます。スキルが何をするか、そして Claude がそれをいつ使うべきかです。この後半部分が、多くの人が省略してしまう部分です。

違いはこれです：

1# 弱い - 何をするかは書いてあるが、リクエストと照合する材料がない
2description: Helps with git commits.
3
4# 強い - 発動すべき具体的な場面を指定している
5description: Writes git commit messages in Conventional Commits format. Use when the user asks to commit changes, write a commit message, or stage and commit files.

弱いバージョンは、Claude にスキルの存在を伝えますが、ユーザーが言いそうなこととは何も結びつきません。強いバージョンは、実際のフレーズを指定しているので、"commit these changes" と入力したときに、Claude が照合する対象を持てます。ユーザーが実際に使う言葉を指定し、全体を 1024 文字以内に収め、内部に < や > を入れないでください。

スキルが発動しない場合、ほぼ常にここが原因です。実際に使っている言い回しを追加してください。"save my work" と言っているのに説明文が "commit" だけを記載している場合、Claude は両者を結びつける方法がありません。逆に、スキルが発動すべきでないときに発動してしまう場合は、説明文を絞り込むか、否定トリガーを追加します：

1description: Writes git commit messages in Conventional Commits format. Use when committing changes. Do not use for writing code comments or documentation.

スキルに頼る前に、簡単な確認方法があります。Claude に直接尋ねてみてください：

"When would you use the commit-messages skill?"

Claude はあなたの説明文を自分の言葉で読み返します。その答えが、実際にスキルを発動させたいタイミングと一致しない場合、問題は説明文にあり、その下にある指示にはありません。

Claude が実際に従う指示を書く

ヘッダーの下には、プレーンな Markdown で本文が続きます。ここに実際のワークフローが記述されます。Claude が従う指示と、静かに無視してしまう指示とを分ける 2 つの習慣があります。

1 つ目は、具体的であることです。Claude は具体的な指示には従い、あいまいな指示は軽く扱います。したがって、より正確に記述すればするほど、Claude はより確実に動作します：

1# Bad
2Validate the commit before finalizing.
3
4# Good
5Run `python scripts/validate.py "<message>"`.
6If it fails, fix these:
7- Invalid type: use feat, fix, docs, refactor, test, chore
8- Summary over 60 chars: shorten it

2 つ目は、順序です。Claude は最初に読んだものを重視するため、長いファイルの最後に埋もれたルールは見逃されがちです。絶対に破ってはいけないルールは、先頭に、それを示す見出しの下に置きます：

1## Important
2- Summary line under 60 characters, always
3- Present tense only: "add", not "added"

また、言語で保証できることにも限界があります。指示は解釈されるため、Claude はそれらにうまく従いますが、毎回全く同じように従うわけではありません。チェックが本当に毎回必ずパスしなければならない場合、それを散文で説明するのではなく、スクリプトに移して、指示からそれを実行するようにします。コードは毎回同じことを行います。文章はそうではありません。（これが scripts/ フォルダの目的であり、次に説明します。）

ほとんどのスキルでうまく機能する構造は、次のようになります：

1# Skill Name
2
3## Important
4Critical rules that must not be missed.
5
6## Instructions
7Step by step, specific and actionable.
8
9## Examples
10Concrete input and output. Claude copies examples more reliably than it follows rules.

ファイルは簡潔に保ってください。コアの指示を超えてファイルが大きくなり始めたら、追加の詳細を外部に移すタイミングです。これこそが、まさにオプションフォルダの目的です。

Scripts、References、Assets

ここまでの内容で、Claude に指示を与えるスキルができました。3 つのオプションフォルダは、それを Claude にツールを与えるスキルに変え、これによりスキルはプレーンなプロンプトではできないことを実行できるようになります。

scripts/ は、Claude が実行するコードを保持します。正確さが求められるあらゆるものに使用します。Claude にコミットのフォーマットが正しいかどうかを目視で確認させるのではなく、チェック用のスクリプトを渡します：

1# scripts/validate.py
2import sys
3msg = sys.argv[1]
4types = ("feat", "fix", "docs", "refactor", "test", "chore")
5
6if msg.split(":")[0] not in types:
7    print(f"Invalid type. Use: {', '.join(types)}")
8elif len(msg.split("\n")[0]) > 60:
9    print("Summary too long (over 60 chars)")
10else:
11    print("OK")

そして、SKILL.md で Claude にそのスクリプトを使用するように指示します：

1Before finalizing, run `python scripts/validate.py "<message>"`
2and fix anything it flags.

これで、フォーマットルールは毎回同じように動作するコードによって強制され、Claude がチェックを覚えているかどうかに依存しなくなります。

references/ は、必要なときだけ読み込まれるドキュメントを保持します。コミット規約が 2 ページにわたるスコープ、フッター、エッジケースで構成されているとします。これらすべてを SKILL.md に置くと、1 行のコミットでも毎回すべて読み込まれます。代わりに、リファレンスファイルに移動します：

1your-skill-name/
2├── SKILL.md
3└── references/
4    └── conventions.md

そして、メインファイルからそれを参照します：

1For the full convention list, see references/conventions.md

Claude は、タスクで必要になった場合にのみそのファイルを開きます。これこそが、スキルを低コストで実行できるようにする理由のすべてです。重要な詳細は、実際に関連するまでディスク上に置かれ、毎回コンテキストに含まれることはありません。

assets/ は、スキルがガイダンスとして読むのではなく、出力で使用するファイルを保持します。テンプレート、設定ファイル、ロゴなどです。コミットスキルには必要ありませんが、レポートを生成するスキルでは、ここに template.md を置き、毎回それを埋め込むことで、すべてのレポートが同じ構造で出力されます。

これら 3 つのフォルダをまとめると、スキルが Claude に「あなたの作業方法」を伝えるだけのものから、Claude に「あなたのやり方で作業を実行するための正確なツール」を提供するものへと変わります。

覚えておくべきこと

スキルは、Claude に新しい能力を教えるものではありません。Claude はすでにコミットの書き方を知っています。スキルが行うのは、毎回、あなたが再説明しなくても、あなたのやり方で仕事を実行させることです。

そして、スキルがうまくいかない場合、その原因は、あなたが苦心して書いた指示にあることはほとんどありません。それは説明文にあります。Claude は、その 1 行だけでスキルを読み込むかどうかを判断し、その下にある作業を読むことはありません。説明文を正しく記述すれば、その下のすべてがようやく使われるようになります。

この記事が役に立ったなら、私のプロフィールにアクセスしてフォローしてください。テクノロジー、AI、そして実際に機能するシステムについて書いています。

Ciao,

@undefinedKi