Skills

スキルは、決まった作業の手順や、参照したい知識を、1 つのフォルダーにまとめておき、必要なときだけ Claude に読み込ませる仕組みです。05. CLAUDE.md とメモリ で扱った CLAUDE.md は、すべてのセッションで読み込まれます。スキルは、使うときにだけ中身が読み込まれるので、長い手順を置いておいても、普段のコンテキストをほとんど使いません。このページでは、スキルの仕組みと作り方を整理し、このサイトのリポジトリで実際に 1 つ作ります。

この記事で分かること

• スキルとは何か。CLAUDE.md との使い分け
• スキルを置く場所と、効く範囲
• SKILL.md の書き方と、主な設定の項目
• スキルが使われ始める 2 つのきっかけと、その制限のしかた
• 作ったスキルを、Claude が期待どおりに使わないときの、原因と対処

用語の整理

用語	意味
スキル（skill）	手順や知識をまとめた、Claude に読み込ませるためのフォルダー。中心になるのは SKILL.md というファイル
SKILL.md	スキルの本体。先頭に設定を書き、そのあとに、Claude への指示を Markdown で書く
フロントマター（frontmatter）	ファイルの先頭に、--- の行で挟んで書く設定の部分。YAML という形式で書く
説明（description）	そのスキルが何をするもので、いつ使うものかを書いた文。Claude は、これを見て、スキルを使うかどうかを決める
呼び出す（invoke）	スキルを使い始めること。利用者が /スキル名 と入力する方法と、Claude が自分で読み込む方法がある
同梱のスキル（bundled skill）	Claude Code に最初から入っているスキル
引数（argument）	スキルを呼び出すときに、名前のあとに付けて渡す情報

スキルとは

スキルは、SKILL.md というファイルを入れたフォルダーです。Claude は、会話の内容がスキルの説明に当てはまるときに、そのスキルを自分で読み込みます。利用者が、/スキル名 と入力して、直接呼び出すこともできます。

公式ドキュメントは、スキルを作るきっかけを、次のように説明しています。

• 同じ指示、チェックリスト、複数の手順からなる作業を、何度も会話に貼り付けている
• CLAUDE.md の中のある部分が、事実ではなく、手順の説明に育ってきた

CLAUDE.md との使い分け

	CLAUDE.md	スキル
読み込まれるとき	すべてのセッションの初めに、全文	普段は、名前と説明だけ。中身は、呼び出されたとき
向いている内容	すべてのセッションで知っておくべき事実。コマンド、決まり、構成	特定の作業の手順。必要なときだけ使う知識
コンテキストの使い方	書いた分だけ、毎回使う	呼び出すまでは、ほとんど使わない

CLAUDE.md には「何が決まっているか」を書き、スキルには「この作業は、こう進める」を書く、と分けると、整理しやすくなります。

同梱のスキル

Claude Code には、最初からいくつかのスキルが入っています。公式ドキュメントが例として挙げているのは、/doctor（設定の点検）、/code-review（コードの確認）、/debug、/loop などです。呼び出し方は、自分で作ったスキルと同じで、/ に続けて名前を入力します。

以前は「カスタムコマンド」と呼ばれていた仕組み（.claude/commands/ にファイルを置く方法）は、スキルに統合されました。以前のファイルは、そのまま動きます。新しく作る場合は、スキルの形にします。

スキルを置く場所

スキルは、置く場所によって、読み込まれる範囲が変わります。考え方は、設定ファイルや CLAUDE.md と同じです。

範囲	場所	読み込まれるセッション
組織	管理設定のフォルダーの中の .claude/skills/<スキル名>/SKILL.md	組織が配布した、すべての利用者
個人	~/.claude/skills/<スキル名>/SKILL.md	この PC の、自分のすべてのプロジェクト
プロジェクト	プロジェクトの .claude/skills/<スキル名>/SKILL.md	そのリポジトリでのセッション。コミットすると、チームの全員に届く
プラグイン	プラグインの中の skills/<スキル名>/SKILL.md	そのプラグインを有効にしたところ

プラグインは、スキルなどをまとめて配布するための仕組みです。「10. Plugins と「カスタマイズ」」で扱う予定です。

セッションの途中での変更

Claude Code は、スキルのフォルダーを見張っています。~/.claude/skills/ やプロジェクトの .claude/skills/ の中でスキルを追加、編集、削除すると、セッションを始め直さなくても、反映されます。

