インディーハッカー道
Claude Codeスキルの作り方をプロが完全解説|毎回の説明を1つ選んで、呼び出せる形にする手順
AI活用

Claude Codeスキルの作り方をプロが完全解説|毎回の説明を1つ選んで、呼び出せる形にする手順

·15分で読める
平城寿
平城 寿(ひらじょう ひさし)
@SOHO創業者 / インディーハッカー

この記事のポイント

  • ✓Claude Code のスキルの作り方を
  • ✓番号つきの手順で解説します
  • ✓SKILL.md の見本

Claude Code に、同じ手順をまた説明している。 そう気づいたことはありませんか。

私は会社を22年やっていて、毎日 Claude Code を使っています。 同じ指示を何度も貼っていた手順は、スキルにして、名前を呼ぶだけで動く形にしました。

この記事では、動画で話した内容に加えて、Claude Code の公式ドキュメントで確かめたことを、手順にして載せています。 スキルを自分で作る手順は、番号を付けて1つずつ書きました。 SKILL.md の見本と、保存する場所は、そのまま写せる形で載せています。 最後に、私が使っている「再発防止」のスキルと、その言葉を拾うフックの作り方も載せました。 動画の説明欄に載せた Claude への指示文も、全文を載せています。 読んだ公式ページの一覧は、最後にあります。

動画でも解説しています。

先に、スキルとは何か

私の説明は、こうです。 決まった手順を書いておく、1つの手順書です。 新人さんに渡す、業務マニュアルのようなものだと思ってください。 Claude Code は、頼まれたときにだけそれを読んで、書いてある通りに動きます。

公式ドキュメント(Extend Claude with skills のページ)でも、スキルは SKILL.md というファイルで作ると書かれています。 中身は、YAML の設定(フロントマター)と、Claude に守らせる手順の本文です。 フォルダの名前が、そのまま呼び出す名前(/名前)になります。

私が、スキルにするようになった理由

困ったことが1つありました。 Claude が Kagemusha を使って作業している間に、私の Mac の画面の一番前にウィンドウが出てきて、私が自分の作業をできなくなることがあったのです。 その場で「前面に出さないで」と言っても、その会話にしか効きません。

窓を開いたときの記録を調べると、スキルを通った形跡がありませんでした。 スキルの側は、前の日に直してありました。 それでも、会話が自己流で起動していたので、直した内容が効いていなかったのです。

原因は、「必ずスキルを通す」と書いた場所が、どこにも無かったことでした。 それ以来、手順はスキルにして残しています。 そして、そのスキルを使う場所に、「必ず使う」と書くようにしました。 この書き方は、後半の手順にあります。

Claude Code に守らせる仕組みは5つある

スキルの作り方に入る前に、仕組みの全体を1枚にします。 どれも、やっていることは同じです。 Claude Code に、自分のやり方を覚えさせて、守らせる仕組みです。

Claude Code に指示を守らせる5つの仕組み。CLAUDE.md、メモリ、スキル、スラッシュコマンド、フックの5枚のカード

仕組み誰が書くかいつ読まれるか向いていること
CLAUDE.md自分で書く毎回の会話の始まり毎回守らせたい決まり
メモリClaude が自分で書く毎回読まれるのは索引だけ叱られたこと、事故の原因の記録
スキル自分で書く(頼めば Claude が作る)その仕事の時だけ決まった手順
スラッシュコマンド自分で書く(頼めば Claude が作る)/名前 と打った時定型作業、間違えたくない指示
フック自分で書く(頼めば Claude が作る)決めた場面の前後絶対に破らせたくないことを、プログラムで止める

公式ドキュメントで確かめた点が、2つあります。

1つ目は、コマンドとスキルの関係です。 いまは、スラッシュコマンドもスキルの一種に統合されています。 以前の .claude/commands/ に置いたファイルも、そのまま動きます。 スキルのほうは、手順書のほかに、スクリプトなどの補助のファイルを同じフォルダに入れられます。

2つ目は、CLAUDE.md の位置づけです。 公式には、CLAUDE.md は強制される設定ではなく、文脈として扱われると書かれています。 CLAUDE.md は1ファイル200行未満を目標にする、という目安もあります。 長いほど、守られる度合いが下がるためです。 そして、必ず守らせたいことは、フックで強制する位置づけです。

私は、次のように分けています。 お願いで足りることは、CLAUDE.md に書きます。 絶対に破らせたくないことは、フックにして、破りそうなときにプログラムが止めます。

お願いで足りる毎回守らせたい決まりは CLAUDE.md、絶対に破らせたくないことは破りそうな時にプログラムが止めるフック、という分け方

スキルにする合図は、1つだけ

