同じ指示を3回打ったら、コマンドにする。私はこの基準でやっています。
3回打つということは、これから10回は打つということです。毎回書くより1度ファイルにしたほうが速い。その1つめを作るところまでを順にたどります。詰まった箇所も書いておきます。
作るのはディレクトリと1枚のファイル
必要なのは2つだけです。ディレクトリ(フォルダのこと)を1つと、その中に SKILL.md という名前のファイルを1枚。
まず個人用の置き場所に作ってみます。個人用に置いたものは、どのプロジェクトからでも使えます。
ターミナルで次を打ちます。先頭の ~ は自分のホームフォルダを指す記号です。
mkdir -p ~/.claude/skills/summarize-changes
次に、テキストエディタで新しいファイルを作り、~/.claude/skills/summarize-changes/SKILL.md という名前で保存します。中身はこう書きます。
---
description: コミットしていない変更を要約し、危なそうな点を挙げる。変更内容を聞かれたときやコミットメッセージを求められたときに使う。
---
## いまの変更
!`git diff HEAD`
## お願い
上の変更を2〜3行の箇条書きで要約してください。そのあと、エラー処理の抜け、ソースに直接書き込まれた値、直すべきテストなど、気になる点を挙げてください。変更がなければ、その旨だけ伝えてください。
これで終わりです。Claude Codeを起動して /summarize-changes と打つと動きます。すでに開いている場合は、一度閉じて開き直してください(理由は後述します)。
上のファイルで何が起きているか
短いので行ごとに見ます。
--- で挟まれた部分がフロントマターと呼ばれる設定欄です。ここに書いた description は、Claudeがこのコマンドをいつ使うか判断する材料になります。打って呼ぶだけなら適当でもいいのですが、後で説明する自動呼び出しに効いてくるので、使う場面を素直に書いておくほうが得です。
!`git diff HEAD` の行は、Claudeが読む前に実行されます。git diff HEAD は、まだコミット(変更の確定)をしていない差分を出すコマンドです。実行結果がその場所に差し込まれるので、Claudeは差分が貼られた状態の指示書を受け取ります。「まず差分を見て」と頼む必要がなくなる、という書き方です。この記法と引数の渡し方は別記事で詳しく扱いました。
残りは日本語の指示です。ここが本体で、凝った書式は要りません。
コマンド名は、ディレクトリの名前から決まる
作ったあとに戸惑ったのがここでした。フロントマターに name という項目があるのですが、個人用とプロジェクト用では、これはコマンド名になりません。
打つ名前を決めるのはディレクトリの名前です。.claude/skills/deploy-staging/SKILL.md なら /deploy-staging になります。name に書いた文字列は一覧に出る表示名として使われるだけです。
例外はプラグインとして配る場合で、こちらは name が名前の最後の部分になり、プラグイン名:名前 という形で呼びます。
以前からある .claude/commands/deploy.md のような1枚ファイルの書き方(いまも動きます)の場合は、拡張子を除いたファイル名がそのままコマンド名です。
個人用か、プロジェクト用か
置き場所は4種類あります。個人用が ~/.claude/skills/、プロジェクト用が .claude/skills/。ほかに会社のIT部門が全社へ配る管理者向けの置き方と、プラグインに同梱する形があります。
判断はそれほど難しくありません。自分の手癖ならホームディレクトリ、リポジトリの作法ならプロジェクトです。「このリポジトリではこういう手順で出す」という内容なら、リポジトリに入れてコミットしてしまえばチーム全員が同じものを使えます。
同じ名前が重なったときは、組織の設定が個人を上書きし、個人がプロジェクトを上書きします。ここは直感と逆かもしれません。プロジェクト固有のほうが強そうに見えますが、個人の設定のほうが勝ちます。
リポジトリ側の .claude/ に何を置くかは、こちらでも整理しています。カスタムコマンドとスキルの関係そのものは別記事にまとめました。
直したら、その場で反映される
試行錯誤で効いてくるのがこれです。Claude Codeは置き場所を監視していて、ファイルを足したり直したりすると、再起動しなくてもその場で反映されます。
私はこれを知らずに、1行直すたびに claude を立ち上げ直していました。10回くらいやって、ふと再起動せずに呼んでみたら普通に新しい内容で動いた、という順で気づきました。
例外が1つあります。~/.claude/skills/ や .claude/skills/ という置き場そのものが、セッションを始めた時点で存在しなかった場合です。新しくできたディレクトリは監視の対象に入らないので、一度立ち上げ直す必要があります。置き場さえできていれば、2つめ以降のスキルを足すのは再起動なしで反映されます。 1つめを作るときだけ立ち上げ直す、と覚えておけば足ります。
打って呼ぶか、気づいてもらうか
既定では、あなたが /名前 と打つこともできるし、Claudeが必要と判断して自分で持ってくることもできます。この2つは、フロントマターで切り分けられます。
デプロイや送信のように、実行するタイミングを自分で決めたいものは disable-model-invocation: true を足します。これでClaudeの判断では動かなくなります。コードが仕上がって見えるからという理由で勝手にデプロイされる、という事故を防ぐための項目です。
逆に、コマンドとして打つ意味はないけれど知っておいてほしい背景知識なら user-invocable: false を書きます。メニューには出さず、Claudeだけが参照します。
短く保つほど長持ちする
最後に、書きすぎないことについて。呼び出したスキルの中身は、そのセッション(Claude Codeを起動してから終えるまでの1回分)のあいだ残り続けます。長く書くほど毎回の消費が増えるということです。公式も SKILL.md は500行以内を目安に挙げています。
長くなってきたら、同じディレクトリに別のファイルを置いて SKILL.md から参照させます。テンプレート、実例、参考資料。必要になったときだけ読ませる形にすれば、本体は短いままで済みます。ディレクトリの形になっているのは、このためでもあります。
私の場合、記事制作のコマンドが200行を超えたあたりで読み返しづらくなりました。レビュー観点を別ファイルに追い出したら本体が70行まで縮み、直すのも楽になりました。1つめは短く、育ってきたら分ける。この順番で足ります。
