【Claude Code】Skillsの使い方をわかりやすく解説

Claude CodeのSkills機能で、AIへの繰り返し指示を効率化する使い方を解説します。スキルの作成方法から、手動・自動での利用、引数の渡し方、そしてデータベース操作のような取り消しできない危険な操作を安全に扱うための設定まで、システムエンジニア初心者向けにわかりやすく解説します。

作成日: 2026年05月10日更新日: 2026年09月29日

開発環境

OS: Windows10（WSL2 / Ubuntu）
Editor: Visual Studio Code
Node.js: v22.22.2
claude-code: 2.1.118

Claude Code Skills（スキルズ）とは？

AIに指示を出す際に、毎回同じ指示文（これを「プロンプト」と呼びます）を入力したり、コピー＆ペーストしたりすることがあるかと思います。これは作業の効率を下げる原因になります。Claude Code Skills（スキルズ）は、このような非効率な作業を解決するための機能です。

スキルズを利用することで、事前に用意した一連の指示を、たった1行の「/コマンド」で簡単に呼び出して実行できるようになります。

.claude/skills/ に Markdown ファイルを置くだけで作れるスキルズを作成する方法は非常にシンプルです。特定のフォルダ（.claude/skills/）の中に、指示内容を記述した「Markdownファイル」を置くだけで作成できます。Markdownファイルとは、文章を簡単に記述できる形式のファイルのことです。
/ から始まる スラッシュコマンド として使える作成したスキルは、チャットツールなどで見かける「スラッシュコマンド」と同じように利用できます。例えば「/summarize」といったように、スラッシュとコマンド名を打ち込むだけで、対応する指示が実行されます。これにより、必要な機能を素早く呼び出すことが可能です。
Claude が 自動で 呼び出すこともできる（自動委譲）スキルズのもう一つの便利な点は、AIであるClaudeが、会話の流れや文脈を判断して、適切なスキルを自動的に選び、実行してくれる機能があることです。これを「自動委譲」と呼びます。例えば、要約が必要な場面では、Claudeが自動的に要約スキルを呼び出して、作業を進めてくれますので、ユーザーが手動でコマンドを入力する手間が省けます。

公式ドキュメント: https://code.claude.com/docs/ja/skills

配置場所で有効範囲が変わる

特定の機能や設定ファイルなどをどこに置くかによって、それが使える範囲が変わるというお話です。

my-project/.claude/skills/ → このプロジェクトだけこれは、あなたが現在作業している特定のプロジェクトのフォルダ内に、関連するファイル（例: skills という機能に関するファイル）を置く場合のルールです。このフォルダに置かれたファイルは、その my-project という名前のプロジェクト内でのみ有効となり、他のプロジェクトからは利用できません。
~/.claude/skills/ → すべてのプロジェクトこれは、あなたのパソコンの「ホームディレクトリ」（~ で表現されます）の中に、関連するファイルを置く場合のルールです。ホームディレクトリに置かれたファイルは、どのプロジェクトで作業していても共通で利用できます。つまり、すべてのプロジェクトで同じ機能や設定を使いたい場合に便利です。

チームで開発を進める際に、プロジェクトメンバー全員で共通して使いたい設定や機能がある場合は、そのプロジェクト専用のフォルダ（例: my-project/.claude/skills/）にファイルを置きます。そして、そのファイルをGitというバージョン管理システムを使って共有することで、チームメンバー全員が同じ環境で作業できるようになります。

一方で、自分だけが使いたい設定や、どのプロジェクトでも共通して使いたい個人用の機能がある場合は、あなたのホームディレクトリ内（例: ~/.claude/skills/）にファイルを置きます。これにより、その設定や機能はあなた専用となり、他のプロジェクトや他のチームメンバーに影響を与えることなく利用できます。

ビフォー・アフター

システムエンジニアとして作業をする際、私たちは毎日さまざまな指示やコマンドを入力します。この「ビフォー・アフター」は、その入力作業をいかに効率化できるかを示しています。


1# 毎回これを打つのをやめる
2「src/auth.ts のコードを初心者向けに解説して。
3 図解とたとえ話を使って、落とし穴も教えて」

上の例では、あるファイルの内容について詳細な解説を求める、非常に長い指示文が示されています。このような指示文を毎回手動で入力する場合、いくつかの問題が発生します。