ただし、1 つ例外があります。セッションを始めたときに、skills フォルダーそのものがまだなかった場合です。この場合、Claude Code は、そのフォルダーを見張っていません。あとから作ったフォルダーの中のスキルを読み込むには、/reload-skills コマンドを実行します。

SKILL.md の書き方

SKILL.md は、2 つの部分からなります。

---
name: api-conventions
description: このコードベースでの API の設計の決まり。API のエンドポイントを書くときに使う。
---

API のエンドポイントを書くときは、次に従う。

- 名前の付け方は、REST の慣習に合わせる
- エラーは、決まった形式で返す
- 入力の検証を入れる

• --- で挟まれた部分（フロントマター）：スキルの設定。Claude が、いつこのスキルを使うかを判断する材料になる。
• そのあとの部分：スキルが呼び出されたときに、Claude が従う指示。

フロントマターの項目は、すべて省略できます。公式ドキュメントが書くことを勧めているのは、description だけです。

主な項目

項目	働き
name	/ のあとに入力する名前。省略すると、フォルダーの名前が使われる
description	何をするスキルで、いつ使うか。Claude は、これを見て、スキルを使うかどうかを決める。いちばん大事な使いみちを、先頭に書く
when_to_use	Claude が使うべき場面の補足。きっかけになる言い回しや、依頼の例
argument-hint	入力の補完のときに表示される、引数の案内。例：[ファイル名]
disable-model-invocation	true にすると、Claude が自分では読み込まなくなる。利用者が /名前 と入力したときだけ動く
user-invocable	false にすると、利用者が /名前 で呼び出せなくなる。Claude だけが読み込む
allowed-tools	このスキルを呼び出した回の応答の間、確認なしで使えるツール
paths	ファイルのパターン。当てはまるファイルを扱っているときだけ、Claude が自動で読み込む
context	fork にすると、別のコンテキスト（サブエージェント）で実行する

項目の名前は、表のとおりに正確に書く必要があります。Claude Code は、知らない名前の項目を、誤りとして知らせずに、無視します。

説明が、いちばん大事

普段のセッションで、コンテキストに入っているのは、それぞれのスキルの名前と説明だけです。Claude は、この説明を見て、今の依頼にスキルが当てはまるかを判断します。そのため、説明には、次の 2 つを書きます。

• 何をするスキルか
• どんなときに使うか（利用者が、実際に口にしそうな言葉を入れる）

スキルの数が多くなると、説明の一覧が長くなりすぎないように、一部の説明が省かれることがあります。説明は、大事なことから先に書きます。

本文は、短く書く

スキルは、一度読み込まれると、その内容が会話の中に残り続けます。つまり、本文の 1 行 1 行が、そのあとの応答のたびに、コンテキストを使います。公式ドキュメントは、やり方や理由を長く説明するのではなく、何をするかを書くように勧めています。

長い資料や例は、同じフォルダーの中の別のファイルに分けられます。

my-skill/
├── SKILL.md       全体の説明と、ほかのファイルへの案内
├── reference.md   詳しい資料。必要なときだけ読まれる
└── scripts/
    └── helper.py  実行するためのスクリプト

SKILL.md の中で、それぞれのファイルに何が書いてあり、いつ読むべきかを案内しておくと、Claude が、必要なときにだけ読みます。

引数を渡す

スキルを呼び出すときに、名前のあとに情報を付けられます。本文の中に $ARGUMENTS と書いておくと、その部分が、渡された内容に置き換わります。

---
name: fix-issue
description: GitHub の Issue を修正する
---

GitHub の Issue $ARGUMENTS を修正する。

/fix-issue 123 と入力すると、本文は「GitHub の Issue 123 を修正する。」として、Claude に渡されます。

スキルが使われ始める、2 つのきっかけ

スキルが使われ始めるきっかけは、2 つあります。

きっかけ	内容	例
利用者が、名前を入力する	入力欄に、/スキル名 と入力する	/deploy と入力する
Claude が、自分で判断する	会話の内容が、スキルの説明に当てはまると Claude が判断して、スキルを読み込む	「変更した内容をまとめて」と頼むと、変更をまとめるスキルが使われる

何も設定しなければ、どのスキルも、両方のきっかけで使われます。

きっかけを、片方だけにする

スキルによっては、片方のきっかけだけにしたほうがよいものがあります。フロントマターの項目で、制限できます。

利用者が入力したときだけ、使われるようにする