スキルにするかどうかは、1つの合図で決めます。 何度も頼んでいる仕事に、気づくことです。 同じ指示を何度も貼っているなら、それがスキルにする合図です。

自分の仕事から探すなら、次の問いが使えます。

  • この1週間で、Claude Code に同じ説明を3回以上したことは何か
  • 説明した内容は、毎回ほぼ同じ文章になっているか
  • 間違えたときに、「今度からこうして」と言い直したことは何か

3つのうち、どれか1つでも当てはまるものが、最初のスキルの候補です。 まず1つだけ選んでください。 1つ選んで作れれば、2つ目からは同じ手順で作れます。

スキルを作る手順

ここからは、実際に作る手順です。 公式ドキュメントの Create your first skill の手順に、私の使い方を合わせて書いています。

1.保存する場所を決める

保存場所は、公式に表で書かれています。

場所パス使える範囲
個人~/.claude/skills/<スキル名>/SKILL.mdこの Mac のすべてのプロジェクト
プロジェクト.claude/skills/<スキル名>/SKILL.mdそのリポジトリの会話。コミットすればチームでも共有できる
入れ子<サブフォルダ>/.claude/skills/<スキル名>/SKILL.mdそのサブフォルダの中で作業するとき

どのプロジェクトでも使う手順は、個人の場所に保存します。 特定のフォルダの中だけで動かしたい手順は、そのフォルダの .claude/skills/ に保存します。 同じ名前が個人とプロジェクトの両方にあるときは、個人のものが優先されると、公式に書かれています。

2.フォルダを作る

個人の場所に、スキルの名前でフォルダを作ります。 名前は、小文字の英数字とハイフンにしておくと、呼び出すときに打ちやすいです。

mkdir -p ~/.claude/skills/summarize-changes

3.SKILL.md を書く

フォルダの中に、SKILL.md というファイルを作ります。 先頭の --- で挟んだ部分が設定で、その下が手順の本文です。 次の見本は、公式ドキュメントの例をもとにしたものです。

--- description: 変更した内容を要約して、危ない点を指摘する。「何を変えた?」「コミットメッセージを考えて」「差分をレビューして」と頼まれたときに使う。 ---

## 現在の変更

!git diff HEAD

## 手順

上の変更を、2〜3個の箇条書きで要約してください。 そのあとで、エラー処理の抜け、直接書かれた値、直すべきテストなど、危ない点を挙げてください。 差分が空のときは、変更が無いと答えてください。