入力の手間と時間: 指示文が長いため、入力に時間がかかり、手間がかかります。
入力ミスの可能性: 長い文章を手で打つと、スペルミスやタイプミスが発生しやすくなります。これにより、期待通りの結果が得られないことがあります。
作業の中断: 同じような指示を何度も繰り返す場合、その都度長い文章を入力することは、作業の流れを中断させ、集中力を妨げる要因となります。

システム開発の現場では、このような非効率な作業は、全体の生産性を低下させる原因となります。


1# skill にすると1行で済む
2/explain-code src/auth.ts

一方、下の例では、たった一行の短いコマンドで同じ目的を達成しています。これは、「スキル」（または「エイリアス」「カスタムコマンド」といった機能）を利用して、複雑な指示を簡略化する仕組みの一例です。

効率の向上: 短いコマンドを入力するだけで良いため、入力にかかる時間と手間が大幅に削減されます。
入力ミスの減少: 短いコマンドは入力ミスが起こりにくく、正確に実行できます。
作業の円滑化: 定型的な作業をコマンド一つで実行できるため、作業の流れがスムーズになり、開発効率が向上します。

システムエンジニアにとって、このように繰り返し行う作業を効率化する視点は非常に重要です。長い指示文を一度定義して短いコマンドに置き換えることで、日々の作業をより迅速かつ正確に進めることができるようになります。これは、ツールの活用や自動化の基本的な考え方につながります。

スキルファイルの構造

スキルファイルは、その名の通り、特定の機能や処理を行うための「スキル」を定義するファイルです。このファイルは 2つのパート で構成されています。

この図は、スキルファイルの構成を視覚的に示しています。ファイルの冒頭に「---」という区切り線があり、その間に設定情報が記述されます。そして、二つ目の「---」の後ろに、スキルが実行する具体的な内容が記述される構造です。


1┌──────────────────────────────┐
2│ --- (frontmatter: YAML設定)  │  ← 名前・説明・引数ヒント
3│ ---                          │
4│                              │
5│ 本文（プロンプト本体）          │  ← Claude への指示
6└──────────────────────────────┘

frontmatter (YAML設定)

このセクションは、ファイルの先頭から二つ目の「---」までの部分です。ここでは、そのスキルに関する基本的な情報や設定を記述します。

YAML設定：YAML（ヤムル）とは、データを人が読み書きしやすい形で表現するためのデータ記述形式です。プログラミングの世界では、設定ファイルなどによく利用されます。
名前：このスキルがどのような目的を持つのか、その識別のための名前を記述します。
説明：このスキルが具体的に何を行うのか、その機能を簡単に説明する文章を記述します。この説明は、他の人がスキルを利用する際に参考になります。
引数ヒント：このスキルを実行する際に、どのような情報を入力として渡す必要があるのか、その入力の形式や内容に関するヒントや指示を記述します。

これらの情報は、スキル自体がどのように動作するかではなく、スキルがどのようなものか、どのように使うかを定義する役割があります。

本文（プロンプト本体）

このセクションは、二つ目の「---」の後ろからファイルの最後まで続く部分です。ここに記述される内容が、AIモデルであるClaudeへの具体的な指示となります。

Claude への指示：この部分には、スキルが実行された際にClaudeにどのようなタスクを実行してほしいのか、どのような応答を生成してほしいのか、といった具体的な命令や手順を記述します。ここが、スキルの核となる処理内容を定義する場所です。

ファイルの保存場所と命名規則

作成したスキルファイルは、特定のルールに従って保存する必要があります。

.claude/skills/<スキル名>/SKILL.md として保存する。

.claude/skills/：これは、スキルファイルを格納するための固定のディレクトリパス（フォルダの場所）です。
<スキル名>：この部分は、作成するスキルの名前を示します。この名前は、ディレクトリ名（フォルダ名）として使用されます。例えば、translate_textというスキルを作成する場合は、translate_textという名前のディレクトリを作成します。
SKILL.md：スキルファイルのファイル名は、常にSKILL.mdとします。.mdはMarkdown形式のファイルであることを示しています。

ディレクトリ名がスキル名になる。

特に重要な点として、スキルファイルが格納されるディレクトリの名前（<スキル名>の部分）が、そのスキルの正式な名前としてシステムに認識されます。したがって、スキルを作成する際は、そのスキルに合った適切な名前をディレクトリ名として設定する必要があります。

これらのルールを守ってファイルを配置することで、システムはスキルを正しく認識し、利用できるようになります。

実例 1: コード解説スキル