---
name: deploy
description: アプリケーションを本番の環境にデプロイする
disable-model-invocation: true
---

disable-model-invocation: true を書くと、Claude は、このスキルを自分の判断では使わなくなります。使われるのは、利用者が /deploy と入力したときだけです。

外部に影響する作業のスキルには、この設定を付けます。デプロイ、コミット、メッセージの送信などです。公式ドキュメントは、「コードの準備ができたように見えるからといって、Claude にデプロイを決めさせたくはない」と説明しています。

Claude が判断したときだけ、使われるようにする

---
name: legacy-system-context
description: 古いシステムの仕組みの説明
user-invocable: false
---

user-invocable: false を書くと、利用者が /名前 と入力しても、動かなくなります。背景の知識のように、Claude には必要なときに読んでほしいが、利用者がコマンドとして実行する意味はない、というスキルに使います。

まとめると、次のようになります。

設定	利用者の入力で使われるか	Claude の判断で使われるか	向いているスキル
何も書かない	使われる	使われる	害のない作業。参照する知識
disable-model-invocation: true	使われる	使われない	外部に影響する作業
user-invocable: false	使われない	使われる	背景の知識

スキルに、確認なしで使えるツールを持たせる

フロントマターの allowed-tools にツールを書くと、そのスキルが使われた回の応答の間、書かれたツールを、確認なしで使えるようになります。たとえば、コミットのスキルに、git のコマンドを書いておく使い方があります。

---
name: commit
description: 今の変更をステージして、コミットする
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

この項目は、許可を広げるものなので、注意が必要です。公式ドキュメントによると、プロジェクトのスキルの allowed-tools は、そのフォルダーについて信頼の確認を承認していなくても、適用されます。スキルは、自分自身に広い許可を与えることができてしまいます。ほかの人が作ったリポジトリで Claude Code を使う前に、コミットされているスキルの allowed-tools を確かめておきます。

どのスキルが使われても確実に止めたいツールは、03. 権限モードと、確認を減らす方法 で見た、権限の設定の deny ルールに書きます。

作ったスキルを、Claude が期待どおりに使わないとき

スキルを作っても、Claude が、作った人の期待どおりに使うとはかぎりません。スキルは、Claude が説明を読んで、使うかどうかを判断する仕組みだからです。起きやすい困りごとは、次の 4 つです。それぞれ、原因と対処が違います。

Claude が、スキルを使わない

使ってほしい場面なのに、Claude がスキルを使わずに、作業を進めてしまう場合です。Claude は、スキルの説明（description）を見て判断しているので、まず、説明を見直します。

原因	対処
説明に、依頼で使う言葉が入っていない	説明に、利用者が実際に言いそうな言葉を入れる
フロントマターの書き方に誤りがあり、説明が読み込まれていない	--- が、ファイルの 1 行目にあるかを確かめる。YAML の書き方を確かめる。フロントマターが読めないと、本文だけが読み込まれて、説明が空になる

説明を直しても使われないときは、/スキル名 と入力すれば、利用者の側から、確実に使い始められます。

作ったスキルが、一覧に出てこない

/ を入力しても、作ったスキルが候補に出てこない場合です。

原因	対処
セッションを始めた時点で、skills フォルダーがなかった	/reload-skills を入力する。または、セッションを始め直す

Claude が、使ってほしくない場面でも、スキルを使う

関係のない依頼でも、Claude がスキルを読み込んでしまう場合です。

原因	対処
説明が広すぎて、多くの依頼に当てはまってしまう	説明を、具体的な場面に絞る
そもそも、Claude の判断で使われては困るスキルである	disable-model-invocation: true を付けて、利用者が入力したときだけ使われるようにする

Claude が、途中からスキルの指示に従わなくなる

最初はスキルの手順に従っていたのに、会話が長くなると、従わなくなる場合です。

スキルの内容は、使い始めたときに 1 回だけ、会話の中に読み込まれます。そのあとで、ファイルが読み直されることはありません。会話が長くなって、圧縮（古い内容の要約）が行われると、スキルの内容は、先頭の部分しか残らないことがあります。

原因	対処
圧縮で、スキルの内容の後ろの部分が失われた	もう一度、スキルを使い始める。大事な指示は、SKILL.md の先頭の近くに書く
毎回、必ず守らせたい決まりを、スキルに書いている	スキルは、強制ではない。必ず守らせたいことは、フックに書く（「09. Hooks」で扱う予定）

