はじめてのスキルを作る

スキル（Skill）は、Claude Code に手順や知識を覚えさせるしくみです。SKILL.md というファイルを1つ置くだけで、Claude はそれを自分の道具として使えるようになります。この記事では、公式ドキュメントに沿って実際に動くスキルを1つ作り、置き場所による優先順位までを確認します。

スキルとは何か

スキルは Claude の能力を拡張するしくみです。指示を書いた SKILL.md ファイルを作ると、Claude はそれを自分の道具箱に加えます。Claude が関連すると判断したときに自動で使うほか、/skill-name の形で直接呼び出すこともできます。

スキルを作るべきタイミングは、公式ドキュメントがはっきり示しています。同じ指示・チェックリスト・複数手順の作業を何度もチャットに貼り付けているとき、あるいは CLAUDE.md のある節が「事実」ではなく「手順」に育ってしまったときです。

ここで CLAUDE.md との違いが効いてきます。CLAUDE.md の内容は常に読み込まれますが、スキルの本文は使われるときだけ読み込まれます。したがって長い参照資料をスキルに置いておいても、必要になるまでコストはほとんどかかりません。手順書や長い規約をコンテキストに常駐させたくない場合、置き場所としてスキルのほうが適しています。

なお、カスタムコマンドはスキルに統合されました。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy を作り、同じように動きます。既存の .claude/commands/ のファイルはそのまま動き続けます。スキル側が持つ追加機能は、補助ファイルを置けるディレクトリ、呼び出し主体を制御するフロントマター、そして Claude が関連時に自動で読み込めることの3点です。

Claude Code のスキルは Agent Skills というオープン標準に従っており、複数の AI ツールで通用します。そのうえで Claude Code は、呼び出し制御、サブエージェント実行、動的コンテキスト注入といった独自の拡張を加えています。

はじめてのスキルを作る

公式ドキュメントの入門例をそのまま作ってみます。Git リポジトリの未コミットの変更を要約し、危なそうな箇所を指摘するスキルです。ポイントは、Claude が読む前に実際の差分をプロンプトへ引き込むところにあります。開いているファイルから推測させるのではなく、実際の作業ツリーに基づいた回答になります。

手順1: スキルのディレクトリを作る

個人用のスキルフォルダに、スキル1つぶんのディレクトリを作ります。個人用スキルは、すべてのプロジェクトで使えます。

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

手順2: SKILL.md を書く

すべてのスキルには SKILL.md が必要です。中身は2つの部分からなります。--- で囲んだ YAML フロントマター（そのスキルをいつ使うかを Claude に伝える部分）と、スキルが実行されたときに Claude が従う指示を書いたマークダウン本文です。ディレクトリ名がそのままコマンド名になり、description が自動読み込みの判断材料になります。

次の内容を ~/.claude/skills/summarize-changes/SKILL.md に保存します。

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

!`git diff HEAD` の行が動的コンテキスト注入です。Claude Code がこのコマンドを実行し、Claude がスキルの内容を見る前に、その行を出力で置き換えます。つまり指示が届いた時点で、現在の差分が既に埋め込まれています。

手順3: 動かして確かめる

Git のプロジェクトを開いて適当なファイルを少し編集し、claude を実行して Claude Code を起動します。試し方は2通りあります。ひとつは、description に合う聞き方をして自動で呼び出させる方法です。

What did I change?

もうひとつは、スキル名で直接呼び出す方法です。

/summarize-changes

どちらの場合も、Claude は編集内容の短い要約とリスクの一覧を返すはずです。

SKILL.md の構造

スキルはディレクトリであり、SKILL.md がその入口です。公式ドキュメントが示す構成は次のとおりです。

my-skill/
├── SKILL.md           # 主要な指示（必須）
├── template.md        # Claude が埋めるテンプレート
├── examples/
│   └── sample.md      # 期待する出力形式を示す例
└── scripts/
    └── validate.sh    # Claude が実行できるスクリプト

必須なのは SKILL.md だけです。ほかのファイルは任意で、テンプレート、期待する出力形式を示す例、Claude が実行できるスクリプト、詳細な参照資料などを置けます。これらのファイルは SKILL.md から参照してください。何が書いてあり、いつ読めばよいかを Claude が知るためです。