1---
2name: explain-code
3description: コードをわかりやすく解説する。
4             「このコード何してるの？」と言われたときに使う。
5argument-hint: <ファイルパス>
6---
7
8以下のファイルを読んで、初心者にもわかるように解説してください。
9
10対象: $ARGUMENTS
11
12解説の構成：
131. 一言でいうと
142. たとえ話
153. 全体の流れ（ASCII図）
164. コードのポイント解説
175. 落とし穴

一言でいうと

「コード解説スキル」とは、書かれているプログラムコードが「何のために」「どのように」動いているのかを、システムエンジニアを目指す初心者の方にもわかるように、簡潔かつ明確に説明する能力のことです。

たとえ話

このスキルは、新しい家電製品を購入したときに付属している「取扱説明書」を作成するようなものと考えてください。取扱説明書は、製品の各ボタンが何をするのか、どのような手順で使えば良いのかを、初めて使う人が迷わずに理解できるように説明しています。コード解説もこれと同じで、プログラムの「取扱説明書」のように、コードが何をしているのかを順序立てて説明する役割を持っています。

全体の流れ（ASCII図）

コードを初心者の方に解説する際の一般的な流れは、以下のようになります。

+---------------------------------+
| 1. コードの全体像を把握する     |
| (このコードが何を実現したいのか)  |
+---------------------------------+
                |
                v
+---------------------------------+
| 2. 主要な部分を特定する         |
| (特に重要な機能や処理はどこか)  |
+---------------------------------+
                |
                v
+---------------------------------+
| 3. 各部分の役割を説明する       |
| (変数、関数、条件分岐などが何をしているか) |
+---------------------------------+
                |
                v
+---------------------------------+
| 4. 実行の流れを追って説明する   |
| (コードが上から順にどのように動くか) |
+---------------------------------+
                |
                v
+---------------------------------+
| 5. 全体として何ができたかをまとめる |
| (最終的にどんな結果になるのか)    |
+---------------------------------+

コードのポイント解説

コードを解説する際には、以下のポイントに注目して説明すると、初心者の方にも理解しやすくなります。

プログラム全体の目的: そのコードが最終的に何を実現しようとしているのかを最初に伝えます。例えば、「これはユーザーが入力した情報を処理して、結果を表示するプログラムです」のように説明します。
主要な変数や定数: プログラムの中で重要な意味を持つデータ（変数や定数）が、何を表しているのかを具体的に説明します。
関数やメソッド: 特定の処理をまとめて実行する部分（関数やメソッド）が、どのような役割を持ち、何を受け取って何を返すのかを説明します。
条件分岐（if文など）: プログラムが「もしAならばBをする、そうでなければCをする」といった判断をしている部分について、どのような条件でどのような処理が行われるのかを説明します。
繰り返し（for文、while文など）: 同じ処理を何度も繰り返す部分について、なぜ繰り返すのか、何回繰り返すのか、繰り返しのたびに何が変わるのかを説明します。
入出力: プログラムが外部から情報を受け取ったり（入力）、外部へ情報を表示したり（出力）する部分について、どのようにデータのやり取りをしているのかを説明します。

落とし穴

コードを解説する際に陥りやすい落とし穴をいくつかご紹介します。これらを避けることで、より質の高い解説ができます。

専門用語をそのまま使う: プログラミングの専門用語を、解説なしでそのまま使ってしまうと、初心者の方には理解が難しいです。必要であれば、簡単な言葉に置き換えるか、その都度説明を加えるようにします。
コードを逐語訳するだけになる: コードの各行をただ日本語に直すだけでは、なぜそのコードが書かれているのか、全体として何をしているのかが伝わりにくいです。それぞれの行が全体の目的の中でどのような役割を担っているのかを説明することが重要です。
相手の知識レベルを考慮しない: 解説を聞く人がどのくらいの知識を持っているのかを事前に把握せず、高すぎるレベルで説明したり、逆に簡単すぎる説明をしてしまったりすることがあります。常に相手の知識レベルに合わせて内容を調整することが大切です。
詳細にこだわりすぎる: 全ての細かい部分まで説明しようとすると、情報量が多すぎて、かえって全体像がつかみにくくなります。まずは重要な部分や基本的な流れを説明し、質問があれば詳細を補足する、といった進め方が有効です。
なぜそのコードになったのかの背景を説明しない: コードが書かれた意図や、なぜそのような設計になっているのか、どのような課題を解決しようとしているのかといった背景を説明しないと、単なる「動くもの」としてしか理解してもらえません。背景を伝えることで、より深い理解を促すことができます。