実際にやってみる

このサイトのリポジトリで、スキルを 1 つ作り、実際に使いました。作ったスキル、試したこと、想定していなかったこと、あとから確かめたこと、の順に書きます。

1. 作ったスキル

名前は、register-page です。書き終えた新しいページを、サイトから見られる状態にする作業をまとめました。

このサイトでは、ページを書き終えるたびに、次の作業をしています。

• サイトの 3 か所（テーマの一覧、サイドバー、トップページの新着記事）に、ページへのリンクを追加する
• サイトをビルドする
• 確認用のサーバーを起動し直して、ページが表示されることを確かめる

05 で作った CLAUDE.md には、「3 か所を更新する」という事実だけを書きました。その具体的な手順を、スキルにしました。

コミットと公開は、スキルに含めていません。外部に影響する作業を含めると、利用者が入力したときだけ使われる設定（disable-model-invocation: true）が必要になります。外部に影響しない範囲だけにして、Claude の判断でも使えるスキルにしました。

スキルの実体は、.claude/skills/register-page/SKILL.md という、ファイル 1 つです。全文は、次のとおりです。

---
name: register-page
description: study-lab のサイトに、書き終えた新しいページを登録する。テーマの一覧、サイドバー、トップページの新着記事の 3 か所にリンクを追加し、ビルドして、確認用のサーバーで表示を確かめる。新しいページを書き終えたとき、または「ページを登録して」と頼まれたときに使う。
argument-hint: "[ページのファイルのパス]"
---

# 新しいページをサイトに登録する

対象のページ：$ARGUMENTS
（指定がなければ、`git status` で、`docs/` 以下に新しく追加された Markdown を対象にする）

次の順に行う。コミット、push、プルリクエストの作成は、この手順には含めない。

1. 対象のページの 1 行目（`# ` で始まる行）から、ページのタイトルを読む。
2. テーマのトップページ `docs/<テーマ>/index.md` の一覧で、対象のページの行を直す。
   - タイトルを、ページへのリンクにする（例：`[タイトル](./ファイル名)`。拡張子の `.md` は付けない）
   - 状態を「準備中」から「公開済み」に変える
3. サイドバー `docs/.vitepress/config.mts` の、対象のテーマのグループに、ページを追加する。
   - 番号のあるテーマでは、番号の順になる位置に入れる
4. トップページ `docs/index.md` の「新着記事」の表の、いちばん上に行を追加する。
   - 形：`| 今日の日付（YYYY-MM-DD） | テーマの名前 | [タイトル](./テーマ/ファイル名) |`
5. `npm run docs:build` を実行して、成功することを確かめる。
6. 確認用のサーバーを起動し直す。
   - 動いていれば止めてから、`npm run docs:preview -- --port 4173` を起動する
7. 次の 2 点を確かめる。
   - `http://localhost:4173/study-lab/<テーマ>/<ファイル名>` が表示される
   - テーマのトップページと、サイトのトップページに、対象のページへのリンクがある
8. 行った変更（3 か所）と、確認用の URL を、利用者に伝える。

フロントマターの description には、「新しいページを書き終えたとき」「ページを登録して」という、使う場面の言葉を入れました。本文の $ARGUMENTS は、対象のページを受け取るための部分です。

2. 試したこと

2 つのことを試しました。

試したこと	方法	結果
作ったスキルを、名前の入力で使えるか	入力欄に、/register-page docs/claude-code/06-skills.md と入力した。対象は、このページ自身	使えた
スキルの手順のとおりに、作業が進むか	Claude が、手順を上から順に行った	最後まで進んだ

名前を入力したとき、Claude に渡されたのは、SKILL.md の本文でした。本文の中の $ARGUMENTS は、入力したパスに置き換わっていました。

対象のページ：docs/claude-code/06-skills.md

手順ごとの結果は、次のとおりです。

手順	結果
1. タイトルを読む	「Skills」
2. テーマの一覧を直す	06 の行にリンクを付け、「公開済み」に変えた
3. サイドバーに追加する	05 の次に追加した
4. 新着記事に追加する	表のいちばん上に追加した
5. ビルドする	成功
6. 確認用のサーバーを起動し直す	起動した
7. 表示を確かめる	ページが表示された。テーマのトップページと、サイトのトップページに、リンクがあった
8. 利用者に伝える	変更した 3 か所と、確認用の URL を伝えた

コミットや公開は、行われませんでした。手順に含めていないためです。

