ガイド

Claude Code のスキルの使い方と SKILL.md の書き方

公開日：2026年10月30日 · 最終確認：2026年10月30日

スキルは、指示を書いた SKILL.md ファイルです。Claude は関連があるときにそれを使い、/skill-name で直接呼び出すこともできます。このページでは、Anthropic の Extend Claude with skills のドキュメントに沿って、最初のスキルの作り方、スキルの置き場所、frontmatter の書き方、誰がスキルを呼び出すかの制御、スキルが発動しないときの確認点を説明します。ドキュメントは 2026 年 10 月 30 日に確認しました。

スキルを書くタイミング

ドキュメントの基準は次のとおりです。同じ指示、チェックリスト、複数ステップの手順を何度もチャットに貼り付けている、または CLAUDE.md の一部が事実ではなく手順に育ってしまっている場合です。CLAUDE.md の内容と違って、スキルの本文は使われたときにだけ読み込まれるので、長い参考資料も、必要になるまではほとんどコストがかかりません。CLAUDE.md については、CLAUDE.md の書き方を参照してください。

ドキュメントはまた、カスタムコマンドがスキルに統合されたとも述べています。.claude/commands/deploy.md のファイルと .claude/skills/deploy/SKILL.md のスキルは、どちらも /deploy を作り、同じように動作し、既存の .claude/commands/ のファイルも引き続き動きます。スキルが加えるのは、補助ファイルを置くディレクトリ、あなたが呼ぶか Claude が呼ぶかを制御する frontmatter、そして関連があるときに Claude が自動で読み込めることです。

最初のスキルを作る

この例はドキュメントにあるもので、git リポジトリのコミットされていない変更を要約し、危険な点を指摘するスキルです。まず、個人用のスキルフォルダにそのディレクトリを作ります。個人用のスキルは、すべてのプロジェクトで使えます。

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

次に、SKILL.md を書きます。すべてのスキルにこのファイルが必要で、2 つの部分から成ります。Claude にスキルをいつ使うかを伝える、--- マーカーで囲んだ YAML の frontmatter と、スキルの実行時に Claude が従う指示を書いた markdown の内容です。

---
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.

ディレクトリ名（name を frontmatter に設定した場合はその名前）が、入力するコマンドになり、description は、Claude がスキルを自動で読み込むタイミングを判断する助けになります。!`git diff HEAD` の行は動的コンテキストの注入を使います。Claude Code はそのコマンドを実行し、Claude がスキルの内容を見る前に、その行を出力で置き換えるので、指示には現在の diff がすでに埋め込まれた状態で届きます。

最後に、試します。git のプロジェクトを開き、任意のファイルを少し編集して、claude を実行して Claude Code を起動します。どちらの方法でも動きます。

What did I change?     # matches the description, so Claude can invoke it automatically
/summarize-changes     # or invoke it directly with the skill name

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

スキルの置き場所

スキルを保存する場所で、どのセッションがそれを読み込むかが決まります。ホームディレクトリの下に保存すればすべてのプロジェクトで使え、リポジトリにコミットすればそこで作業する全員と共有でき、プラグインや managed settings で配布すればチーム全体に届けられます。

2 つのスキルが同じ名前を持つ場合です（ドキュメントの表からの抜粋）。

• enterprise、personal、project のうち 2 つで同じ名前：enterprise が personal より、personal が project より優先されます。deploy が ~/.claude/skills/ とプロジェクトの .claude/skills/ の両方にある場合、/deploy は personal のほうを実行します。
• スキルと .claude/commands/ のファイル：スキルが優先されます。
• プラグインのスキルと、上記のいずれかの場所のスキル：プラグインのスキルは /plugin-name:skill-name として名前空間が分かれているため、両方が読み込まれます。

もう 1 つのルールがあります。始めた場所より下の .claude/skills/ ディレクトリにあるスキルは、起動時には読み込まれません。Claude がそのサブディレクトリのファイルを初めて読むか編集したときに読み込まれます。それまでは、/ メニューに現れず、名前で呼び出すこともできません。

スキルを変更した後に、再起動する必要はありません。Claude Code はスキルのディレクトリを監視しているので、~/.claude/skills/ やプロジェクトの .claude/skills/ の下でスキルを追加、編集、削除すると、現在のセッション内で反映されます。セッションの開始時に存在しなかったトップレベルのスキルディレクトリを作った場合は、/reload-skills を実行します。

特に重要な frontmatter のフィールド

すべてのフィールドは任意です。推奨されるのは description だけです。フィールド名は、ハイフンも含めて表と完全に一致させる必要があります。Claude Code は、認識できないフィールドをエラーを出さずに無視します。真偽値のフィールドは、true と false に加えて、yes、no、on、off、1、0 を、大文字小文字を問わず受け付けます。

ドキュメントには、model、effort、agent、background、hooks、shell、metadata、license、compatibility など、さらに多くのフィールドが載っていますが、ここでは扱いません。1 つ注意点があります。Claude Code が frontmatter を読むのは、先頭の --- がファイルの 1 行目にあるときだけです。そうでない場合は、--- マーカーを含むファイル全体を、スキルの内容として扱います。

自分で呼び出すか、Claude に任せるか

デフォルトでは、あなたも Claude も、どのスキルでも呼び出せます。/skill-name と入力して直接呼び出すことができ、Claude は会話に関連があるときにそれを自動で読み込めます。これを制限する frontmatter のフィールドが 2 つあります。

• disable-model-invocation: true：Claude がスキルを自分で呼び出せなくなります。/commit、/deploy、/send-slack-message のように、副作用があるワークフローや、タイミングを自分で管理したいワークフローに使います。コードが準備できていそうだからと、Claude にデプロイを決めてほしくはないでしょう。
• user-invocable: false：Claude だけがスキルを呼び出せます。古いシステムの仕組みを説明する legacy-system-context スキルのように、コマンドとして実行できない背景知識に使います。

