Claude Code Skills/Hooksの作り方

結論、Claude CodeのSkillsは「繰り返す作業手順」をSKILL.mdとして登録する仕組み、Hooksは「操作の前後に処理を差し込む」仕組みです。定型作業はSkills、強制したい制御はHooksと考えると選びやすくなります。

SkillsとHooksの違い

どちらもClaude Codeの拡張機能ですが、効くタイミングと役割が異なります。

そもそもの基本的な起動方法や画面の見方から知りたい場合は、Claude Codeの使い方ガイドを先に確認してください。

Skillsの作り方

Skillsは、プロジェクト直下の .claude/skills/<スキル名>/SKILL.md、または個人の作業環境全体に効かせたい場合はホームディレクトリの ~/.claude/skills/<スキル名>/SKILL.md に置きます。

---
name: deploy-checklist
description: 本番デプロイ前に実行する確認手順。「デプロイして」「本番に出して」といった依頼で候補に挙がる
---

# デプロイ前チェックリスト

1. `npm test` を実行し、失敗がないことを確認する
2. `CHANGELOG.md` に変更点を追記する
3. ステージング環境で動作確認してから本番へ反映する

手順は次の通りです。

1. .claude/skills/配下にスキル名のディレクトリを作り、SKILL.mdを置く。
2. 先頭にYAML形式のfront matterでnameとdescriptionを書く。descriptionは「どんな依頼のときにこのスキルを使うべきか」が伝わる文にする。ここが曖昧だと、意図しない場面で提案されたり、逆に必要な場面で候補に挙がらなかったりする。
3. 本文にMarkdownで具体的な手順を書く。参照資料やスクリプトを同じディレクトリに置いて本文から相対パスで参照することもできる。
4. 保存後、対象の作業を依頼すると候補に挙がる。名前を指定して明示的に呼び出すこともできる。

詳細な仕様はClaude Code公式のSkillsドキュメントで確認できます。

Hooksの作り方

Hooksは、プロジェクト直下の.claude/settings.json、または個人の作業環境全体に効かせたい場合はホームディレクトリの~/.claude/settings.jsonに設定を書きます。イベントの種類ごとに、対象のツールを絞り込むmatcherと、実行するコマンドの配列を指定します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -I{} npx eslint --fix {}"
          }
        ]
      }
    ]
  }
}

上記は、ファイルの編集・作成が行われるたびにESLintの自動修正をかける例です。Hooksのコマンドには、イベントの内容(どのツールが呼ばれ、どんな入力だったか)を含むJSONが標準入力で渡されるので、jqなどでパースして使います。コマンドの終了コードで結果を制御する仕組みもあり、特定の条件で操作そのものをブロックすることもできます。イベント名やJSONの項目名は今後変わる可能性があるため、設定前に公式ドキュメントで最新の仕様を確認するのが安全です。

代表的なイベントには、ツール実行前に働くPreToolUse、実行後に働くPostToolUse、応答終了時に働くStopなどがあります。用途に応じてどのタイミングに差し込むかを選びます。イベント一覧と入出力の仕様はClaude Code公式のHooksドキュメントにまとまっています。

つまずきやすいポイント

• descriptionが曖昧なSkillは呼ばれない、または呼ばれすぎる: 「何をするときに使うスキルか」を具体的な言葉で書かないと、狙った場面で候補に挙がらない。
• プロジェクト用と個人用の置き場所を混同する: .claude/配下はリポジトリに含めればチームに共有されるが、ホームディレクトリ側は自分の作業環境にしか効かない。共有したいのか個人用なのかを先に決める。
• Hooksのコマンドが失敗し続けると毎回引っかかる: JSONのパース処理や外部コマンドの記述ミスがあると、対象の操作のたびにエラーが出る。範囲の狭いイベントで試してから広げる。
• Hooksに重い処理を書くと操作のたびに待ち時間が伸びる: 全ファイルのフルビルドのような重い処理を毎回走らせる設定は避け、対象を絞る。

向いていない人

• 雑談や単発の質問が中心で、繰り返す作業手順が特にない人。仕組み化のコストに見合わない。
• シェルスクリプトやJSON、YAMLの記述に慣れておらず、設定ミスのデバッグに時間を使いたくない人。最初はコピー用のサンプルをそのまま使う範囲にとどめるのが無難。
• プロジェクトごとに手順がバラバラで、共通化できるパターンがまだ見えていない人。無理に仕組み化する前に、まず手作業で数回繰り返してから手順を固めた方が結果的に早い。

FAQ

Q. SkillsとHooksはどちらから作ればいいですか？ A. 同じ手順を毎回自分で指示している作業があるなら、まずSkillsから作るのがおすすめです。特定の操作を常に禁止・実行したいという「強制したいルール」がある場合はHooksが向いています。両方を併用しても構いません。

Q. SkillsとCLAUDE.mdは何が違いますか？ A. CLAUDE.mdはプロジェクト全体に常に効く前提知識やルールを書く場所です。Skillsは特定の作業のときだけ呼び出す手順書という位置づけで、必要な場面でのみ読み込まれる点が異なります。

Q. Hooksの設定を間違えるとどうなりますか？ A. コマンドの記述ミスがあると、対象の操作のたびにエラーが出続けたり、意図せず操作がブロックされたりします。設定直後は影響範囲の狭いイベント(1つのツールだけを対象にするなど)で動作を確認してから広げると安全です。

Q. SkillsやHooksの設定はチームで共有できますか？ A. プロジェクト直下の.claude/ディレクトリに置いた設定はリポジトリに含めて共有できます。個人の作業環境だけに効かせたい設定はホームディレクトリ側に置くことで使い分けられます。

まとめ

Skillsは繰り返す作業手順を登録する仕組み、Hooksは操作の前後に処理を差し込んで制御する仕組みです。まずは今自分が毎回同じ指示を出している作業を1つSkillsにしてみて、次に「常に守らせたいルール」が出てきた段階でHooksを足していくと、設定を持て余さずに運用しやすくなります。