frontmatter の各フィールド

ここでは、プログラムや設定の冒頭部分によく見られる「frontmatter」という領域にある、各設定項目（フィールド）について説明します。これらのフィールドは、AIが特定の機能をどのように扱い、いつ利用するかを決定するために使用されます。

フィールド	説明	例
`name`	スキルのID（省略時はディレクトリ名）	`explain-code`
`description`	いつ使うかをClaudeに伝える	「コードを解説する」
`argument-hint`	引数の表示ヒント	`<ファイルパス>`
`disable-model-invocation`	自動呼び出しを禁止	`true`
`allowed-tools`	使えるツールを制限	`Read, Grep`

それぞれのフィールドについて詳しく見ていきましょう。

name これは、特定の「スキル」や「機能」を識別するための名前です。もしこの名前が指定されない場合、そのスキルが置かれているディレクトリ（フォルダ）の名前が自動的に使われます。例えば、コードを解説するスキルであれば、explain-codeという名前が付けられます。
description このフィールドは、AI（ここではClaudeというAIを想定しています）に対して、「このスキルや機能をどんな状況で使えば良いのか」を具体的に伝えるための説明文です。例えば、「コードを解説する」という説明があれば、AIはユーザーがコードの解説を求めているときにこのスキルを使おうと判断します。この説明の書き方が、AIがスキルを適切に利用するかどうかを決める上で非常に重要です。
argument-hint このフィールドは、AIがスキルを使用する際に、どのような情報（引数と呼びます）を渡せば良いのかを示すヒントです。例えば、<ファイルパス>と指定されていれば、AIはスキルにファイルの場所を渡す必要があると理解します。これにより、AIはスキルを正しく利用するための情報を準備できます。
disable-model-invocation このフィールドにtrueと設定すると、AIがこのスキルを自動的に判断して呼び出すことを禁止します。つまり、明示的に指示しない限り、AIが勝手にこのスキルを使わないように設定できるということです。これにより、意図しないスキルの実行を防ぐことができます。
allowed-tools このフィールドは、特定のスキルが利用できる追加の機能やツールを制限するために使われます。例えば、ReadやGrepといったツールを指定することで、このスキルはファイルを読み込む（Read）ことや、ファイルの中から特定の文字列を探す（Grep）ことだけが許可されます。セキュリティや効率の観点から、スキルが必要とする最小限の機能だけを許可することができます。

description の書き方が最重要。 Claude はこれを読んで「いつ呼ぶか」を判断する。

この引用が示すように、descriptionフィールドの記述は最も重要です。AIであるClaudeは、この説明文を読み取ることで、ユーザーの要求に対してどのスキルを使うべきかを判断します。そのため、分かりやすく正確な説明を記述することが、AIを適切に活用するために不可欠です。

手動呼び出し

これは、システムやツール内で利用できる特定の機能（スキル）を、ユーザーがコマンドを入力して直接実行する方法について説明しています。

多くのシステムでは、対話型インターフェースやコマンド入力欄で「/」を入力すると、利用できるスキルのリストが表示されます。この機能を使うことで、どのような操作が可能であるかを簡単に確認し、必要なスキルを選んで実行できます。

例えば、以下のように特定のファイルを指定してコードを説明してもらうスキルを呼び出すことができます。


1> /explain-code src/auth.ts

上記のコマンドは、explain-codeというスキルを使って、srcフォルダ内にあるauth.tsというファイルを解説してもらうことを指示しています。

このコマンドを実行すると、以下のような出力結果が得られます。

出力結果
1**auth.ts の解説**
2
3一言でいうと: ユーザーのログイン認証を担当するファイルです。
4
5たとえ話: マンションのオートロックのようなもの。
6正しい鍵（パスワード）があれば中に入れます。
7
8全体の流れ:
9  入力 → バリデーション → DB照合 → トークン発行

この出力結果は、auth.tsファイルがどのような役割を持っているのか、そしてその内部でどのような処理が行われているのかを分かりやすく示しています。