ドキュメントにある deploy の例です。

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

それでも Claude が呼び出そうとすると、Claude Code はその呼び出しをブロックし、デプロイの手順を別の方法で再現しないよう指示します。そのため、Claude は /deploy を自分で実行するよう提案してくるはずです。

スキルを直接実行するには、メッセージの先頭にその名前を置きます。/deploy staging はスキルを直接実行します。go ahead and /deploy to staging のように普通の文章の後ろに置いた場合は、直接実行されません。その名前は、そのメッセージに限ってあなたの許可として扱われ、Claude は応答中にそのスキルを実行でき、あなたの言い回しから、実行を依頼されたかどうかを判断します。実行を許可せずにそのスキルについて書くには、スラッシュを付けないでください。

引数と補助ファイル

スキルを呼び出すとき、あなたも Claude も引数を渡せます。引数は $ARGUMENTS プレースホルダーで使え、スキル名の後ろに続くものに置き換えられます。

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

/fix-issue 123 を実行すると、Claude は「Fix GitHub issue 123 following our coding standards...」を受け取ります。個々の引数を位置で参照するには、$ARGUMENTS[N] か、より短い $N を使います。引数付きでスキルを呼び出したのに、スキルの内容にそれを受け取るプレースホルダーがない場合、Claude Code はスキルの内容の末尾に ARGUMENTS: <your input> を追加するので、Claude はあなたが入力したものを引き続き見られます。

スキルのディレクトリには、複数のファイルを置けます。これにより、SKILL.md を要点に絞りつつ、詳細な参考資料を、必要なときにだけ Claude に読ませられます。

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

補助ファイルを SKILL.md から参照して、各ファイルの内容と、いつ読み込むべきかを Claude に伝えます。

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

ドキュメントのヒントは、SKILL.md を 500 行以内に保ち、詳細な参考資料は別のファイルに移すことです。

良い description の書き方

• ユーザーが自然に口にするキーワードを使う。ドキュメントのトラブルシューティングの一覧の最初の項目は、description にそれらが含まれているか確認することです。上の例は、トリガーを直接書いています：「Use when the user asks what changed, wants a commit message, or asks to review their diff.」
• 主な用途を最初に書く。description と when_to_use を合わせたテキストは、スキルの一覧では 1,536 文字で切り詰められます。
• 発動しすぎるなら、より具体的にする。これは、望まないときにスキルが発動する場合のドキュメントの最初の提案です。
• 山括弧はエスケープされる。description と when_to_use の中の < と > は、< と > として表示されます。<branch> のようなプレースホルダーを表示するには、角括弧の [branch] を使うか、別の argument-hint の行に移します。
• 本文は短くする。スキルが読み込まれると、その内容はターンをまたいでコンテキストに残るので、すべての行が継続的なトークンコストになります。どのように、なぜを語るのではなく、何をするかを書いてください。

トラブルシューティング

スキルが発動しない

• description に、ユーザーが自然に口にするキーワードが含まれているか確認します。
• What skills are available? の答えにそのスキルが現れるか確認します。
• description により近くなるよう、依頼の言い回しを変えてみます。
• スキルがユーザーから呼び出せるなら、/skill-name で直接呼び出します。
• /skill-name も認識されない場合は、Claude Code がスキルの名前を拒否していないか確認します（ゼロ幅スペース、制御文字、<、> などの文字が原因になります）。
• スキルが paths を設定している場合は、Claude が読む、編集する、書くファイルが、Claude の現在の作業ディレクトリの内側にあるか確認します。スキルは、その外にあるファイル（/add-dir で追加したものも含め、兄弟の git worktree にあるファイルなど）には発動しません。

frontmatter の YAML が不正な場合、Claude Code はスキルの本文を空のメタデータで読み込むので、/skill-name は引き続き動きますが、Claude は description との照合ができません。--debug を付けて実行すると、解析エラーが表示されます。frontmatter が解析できない SKILL.md ファイルを見つけるには、スキルのディレクトリに対して claude plugin validate を実行します。たとえば claude plugin validate .claude/skills や claude plugin validate ~/.claude/skills です。Claude Code v2.1.233 以降が必要です。

スキルが発動しすぎる

description をより具体的にします。手動での呼び出しだけにしたい場合は、disable-model-invocation: true を追加します。

Claude がスキルに従わなくなる

スキルが呼び出されると、Claude Code はその内容を会話に追加し、以降のターンではファイルを読み直しません。そのため、タスク全体に当てはまる指針は、「Run the tests」ではなく「Run the tests after every edit」のように書きます。コンパクトの後、Claude Code は、呼び出されたスキルの先頭部分だけを保持することがあるので、最も重要な指示は SKILL.md の冒頭近くに置き、スキルをもう一度呼び出して、全体の内容を復元してください。毎回必ず守らせたいルールには、ドキュメントは代わりにフックを勧めています。

description が途中で切れる

スキルが多いと、Claude Code は一覧の文字数の予算に収めるために一部の description を落とし、Claude があなたの依頼と照合するのに必要なキーワードが失われます。予算はモデルのコンテキストウィンドウの 1% に比例し、description は、あなたが呼び出す頻度の低いスキルから順に落とされます。/doctor を実行すると、一覧のコンテキストコストの見積もりと、最も大きな要因が分かります。

FAQ

参考資料

• Claude Code: Extend Claude with skills（スキルの置き場所、名前の衝突、frontmatter のフィールド、呼び出しの制御、引数、補助ファイル、トラブルシューティング）