!` で始まる行は、公式で動的コンテキストの挿入と呼ばれています。 Claude Code がそのコマンドを実行して、出力でその行を置き換えてから、Claude に渡します。 つまり、手順を読む時点で、現在の差分がもう入っています。

4.description を書く

SKILL.md の設定の中で、いちばん効くのが description です。 公式には、Claude はこの文を見て、いつそのスキルを使うかを決めると書かれています。 書くときの決まりが、公式にあります。

  • 何をするスキルか、いつ使うかを書く
  • 使う人が自然に言う言葉を入れる
  • 主な用途を先頭に書く。description と when_to_use を合わせた文は、一覧では1,536文字で切られる

名前は、フォルダの名前がそのまま使われます。 フロントマターに name を書けば、その名前になります。

5.呼び出して試す

作ったら、2つの方法で試します。 1つ目は、頼み方で呼ぶ方法です。 description に合う頼み方をします。

何を変えた?

2つ目は、名前で直接呼ぶ方法です。

/summarize-changes

どちらでも、期待した通りに動けば完成です。 公式によると、~/.claude/skills/ の中のスキルは、会話の途中で追加や編集をしても、再起動なしで反映されます。 ただし、スキルのフォルダそのものを新しく作った直後は、/reload-skills を打つと読み込まれます。

6.勝手に動かれたら困る仕事は、自分が呼んだときだけ動く形にする

スキルには、誰が呼ぶかを決める設定が2つあります。 どちらも公式に書かれています。

  • disable-model-invocation: true と書くと、Claude は自分ではそのスキルを読み込みません。/名前 と打ったときだけ動きます
  • user-invocable: false と書くと、/ のメニューに出ません。Claude だけが使います

送信や公開のように、勝手に動かれたら困る仕事は、1つ目にします。 公式でも、/commit や /deploy のような、副作用のある手順に使うよう書かれています。

--- description: 月次のレポートを Excel に転記する。 disable-model-invocation: true ---

## 手順

1.今月のレポートの PDF を開く 2.表の数字を読み取る 3.Excel の該当する行に転記する 4.転記した数字と、PDF の数字を並べて、私に見せる

この例は、私が毎月やっている作業を、そのまま手順にしたものです。 不動産の毎月のレポートが、PDF の添付でメールに届きます。 その PDF を Excel に転記する作業を、コマンドにしています。

7.特定のフォルダの中だけで動かす

私は、この転記のコマンドを、資産管理のフォルダの中でしか動かないようにしています。 その方法は、手順1の入れ子の場所です。 資産管理のフォルダの中の .claude/skills/ に保存します。 そのフォルダの中で作業しているときだけ読み込まれるので、ほかの場所では出てきません。

8.補助のファイルを同じフォルダに入れる

手順が長くなったときは、補助のファイルを同じフォルダに入れます。 公式には、SKILL.md は500行未満に抑えて、詳しい資料は別のファイルへ分けるよう書かれています。 スクリプトも同じフォルダに入れて、SKILL.md から呼ばせられます。

9.毎回、自分で書かなくてよい

ここまで書いてきましたが、実は、自分で書く必要はありません。 Claude Code に、頼むだけで作ってくれます。 スラッシュコマンドにしたいときは、「コマンドにしておいて」と頼みます。 スキルにしたいときは、「いまの手順を、スキルにしておいて」と頼みます。

頼む文の例は、この後の「Claude に頼む文」にあります。

作ったスキルが、呼ばれないとき

スキルは、作っただけでは使われないことがあります。 公式ドキュメントの Skill not triggering には、確かめる順番が書かれています。

1.description に、自分が普段言う言葉が入っているか見る 2.「What skills are available?」と聞いて、一覧にそのスキルがあるか見る 3.description に合う頼み方に言い換えてみる 4./スキル名 と打って、直接呼んでみる 5./スキル名 でも動かないときは、名前が受け付けられたか確かめる 6.paths を書いているときは、作業中のファイルがそのフォルダの中にあるか見る

フロントマターの YAML が壊れているときは、スキルの本文だけが読み込まれます。 この場合、/スキル名 では動きますが、Claude は description で判断できません。 claude --debug で、壊れている箇所が分かります。

私の場合は、ここまでの確認を終えたあとに、最後の手を追加しました。 そのスキルを使う場所の CLAUDE.md に、「この作業は必ずこのスキルを通す」と書いたのです。 Kagemusha の窓の件で、ここが抜けていました。

それでも、絶対に破らせたくないことは、お願いの文章では足りません。 そのためのものが、フックです。

叱った一言を、仕組みに変える

ここからは、私独自の使い方です。 Claude がミスをしたとき、私は「再発防止」と一言打つだけにしています。

なぜこれを考えたかというと、私が会社員のころ、IT コンサルをしていたからです。 システムの障害対応を何度も経験して、そのたびに、クライアント向けの障害報告書を書いていました。 その報告書には、背景、原因、再発防止策の3点を書くことになっていました。 この経験から、これを Claude に覚えさせたらうまくいくのではないかと考えたのです。

流れは、こうです。

  • 私が「再発防止」と打つ
  • フックが、その言葉を拾う
  • スキルが、原因を調べて、同じミスを止める仕組みを作る
  • 次からは、プログラムがそのミスを止める
  • 最後に、メモリへ1件書き残す

叱った一言が、次から自動で止める仕組みに変わります。 しかも、最後にメモリへ1件書き残すので、次の会話の Claude も同じミスを知っています。 私にとって、いちばん強いコマンドです。

スキル本体の見本

次の見本は、私が使っているスキルの考え方を、写せる形にしたものです。 手順は、動画で話した内容のままです。

--- name: prevent-recurrence description: 起きた不具合の原因を調べ、同じことが二度と起きないように、機械が止める仕組みを作る。「再発防止」「同じミスを繰り返すな」と言われたときに使う。 ---

## 手順

1.何が起きたかを、事実で書く。推測と、確かめた事実を分ける 2.原因を調べる。記録、設定、コードを実際に見て、なぜ起きたかを突き止める 3.背景、原因、再発防止策の3点にまとめる 4.「気をつける」「文書に書く」で終わらせない。同じミスをプログラムで止める仕組みを作る 5.作った仕組みが、本当に止まるかを試す。止まったところを見るまで、完了にしない 6.同じ穴が、ほかの場所に空いていないか調べる 7.最後に、何が起きて、どう直したかを、メモリに1件書き残す

手順5の、本当に止まるかを試すところは、動画で話した内容です。 作っただけで終わらせないための手順です。

言葉を拾うフックの見本

フックは、2つのものでできています。 言葉を拾うスクリプトと、それを登録する settings.json の設定です。

公式ドキュメントでは、UserPromptSubmit というフックが、プロンプトを送った瞬間に、Claude が処理を始める前に動くと書かれています。 このフックは、毎回のプロンプトで動きます。 フックのスクリプトには、プロンプトの文字が JSON で渡されます。 スクリプトが成功して終わったとき、出力した文字は、Claude が読む文脈に追加されます。

ここで1つ、はっきりさせておきます。 フックは、スキルを自分で呼ぶことはできません。 できるのは、Claude への指示の文を、文脈に追加することです。 その指示の文に、「必ず再発防止のスキルを使う」と書いておく形になります。

スクリプトは、次のように書きます。 ~/.claude/hooks/ に、saihatsu-boushi.sh という名前で保存します。

#!/bin/bash input=$(cat) prompt=$(echo "$input" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("prompt",""))') case "$prompt" in *再発防止*) echo "ユーザーが「再発防止」と書きました。必ず prevent-recurrence スキルを呼び、その手順の通りに進めてください。" ;; esac exit 0

実行できる形にします。

chmod +x ~/.claude/hooks/saihatsu-boushi.sh

登録は、~/.claude/settings.json に書きます。 UserPromptSubmit は、公式の表で、絞り込みに対応しない(matcher を書かない)イベントです。

{ "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "~/.claude/hooks/saihatsu-boushi.sh" } ] } ] } }

登録できたかどうかは、Claude Code で /hooks と打つと、一覧で確かめられます。 このフックは、毎回のプロンプトで動きます。 公式によると、UserPromptSubmit の標準の待ち時間は30秒です。 スクリプトは、短く終わる形にしておいてください。

試す

登録できたら、「再発防止」と書いて送ります。 Claude が、スキルの手順に沿って、原因の調査から始めたら、成功です。

フックだけでは足りない

フックで止められるのは、はっきり判定できる決まりです。 「この文字が入っていたら止める」という形のものです。

「聞かれたことだけ答える」「読む人の言葉で書く」のような、あいまいな判断が要る決まりは、フックでは判定できません。 これは、Claude の判断に任せる決まりです。 CLAUDE.md や、スキルの手順に書きます。

フックは、この文字が入っていたら止めるというはっきり判定できる決まり。Claude の判断は、あいまいな判断が要る決まり。5つを上手に組み合わせて、過不足のない環境にする

5つの仕組みは、1つを選ぶものではありません。 上手に組み合わせて、過不足のない環境にします。

一言で頼む

仕組みの名前を覚える必要は、ありません。 私は、スキルもスラッシュコマンドも、一応定義はしています。 ただ、コマンドが増えていくと、いちいち覚えていられず、忘れてしまいます。

なので、「〇〇やっておいて」とラフに頼みます。 すると、Claude が自分でスキルやコマンドを探して、実行してくれます。 自分で名前を打つのは、送信や公開のように、勝手に動かれたら困る仕事のときだけです。

迷ったら、Claude Code に一言で聞いてください。 「これは、CLAUDE.md、スキル、フックのどれにするのがよい?」と聞けば、答えてくれます。

Claude に頼む文

そのまま、Claude Code に貼れます。 「〇〇」は、自分のものに直してください。

動画の説明欄に載せた指示文です。

私が「再発防止」と書いたら、障害報告書と同じように、背景・原因・再発防止策をまとめて、同じミスをプログラムで止める仕組みまで作るスキルを作って。「再発防止」の言葉を拾うフックもね

次の4つは、この記事の手順に合わせて、私が書いた頼み方の例です。

1.いまの手順を、スキルにしておいてください。保存する場所は、私に確かめてから決めてください

2.いまの手順を、スラッシュコマンドにしておいてください。/〇〇 と打てば動く形にしてください

3.「〇〇」のフォルダの中でしか動かない、スキルを作ってください

4.これは、CLAUDE.md、スキル、フックのどれにするのがよいか、理由を添えて教えてください

最初のスキルを作る

最後に、1つだけお願いがあります。 あなたが最近、3回以上説明したことを、思い出してください。 それが、最初のスキルになります。

読んだ公式ページ

2026年11月16日に確認しました。

Extend Claude with skills(Claude Code の公式ドキュメント。SKILL.md、置き場所、description、呼び出しの制御、うまく動かないとき) https://code.claude.com/docs/en/skills

Automate workflows with hooks(Claude Code の公式ドキュメント。フックの作り方と、/hooks での確認) https://code.claude.com/docs/en/hooks-guide

Hooks reference(Claude Code の公式ドキュメント。UserPromptSubmit の入力と出力) https://code.claude.com/docs/en/hooks

Manage Claude's memory(Claude Code の公式ドキュメント。CLAUDE.md と自動メモリ) https://code.claude.com/docs/en/memory

シェア
#Claude Code#スキル#SKILL.md#スラッシュコマンド#フック#CLAUDE.md
平城寿
平城 寿(ひらじょう ひさし)
インディーハッカー。2004年に@SOHOを創業し、20年間1人で運営。
フォロー

関連記事