auth.ts の解説：このファイルが「ユーザーのログイン認証」を行う中心的な役割を担っていることを説明しています。
全体の流れ：認証プロセスがどのように進むかを示しています。
- 入力: ユーザーがログイン情報（IDやパスワードなど）を入力する段階です。
- バリデーション: 入力された情報が正しい形式であるか、セキュリティ上の問題がないかなどをチェックする段階です。例えば、パスワードが指定された文字数以上であるかなどを確認します。
- DB照合 (データベースしょうごう): 入力されたユーザーIDとパスワードが、システムに登録されている情報と一致するかをデータベースで確認する段階です。
- トークン発行: 認証が成功した場合、ユーザーがシステム内で引き続き操作を行うための「トークン」と呼ばれる一時的な認証情報を発行する段階です。これにより、ユーザーは毎回ログイン情報を入力することなく、システムを利用できます。

$ARGUMENTS で引数を受け取る

システム開発において、プログラムに何らかの指示を出す際に、その指示に続けて追加の情報（引数）を与えることは非常に一般的です。ここで説明するのは、コマンドの後ろにテキストを入力し、そのテキストをプログラムがどのように受け取るか、という仕組みです。

例えば、以下のようなコマンドを想像してください。


1/explain-code src/auth.ts
2              ↑ ここが $ARGUMENTS

この例では、「/explain-code」というコマンドに、「src/auth.ts」という情報を追加で与えています。この追加の情報が「引数」です。プログラムは、この引数を受け取ることで、どのような処理を行うべきか判断できます。

引数を受け取るための変数

入力された引数は、以下のような特別な変数に格納されます。これらの変数をプログラム内で利用することで、入力されたテキストを処理できます。

変数	内容
`$ARGUMENTS`	入力されたテキスト全体
`$1`	最初のスペース区切りの値
`$2`	2番目の値
`${CLAUDE_SESSION_ID}`	現在のセッションID
`${CLAUDE_SKILL_DIR}`	SKILL.md が置かれているディレクトリ

それぞれの変数の内容について、詳しく見ていきましょう。

$ARGUMENTS: この変数は、コマンドに続いて入力されたすべてのテキストをそのまま受け取ります。上記の例「/explain-code src/auth.ts」の場合、「$ARGUMENTS」には「src/auth.ts」という文字列全体が入ります。もし「/search users name=Alice」と入力した場合、「$ARGUMENTS」には「users name=Alice」が入ることになります。
$1: この変数は、入力されたテキストをスペースで区切った際の、最初の部分を受け取ります。例えば、「/search users name=Alice」と入力した場合、「$1」には「users」が入ります。上記の例「/explain-code src/auth.ts」のように、スペースがない場合は、「$1」には「src/auth.ts」全体が入ります。
$2: この変数は、「$1」と同様に、スペースで区切られたテキストの2番目の部分を受け取ります。例えば、「/search users name=Alice」と入力した場合、「$2」には「name=Alice」が入ります。もし2番目の部分が入力されていない場合は、この変数は空になります。
${CLAUDE_SESSION_ID}: この変数は、現在実行しているセッションに割り当てられた**一意の識別子（ID）**を保持しています。セッションIDは、個々のやり取りや作業のまとまりを識別するために使われるもので、システムのログ記録や、特定のセッションに関連するデータを管理する際などに役立ちます。プログラムが、現在どのセッションで動作しているかを知るために利用されます。
${CLAUDE_SKILL_DIR}: この変数は、現在実行されている「スキル」やプログラムの定義ファイル（例えば「SKILL.md」）が置かれているディレクトリのパスを保持しています。プログラムが自分自身のファイルや、関連する設定ファイル、リソースなどを参照する必要がある場合に、このパスを利用して正確な場所を特定できます。

これらの引数や環境変数を適切に利用することで、プログラムはユーザーの意図を正確に理解し、柔軟な処理を実行できるようになります。

実例 2: コミットメッセージ生成

このセクションでは、プログラムの変更を記録する際に使用する「コミットメッセージ」を自動で生成する機能について学びます。コミットメッセージとは、Gitなどのバージョン管理システムで、どのような変更を行ったかを記録するための短い説明文のことです。このメッセージが適切であると、後から変更履歴を追う際に何が変更されたのかをすぐに理解できるため、非常に重要です。

この機能は、ステージングエリアに追加した変更内容を読み取り、適切なコミットメッセージの候補を提案してくれます。

.claude/skills/commit-message/SKILL.md


1---
2name: commit-message
3description: ステージされた変更からコミットメッセージを生成する。
4---
5
6git diff --staged の結果を読んで、
7コミットメッセージの候補を3つ作ってください。
8
9フォーマット： <種別>: <変更内容を一言で>
10
11種別: feat / fix / refactor / docs / test
12
13候補ごとに「なぜそのメッセージにしたか」を1行で添える。