3. 想定していなかったこと

1 つ、ありました。作った直後は、スキルを使えませんでした。

項目	内容
起きたこと	スキルのファイルを作ってすぐに使おうとすると、Unknown skill: register-page（そのスキルは存在しない）という結果になった
原因	Claude Code は、スキル用のフォルダーを見張っていて、普通は、新しいスキルにすぐ気づく。ただし、セッションを始めた時点で、そのフォルダーがなかった場合は、見張っていない。今回は、.claude/skills/ フォルダーごと新しく作ったので、これに当たった
対処	入力欄に、/reload-skills（スキルを読み込み直すコマンド）を入力した。Reloaded skills: 34 skills available (1 added) と表示され、使えるようになった
今後	このリポジトリでは、もう起きない。フォルダーができたので、次からは、新しいスキルにすぐ気づく

これは、公式ドキュメントに書かれているとおりの動きです（上の「セッションの途中での変更」を参照）。

4. あとから確かめたこと：Claude の判断で、スキルが使われるか

このページを書いた時点では、利用者が名前を入力して、スキルを使い始めました。Claude が、自分の判断でスキルを使い始める動きは、次のページ（07. MCP とコネクター）を書き終えたときに、確かめました。

項目	内容
状況	Claude が、07 のページの本文を書き終えた。利用者は、スキルの名前を入力していない
Claude がしたこと	スキルの一覧にある register-page の説明（「新しいページを書き終えたとき…に使う」）が、今の状況に当てはまると判断して、自分でスキルを使い始めた。対象のページのパスも、引数として自分で渡した
結果	スキルの本文が読み込まれ、手順のとおりに、3 か所へのリンクの追加、ビルド、表示の確認まで進んだ

スキルの内容は、このページのときに、すでに 1 回読み込まれていました。2 回目は、引数（対象のページ）が違うので、本文の全体が、もう一度読み込まれました。上の「Claude が、途中からスキルの指示に従わなくなる」で見た、「スキルの内容は、使い始めたときに読み込まれる」という動きのとおりです。

5. スキルを、リポジトリで共有するための変更

スキルとは別に、設定を 1 つ変えました。

04. 設定ファイルの仕組み で確かめたとおり、このリポジトリでは、.gitignore で .claude フォルダーの全体を、Git の管理の対象から外していました。スキルは、その中にあるので、そのままでは、リポジトリに入りません。

.gitignore を、次のように書き換えました。

.claude/*
!.claude/skills/

1 行目で、.claude の中のものをすべて外し、2 行目で、スキルのフォルダーだけを、管理の対象に戻しています。PC ごとに内容が違うファイル（プレビュー用の設定など）は、これまでどおり、対象から外れたままです。

まとめ

• スキルは、手順や知識をまとめた SKILL.md を、フォルダーに入れたもの。普段は名前と説明だけが読み込まれ、中身は、呼び出されたときに読み込まれる。
• すべてのセッションで必要な事実は CLAUDE.md に、特定の作業の手順はスキルに書く。
• 置く場所で、範囲が決まる。個人のスキルは ~/.claude/skills/、プロジェクトのスキルは .claude/skills/。
• 説明（description）が、Claude がスキルを使うかどうかの判断の材料になる。何をするか、いつ使うかを、具体的に書く。
• スキルが使われ始めるきっかけは、利用者が名前を入力することと、Claude が自分で判断することの 2 つ。外部に影響する作業のスキルは、disable-model-invocation: true を付けて、利用者が入力したときだけ使われるようにする。
• allowed-tools は、許可を広げる項目である。ほかの人が作ったスキルを使う前に、内容を確かめる。

確認の記録

• Extend Claude with skills（Claude Code Docs）

項目	内容
最終確認日	2026 年 10 月 13 日
Claude Code のバージョン	2.1.295（macOS のデスクトップアプリ）
検証の状況	「実際にやってみる」は、macOS のデスクトップアプリと、このサイトのリポジトリで確かめた結果。プロジェクトのスキルを作り、/reload-skills で読み込み、/スキル名 で呼び出して、手順のとおりに動くことを確かめた。Claude が、説明をもとに、自分でスキルを使い始めることも、次のページを書いたときに確かめた。それ以外の節は、公式ドキュメントの内容をもとに書いている
確かめていない内容	同梱のスキル、個人のスキル、allowed-tools、disable-model-invocation、paths、context: fork、補助のファイルは、実際には操作していない