入門例のフロントマターは description だけでした。最小構成としてはこれで足ります。description は「何をするか」に加えて「どういうときに使うか」まで書くのがコツで、公式の例も後半で Use when the user asks what changed... と用途を明示しています。自動読み込みの判断はこの文面で行われるため、ここが曖昧だと呼ばれるべきときに呼ばれません。

なお .claude/commands/ のファイルも同じフロントマターに対応していますが、name と paths だけはコマンドファイルでは無視されます。コマンドファイルはファイル名で呼び出します。補助ファイルなどの追加機能があるため、公式はスキルのほうを推奨しています。

スキルの置き場所と優先順位

どこに置くかで、誰が使えるかが決まります。

名前が衝突したときの解決順は、直感と逆になりやすいので注意してください。階層をまたぐ場合、エンタープライズが個人を上書きし、個人がプロジェクトを上書きします。つまり ~/.claude/skills/ とプロジェクトの .claude/skills/ の両方に deploy スキルがあるとき、/deploy で動くのは個人のほうです。プロジェクト側が勝つと思い込んでいると、意図しないスキルが動きます。

そのほかの規則は次のとおりです。

• 上記いずれかの階層に置いたスキルは、同名の同梱スキル（bundled skill）も上書きします。ただし同梱スキルの別名（エイリアス）は上書きしません。たとえばプロジェクトの code-review スキルは同梱の /code-review を置き換えますが、同梱の別名 /review と打っても自作スキルは動きません。
• プラグインのスキルは plugin-name:skill-name という名前空間を使うため、ほかの階層と衝突しません。
• スキルとコマンドが同名のときは、スキルが優先されます。

さらに、作業ディレクトリより下の入れ子の .claude/skills/ からも読み込まれます。Claude がサブディレクトリのファイルを読んだり編集したりすると、そのディレクトリのスキルが使えるようになります。モノレポで、パッケージが自分専用のスキルを持てるようにするためのしくみです。入れ子のスキルが同名の場合は両方が残り、入れ子側は apps/web:deploy のようにディレクトリ名で修飾された名前で現れます。

つまずきやすい点

• 起動時に読み込まれない入れ子スキルがある。プロジェクトのスキルは、Claude Code を起動したディレクトリとその親ディレクトリ（リポジトリのルートまで）から読み込まれます。一方、起動ディレクトリより下の入れ子の .claude/skills/ は起動時には読み込まれず、Claude がそのサブディレクトリのファイルを最初に読むか編集したときに読み込まれます。それまでは補完にも出ず、名前で呼び出すこともできません。
• セッション中の編集は反映されるが、ディレクトリの新設は別。Claude Code はスキルのディレクトリを監視しており、~/.claude/skills/ やプロジェクトの .claude/skills/ の中でスキルを追加・編集・削除すると、再起動なしでそのセッション中に反映されます。ただし、セッション開始時に存在しなかったトップレベルのスキルディレクトリを新しく作った場合は、監視対象に加えるために再起動が必要です。
• ライブ反映は SKILL.md のテキストだけ。スキルフォルダがプラグインを兼ねている場合、hooks/、.mcp.json、agents/、output-styles/ への変更を反映するには /reload-plugins が必要です。
• synced という名前は予約されている。エンタープライズ・個人・プロジェクトのスキル配置場所で、フォルダ名 synced は大文字小文字を問わず予約されています。claude.ai で有効にしたスキルの同期先として使われるため、その名前で自作しても読み飛ばされます。
• Cowork とクラウドセッションはローカルのスキルを読まない。Cowork のセッションとクラウドセッション（ルーティンを含む）は、手元の ~/.claude/skills/ を読みません。Cowork は claude.ai アカウントで有効にしたスキルをセッション開始時に同期して使います。クラウドセッションはこれに加えて、クローンしたリポジトリの .claude/skills/ にコミットされたプロジェクトスキルを読み込みます。
• permissions.additionalDirectories ではスキルは読み込まれない。スキルとコマンドを追加で読み込むのは --add-dir フラグと /add-dir コマンドだけです。settings.json の permissions.additionalDirectories はファイルへのアクセス権を与えるだけで、スキル・コマンド・サブエージェントは読み込みません。

関連記事: スキルとは何か / スキルと他機能の使い分け / スラッシュコマンド リファレンス

この記事は 公式ドキュメント「Extend Claude with skills」に基づく非公式の日本語解説です（確認日 2026-08-20）。仕様は更新されるため、最新は公式をご確認ください。