上記は、この「コミットメッセージ生成」スキルを定義しているファイルです。このファイルには、スキルがどのように動作するかという情報が書かれています。

上記のコードブロックは、このスキルの具体的な動作内容を示しています。

name: commit-message：このスキルの名前が commit-message であることを示しています。
description: ステージされた変更からコミットメッセージを生成する。：このスキルが「ステージされた変更」という、プログラムに加えた変更内容のうち、次にコミット（変更の確定）する予定のものを元に、コミットメッセージを作成することを説明しています。
git diff --staged の結果を読んで、コミットメッセージの候補を3つ作ってください。：
- git diff --staged は、Gitコマンドの一つで、現在ステージングエリアにある変更（次回のコミットに含まれる変更）と、その一つ前のコミットとの差分を表示するものです。
- このスキルは、この差分を読み解き、変更内容を理解します。
- そして、その変更内容に基づいて、コミットメッセージの候補を3つ提案するように指示されています。
フォーマット： <種別>: <変更内容を一言で>：
- コミットメッセージは、この決められた形式に従って作成されます。
- まず「種別」を書き、その後にコロン（:）を挟んで「変更内容を一言で」簡潔に記述します。
- この統一されたフォーマットにより、コミットメッセージが一貫性のあるものになり、後から履歴を見たときに変更の種類がすぐにわかるようになります。
種別: feat / fix / refactor / docs / test：
- 「種別」には、以下のいずれかを使用します。
  - feat：新しい機能を追加した場合に使う種別です。
  - fix：プログラムのバグ（不具合）を修正した場合に使う種別です。
  - refactor：コードの内部構造を改善したり、整理したりした場合に使う種別です。機能自体は変更されません。
  - docs：ドキュメント（説明書やコード内のコメントなど）に関する変更の場合に使う種別です。
  - test：テストコードの追加や修正に関する変更の場合に使う種別です。
候補ごとに「なぜそのメッセージにしたか」を1行で添える。：
- 提案される3つのコミットメッセージの候補それぞれに対して、なぜそのメッセージが適切だと判断されたのか、理由が1行で説明されます。これにより、提案されたメッセージが変更内容に合っているかを判断しやすくなります。

このスキルは、引数を何も指定しなくても動かすことができます。単に /commit-message と入力するだけで、現在のステージされた変更からコミットメッセージの候補を生成してくれます。これにより、手動でコミットメッセージを考える手間を省き、より効率的に作業を進めることができます。

自動委譲（Claudeが勝手に呼ぶ）

description とは、AI（Claude）の「スキル」や「機能」がどのような目的を持っているかを説明するための記述です。この description をあらかじめ設定しておくと、ユーザーとの会話の流れ（文脈）から、AIが判断して自動的にそのスキルを呼び出して実行します。

例えば、以下の会話例を見てみましょう。


1> auth.ts のコード、どういう仕組みか教えてもらえますか？

上記の質問に対して、AIは description に「コードを解説する」といった内容が書かれたスキルがある場合、それを自動で実行します。その結果が以下のように表示されます。

出力結果
1✓ explain-code スキルを自動で呼び出し中...
2
3auth.ts の解説
4一言でいうと: ...

この例では、ユーザーが「auth.ts のコードについて教えてほしい」と質問したことで、AIが自動的に「explain-code」という、コードを解説するスキルを呼び出しています。ユーザーが明示的に「explain-code スキルを使ってください」と指示しなくても、AIが会話の内容から意図を読み取って判断しているのです。

このように、description を用いた自動委譲の機能は、AIとのやり取りをスムーズにし、ユーザーの手間を省くという点で非常に便利です。しかし、便利な一方で注意が必要な点もあります。

AIが会話の文脈を誤って解釈したり、意図しないタイミングで特定のスキルを呼び出してしまったりする危険性があるためです。もし、そのスキルがシステムの設定を変更する、ファイルを削除する、外部サービスと連携して情報を提供するなど、何らかの操作を伴うものであった場合、ユーザーが予期しない危険な操作まで自動で実行されてしまう可能性があります。

そのため、description を設定してスキルを自動で呼び出す仕組みを導入する際は、そのスキルがどのような操作を行うのかを慎重に設計し、誤作動によるリスクを最小限に抑える対策を講じることが重要になります。

自動委譲を止める：disable-model-invocation

取り消しできない操作は 必ず手動で呼ぶ ようにします。

システムを開発する際、AI（人工知能）が特定のタスクを自動で実行する機能は非常に便利です。しかし、中には「一度実行すると元に戻せない」「重大な影響を及ぼす可能性がある」といった、注意が必要な操作も存在します。例えば、データベースの全データを削除したり、システム上の重要なファイルを削除したりする操作がこれにあたります。

このような取り消しできない操作をAIが勝手に判断して実行してしまうと、予期せぬ問題が発生する可能性があります。そのため、開発者はAIがそのような危険な操作を自動で実行しないよう設定し、ユーザー（人間）が明確に指示した場合にのみ実行されるように制御する必要があります。

この制御を実現するための設定が disable-model-invocation: true です。これにより、AI（モデル）がプログラマーが定義した「スキル」（特定の処理を実行する機能）を自動的に判断して呼び出す「自動委譲」の動きを停止させることができます。

以下に、データベースをリセットするスキルを例に説明します。


1---
2name: reset-db
3description: テスト用データベースを初期状態にリセットする
4disable-model-invocation: true
5---
6
7テスト用データベースをリセットします。
8
91. 現在のデータ件数を確認して報告する
102. 全テーブルのデータを削除する（TRUNCATE）
113. 初期データ（seed）を投入する
124. 件数を再確認して完了を報告する

このMarkdown形式で書かれた内容は、AIが実行できる「reset-db」という名前のスキルを定義しています。

name: スキルの名前です。この場合は「reset-db」という名前です。
description: スキルの説明です。このスキルが「テスト用データベースを初期状態にリセットする」ものであると記述されています。
disable-model-invocation: true: この設定が特に重要です。これが true に設定されていることで、AI（モデル）はユーザーの発言内容に基づいて、この「reset-db」スキルを自動で呼び出すことはありません。

もしこのスキルが disable-model-invocation: true の設定なしに定義されていた場合、AIはユーザーのあいまいな指示から「データベースをリセットしたい」と解釈し、自動でこのスキルを実行しようとする可能性があります。しかし、この設定があることで、そのような自動実行が防がれます。

実際にユーザーがAIに対して、データベースのリセットを意図するような発言をした場合の例を見てみましょう。


1> テストデータをきれいにしてください

上記のように、ユーザーが「テストデータをきれいにしてください」とAIに依頼した場合、AIはどのように応答するでしょうか。

出力結果
1[reset-db は呼ばれない。通常の会話として応答する]
2「どのテーブルをリセットしますか？」

disable-model-invocation: true の設定があるため、AIは「テストデータをきれいにしてください」というユーザーの曖昧な指示に対して、「reset-db」スキルを自動で呼び出すことはありません。代わりに、「どのテーブルをリセットしますか？」のように、より具体的な情報をユーザーに尋ねることで、通常の会話として応答を続けます。これは、AIがユーザーの意図を確認し、誤って取り返しのつかない操作を実行することを避けるための安全策です。

では、ユーザーが明示的にこのスキルを呼び出したい場合はどうすればよいでしょうか。その場合は、スラッシュ（/）を使ったコマンドでスキル名を指定します。

明示的に呼んだときだけ動く：


1> /reset-db
2✓ reset-db スキル実行中...

このように、ユーザーが「/reset-db」と明確にコマンドを入力した場合にのみ、AIはこの「reset-db」スキルを実行します。これにより、開発者は危険な操作が意図しないタイミングで実行されることを防ぎつつ、必要な時にはユーザーの明確な指示に基づいてスキルを実行させることができます。

注意: DBリセット・ファイル削除・外部API送信など、取り消しが難しい操作には必ず disable-model-invocation: true を付けます。

システムエンジニアとして、取り消しが難しい操作や、システム全体に影響を与える可能性のある操作を定義する際には、必ず disable-model-invocation: true を設定し、AIが自動で判断して実行することを防ぐようにしましょう。これは、システムを安全に運用するための非常に重要なベストプラクティスです。

使い分けの基準

AIモデルをシステム開発に活用する際、そのモデルが外部のシステムに対して操作を実行する能力をどのように管理するかが非常に重要になります。以下の表は、AIモデルが外部の機能やシステムに指示を出すことを許可するかどうかを制御する「disable-model-invocation」という設定の使い分けの基準を示しています。

用途	設定
コード解説・レビュー・生成など安全な操作	`disable-model-invocation` なし
DBリセット・ファイル削除など取り消せない操作	`disable-model-invocation: true`

この表の内容を解説する。

「disable-model-invocation」という設定は、AIモデルが外部のシステムやツールに対して、何らかの操作を実行する指示を出す能力を持っているかどうかを制御するためのものです。

コード解説・レビュー・生成など安全な操作の場合

設定: disable-model-invocation なし
この設定は、AIモデルが外部のシステムに対して操作指示を出す能力を「有効にする」、または「制限しない」という意味です。
コードの解説を依頼したり、既存のコードをレビューさせたり、新しいコードのアイデアを生成させたりする作業は、基本的にシステム自体に直接的な変更を加えるものではありません。AIは与えられた情報を分析し、テキストやコードといった出力を生成するだけで、実際にデータベースをリセットしたり、サーバー上のファイルを削除したりするわけではありません。
これらの操作では、AIの持つ情報処理能力や生成能力を最大限に活用したいので、特に外部システムへの操作を制限する必要はないと判断されます。

DBリセット・ファイル削除など取り消せない操作の場合

設定: disable-model-invocation: true
この設定は、AIモデルが外部のシステムに対して操作指示を出す能力を「無効にする」という意味です。つまり、AIがシステムに対して何かを実行することを禁止します。
データベースのリセットやサーバー上のファイルの削除といった操作は、一度実行してしまうと元に戻すことが非常に困難、あるいは不可能な、非常に重大な操作です。もしAIが何らかの原因で誤ってこのような指示を出してしまった場合、システム全体に深刻な損害を与える可能性があります。
このような取り返しのつかない操作については、AIに実行権限を与えず、必ず人間が内容を十分に確認し、最終的に手動で実行するようにします。これは、AIによる予期せぬ誤操作を防ぎ、システムの安全性と信頼性を確保するための非常に重要な対策です。

このように、「disable-model-invocation」の設定を適切に使い分けることで、AIモデルの持つ便利な機能を安全に活用し、システムへのリスクを最小限に抑えることができます。システムエンジニアとしてAIツールを安全に利用するために、この基準を理解しておくことは非常に大切です。

よくあるトラブルと対処

スキルが認識されない

設定した新しい機能や命令（スキル）が、システムに反映されないトラブルです。

原因: セッションが始まった時点で存在しなかったトップレベルの skills ディレクトリを新しく作成した場合、Claude Code がそのディレクトリを監視できていないことが原因です。

対処: skills ディレクトリ自体を新しく作った直後は、Claude Code を再起動するか、新しくセッションを開き直してください。これにより、新しいディレクトリが監視対象になります。

なお、~/.claude/skills/ やプロジェクトの .claude/skills/ が既にある状態でスキルファイルを追加・編集・削除した場合は、現在のセッション内で変更が検出されるため、再起動は不要です。

引数を渡しても無視される

AIに何か指示を出す際に、具体的な情報（引数）を伝えているにもかかわらず、その情報が無視されてしまうトラブルです。引数とは、例えば「このファイル」や「このデータ」といった、AIが処理する対象となる具体的な内容を指します。

原因: 指示の本文に $ARGUMENTS という特別な記述が含まれていないことが原因です。$ARGUMENTS は、AIが指示された引数をどこに当てはめて処理すればよいかを示す目印。この目印がないと、AIは受け取った引数をどこに使えば良いか分からず、結果的に無視してしまいます。


1# NG                           # OK
2対象ファイルを解説してください    対象: $ARGUMENTS を解説してください

上記 NG の例では、「対象ファイルを解説してください」とだけ書かれており、AIは具体的にどの「対象ファイル」を解説すれば良いか認識できません。一方 OK の例では、「対象: $ARGUMENTS を解説してください」と記述することで、$ARGUMENTS の部分に渡された具体的なファイル名が入ることをAIが理解し、正しく処理できるようになります。

おわりに

本記事では、Claude Code Skillsを利用して、AIへの繰り返し指示を効率化する方法を詳しく解説しました。Markdownファイルでスキルを作成し、/コマンドとして手動で呼び出すだけでなく、descriptionの設定によってClaudeが自動でスキルを実行することも可能になります。しかし、$ARGUMENTSで引数を渡す際には適切な記述が必要であり、データベースリセットのような取り返しのつかない操作ではdisable-model-invocation: trueを設定して安全性を確保することが重要です。