Claude Code Skillsの使い方｜呼び出し方・作り方・直し方を手順で解説

「Claude Codeのスキルを入れてみたけれど、どう呼び出せばいいのか分からない」「自分でスキルを作ってみたのに、Claudeが使ってくれない」という場面は、スキルを使い始めた方がよく経験するつまずきです。

スキルは、作業の手順や決まりごとをSKILL.mdというファイルにまとめ、Claudeに必要なときだけ読み込ませる仕組みです。仕組みそのものは単純ですが、説明文の書き方や置き場所、呼び出し方の設定によって、動き方が大きく変わります。

この記事では、スキルを使う・作る・直す・共有するの4つを、手を動かす順番で解説します。スキルとは何か、CLAUDE.mdとの違いはClaude Code Skillsとはで、どのスキルを入れるべきかはおすすめスキルの記事で説明しています。ここでは重ねて説明せず、操作と書き方に絞ります。内容は2026年10月時点のClaude Codeの公式ドキュメントにもとづいています。

スキルを使う

まずは、すでにあるスキル（標準のスキル、プラグインのスキル、自分や同僚が作ったスキル）を使う方法です。作るときにも同じ操作を使うので、先に押さえておきましょう。

使えるスキルを一覧で確かめる

Claude Codeの入力欄で/を打つと、使えるコマンドとスキルのメニューが開きます。名前の一部を続けて打つと絞り込めます。

スキルだけを見たいときは、/skillsと入力します。公式のコマンド一覧によると、この画面では次の操作ができます。

• 文字を打つと、名前・説明・出所で一覧を絞り込める
• tキーで、読み込みの負担（トークン数）が大きい順に並べ替えられる
• SpaceまたはEnterで、そのスキルの見え方（Claudeに見せるか、/のメニューに出すか）を切り替えられる
• Escで、変更を保存して閉じる

Claudeに「使えるスキルは何？」と聞いても、一覧が返ってきます。公式ドキュメントでは、スキルが使われないときの確認方法として、この質問が挙げられています。claude.aiのアカウントから同期されたスキルは「claude.ai sync」の見出しの下に、プラグインのスキルは出所のプラグイン名つきで表示されます。

呼び出しは2通りある

スキルの呼び出し方は、自分で呼ぶ方法と、Claudeに任せる方法の2つです。

公式ドキュメントでは、スキル名を書く位置によって動きが変わると説明されています。メッセージの先頭に書くと、そのスキルが直接動きます。「/deployしてください」のように文の途中に書いた場合は、スキルはすぐには動かず、「このスキルを使ってよい」という許可として扱われます。使うかどうかはClaudeが文面から判断します。確実に動かしたいときは、先頭に書いてください。

スキルについて話すだけで動かしたくないときは、スラッシュをつけずに名前を書きます。

引数をつけて呼び出す

スキルによっては、呼び出すときに続けて言葉を渡せます。たとえば公式ドキュメントの例では、/fix-issue 123と入力すると、スキルの本文の$ARGUMENTSという部分が「123」に置きかわります。

複数の言葉を渡すときは、位置で受け取る書き方もできます。空白の入った言葉は、引用符で囲んで1つの値として渡します。

/migrate-component SearchBar JavaScript TypeScript
/my-skill "hello world" second

1行目は3つの値、2行目は「hello world」と「second」の2つの値を渡しています。スキルを作る側での引数の書き方は、後の「機能を足して作り込む」で説明します。

スキルが引数を受け取る場所を用意していなくても、入力した言葉は捨てられません。公式ドキュメントによると、その場合は本文の末尾にARGUMENTS: 入力した内容という形で追加されます。

複数のスキルを続けて呼び出す

1つのメッセージの先頭に、スキルを続けて並べることもできます。公式ドキュメントの例は、次のとおりです。

/write-tests /fix-issue 123

この場合、2つのスキルが両方とも読み込まれ、末尾の「123」が、それぞれのスキルの引数として渡されます。1つめのスキルに加えて、あと5つまで続けて指定できます。ただし、別の担当（サブエージェント）で動くスキルや、引数にスラッシュコマンドを取るスキルが出てきたところで、読み込みは止まります。そこから後ろは、すべて引数の文字として扱われます。

プラグインや同じ名前のスキルの扱い

プラグインで入れたスキルは、/プラグイン名:スキル名の形で呼び出します。たとえばcommit-commandsプラグインのcommitなら、/commit-commands:commitです。プラグイン名がつくので、自分で作ったスキルと名前がぶつかりません。

自分のパソコンやプロジェクトの中で、同じ名前のスキルが複数あるときは、公式ドキュメントに次の優先順位が書かれています。

意図せず同じ名前をつけると、標準スキルを隠してしまうことがあります。たとえば自分でcode-reviewという名前のスキルを作ると、標準の/code-reviewの代わりにそちらが動きます。標準のスキルと同じ名前は避けるのが無難です。

呼び出したあと、スキルはどう動くか

スキルを呼び出すと、SKILL.mdの本文が、会話の中の1つのメッセージとして加わります。公式ドキュメントでは、次のように説明されています。

• 本文は、その後の会話にも残り続ける。Claude Codeは、次のターン以降にファイルを読み直さない
• 同じスキルをもう一度呼び出したとき、内容が前回と同じなら、短い「すでに読み込み済み」のメモだけが加わる
• allowed-toolsで許可した道具の確認なしの権限は、次にメッセージを送ると解除される
• 会話が長くなって自動で要約（コンパクト）されるとき、呼び出したスキルは1つにつき先頭の5,000トークンまでが残る。複数のスキルを合わせた上限は25,000トークンで、古いスキルから外れることがある

使わせたくないスキルを止める

入っているスキルを、自分のパソコンで見えなくしたり、Claudeに使わせなくしたりする方法は、いくつかあります。SKILL.mdを書き換えられないスキル（共有リポジトリのものなど）も、設定で止められます。

skillOverridesは、/skillsの画面でSpaceキーを押して状態を切り替え、Escで保存すると、.claude/settings.local.jsonに書き込まれます。ファイルを直接編集する必要はありません。

作る前に決めること

スキルは、思いついたときに書き始めるより、少しだけ準備してから書いた方が、あとで直す手間が減ります。ここでは、何をスキルにするか、どこまでを1つにするか、名前をどうつけるかを決めます。

スキルにする仕事の見つけ方

公式ドキュメントでは、スキルを作るタイミングとして次の2つが挙げられています。

• 同じ指示やチェックリスト、何段階もある手順を、何度もチャットに貼り付けているとき
• CLAUDE.mdの一部が、「事実」ではなく「手順」になってきたとき

具体的には、最近のClaude Codeとのやりとりを振り返って、3回以上、同じ説明をしている仕事を探します。「議事録はこの型で」「返信メールではこの言い回しは使わない」「公開前にこの項目を確認して」のように、毎回ほぼ同じ内容を書いているものが候補です。

すでにうまくいった作業があるなら、その会話がそのまま材料になります。何を渡し、どう直させ、最終的にどんな形で受け取ったかを思い出して、メモに書き出してみてください。

スキルに向いている仕事・向いていない仕事

何でもスキルにすればよいわけではありません。仕事の性質によって、向いている仕組みが違います。

迷うのは、「毎回守ってほしい決まり」です。スキルは、Claudeが内容を読んで判断しながら使うものなので、守られないことがあります。守られなかったときの影響が大きい決まりは、スキルではなくフックにしてください。スキルの設定にhooksを書くと、そのスキルを呼び出したあと、セッションが終わるまで有効なフックを一緒に持たせることもできます。

1つのスキルは、1つの仕事にする

1つのスキルに、ちがう仕事を詰め込みすぎると、説明文が長くなり、どの場面で使うスキルなのかが分かりにくくなります。反対に、細かく分けすぎると、一覧が長くなり、呼び出すときに迷います。

分け方の目安は、「頼むときの言葉が同じかどうか」です。「議事録を整えて」と頼む仕事と「請求書を確認して」と頼む仕事は、頼む言葉が違うので別のスキルにします。逆に、「議事録の整形」と「議事録の宿題の抜き出し」が、いつも続けて頼まれるなら、1つのスキルの中の手順にしてかまいません。

1つのスキルの中に、まったく別の流れが並び始めたら、分けるサインです。公式ドキュメントも、詳しい資料は別のファイルに分けて、SKILL.mdは500行以内に収めるようすすめています。

名前を決める

スキルのフォルダの名前が、そのまま/名前のコマンド名になります。frontmatter（SKILL.mdの上の設定部分）にnameを書けば、そちらが優先されます。次の決まりに沿って名前をつけておくと、あとで困りません。

• 英小文字・数字・ハイフンだけにする（入力しやすく、claude.aiなどにアップロードするときにも使える）
• 何をするスキルかが分かる名前にする。動詞の形（check-invoice）か、名詞の形（invoice-check）で、集めたスキルの間で書き方をそろえる
• helperやutilsのような、何をするか分からない名前は避ける
• 標準スキルと同じ名前は避ける（自分のスキルが標準のものを隠してしまう）

最初のスキルを作る

それでは、実際に1つ作ります。ここでは、自分のパソコンのすべてのプロジェクトで使える「個人用」のスキルを作る手順で説明します。置き場所の違いはClaude Code Skillsとはの記事に一覧があります。

作る手順

1. フォルダを作る個人用のスキルは、ホームフォルダの.claude/skills/の下に、スキル名のフォルダを作ります。Windowsでは、%USERPROFILE%\.claude\skills\スキル名です（公式ドキュメントに、Windowsでは~/.claudeがこの場所にあたると書かれています）。MacやLinuxでは、~/.claude/skills/スキル名です。エクスプローラーやFinderで作ってもかまいません。
2. SKILL.mdを作るフォルダの中に、SKILL.mdという名前のファイルを作ります。メモ帳などのテキストエディタで書けます。ファイルの1行目は、必ず---から始めます。
3. 設定部分と本文を書く先頭の---と---で囲んだ部分に説明文（description）を書き、その下に手順や決まりごとを書きます。書き方は次の見本を参考にしてください。
4. Claude Codeを起動して、呼び出す作業するフォルダでClaude Codeを起動します。説明に合う頼み方をするか、/スキル名と入力して呼び出します。
5. 結果を見て、書き直す思ったとおりに動かなければ、SKILL.mdを直して、もう一度呼び出します。

公式ドキュメントでは、frontmatterのどの項目も省略できるとしたうえで、説明文（description）だけは書くことをすすめています。説明文がないと、Claudeがスキルを使う場面を判断しにくくなります。

見本1：公式ドキュメントの例

公式ドキュメントでは、最初の例として、変更内容を要約して危ない点を指摘するスキルが紹介されています。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が読む前にClaude Codeがコマンドを実行し、結果で置きかえる書き方です（「機能を足して作り込む」で説明します）。この例は、Gitで管理しているプロジェクトで試せます。ファイルを少し編集してから、「何を変更した？」と聞くか、/summarize-changesと入力します。

見本2：問い合わせへの返信の下書き

プログラミングをしない方向けに、問い合わせメールへの返信の下書きを作るスキルの例も示します。reply-draftというフォルダに置く想定です。

---
name: reply-draft
description: お客様からの問い合わせメールへの返信の下書きを作る。問い合わせへの返事、お客様対応のメール、返信文の作成を頼まれたときに使う。
---

## 返信の型
1. お礼（1文）
2. 回答（結論を先に書く。質問が複数あるときは箇条書き）
3. お願いしたいこと（なければ省く）
4. 結びと署名

## 決まりごと
- です・ます調で書く。「させていただきます」は多用しない
- 納期・金額・在庫は、元のメールや資料に書いてあるものだけを使う。なければ「要確認」と書いて空欄にする
- 謝罪が必要な内容は、事実と対応を書く。言い訳は書かない
- 質問の意味が2通りにとれるときは、下書きの前に確認の質問を返す
- 下書きは replies/ フォルダに「日付_会社名.md」で保存する。送信はしない

手順を細かく書くより、できあがりの型と迷ったときの判断としてはいけないことを書く方が、Claudeは安定して動きます。この例では、事実を勝手に補わないこと、送信までは行わないことを、決まりごととして先に明記しています。

動かして確かめる

スキルは、次の2つの方法で試せます。

• Claudeに任せる：説明文に合う頼み方をします。たとえば「この問い合わせへの返信を書いて」と頼み、スキルが使われるかを見ます
• 自分で呼び出す：/reply-draftと入力します。これで動かなければ、ファイルの場所や名前に問題があります

Claude Codeは、~/.claude/skills/やプロジェクトの.claude/skills/の中のファイルを見張っています。そのため、作業中にSKILL.mdを追加したり直したりしても、再起動せずに反映されます。ただし、セッションを始めたときに存在しなかった「skills」フォルダそのものを新しく作った場合は、/reload-skillsと入力して、読み込み直してください。

Claudeに下書きを作ってもらう

SKILL.mdは、自分で書かなくても、Claudeに下書きを作らせられます。Claude開発者ドキュメントでは、まず、スキルなしで普通に作業を終え、そのあとでスキルにまとめる進め方が紹介されています。作業の中で、あなたはデータの場所、好み、直してほしい点を何度か伝えているはずです。その情報が、スキルの材料になります。

作業が終わったら、同じ会話の中で、次のように頼みます。

今の作業の流れを、次から使えるスキルにしてください。名前は reply-draft にして、個人用のスキルのフォルダに保存してください。返信の型、守ってほしい決まりごと、してはいけないことを入れてください。

下書きができたら、次の2点を見直します。

• 余計な説明がないか：Claudeがすでに知っていることまで書かれていたら、削るよう頼みます。公式のガイドでも、「Claudeはすでに賢い。持っていない情報だけを足す」ことが基本とされています
• 説明文に「いつ使うか」があるか：頼み方の言葉が入っているかを見ます

別の方法として、Anthropicの公式プラグインのskill-creatorを入れると、スキルの作成から、効果の測定、説明文の改善までを手伝ってもらえます。使い方は「効果を確かめて直す」で説明します。

SKILL.mdの書き方

スキルが思いどおりに動くかどうかは、ほとんどが説明文と本文の書き方で決まります。ここでは、公式ドキュメントとClaude開発者ドキュメント（Skill authoring best practices）に書かれている考え方を、実際の書き方に置き換えて説明します。

説明文（description）の書き方

説明文は、Claudeが「このスキルを使うか」を決める唯一の手がかりです。Claudeは、入っているすべてのスキルの名前と説明文を常に見ていて、依頼の内容に合うものを選びます。開発者向けドキュメントでは、100を超えるスキルの中から選ぶこともあるため、何をするかと、どんなときに使うかの両方を書くよう説明されています。

説明文を書くときのコツは、実際に頼むときの言葉を入れることです。「議事録」と呼んでいる人もいれば、「会議メモ」「打ち合わせの記録」と呼ぶ人もいます。よく使う言い方を、説明文に混ぜておくと、頼み方が少し違っても選ばれます。

Claude Codeでは、説明文と、補足のwhen_to_useを合わせた文字が、スキルの一覧では1,536文字で切られます。公式ドキュメントでは、いちばん大事な使いどころを、先頭に書くようすすめています。なお、claude.aiやAPIにアップロードするスキルの説明文は、1,024文字までです。

本文の書き方の基本

本文には、スキルを使うときにClaudeが従う手順や決まりごとを書きます。公式ドキュメントとClaude開発者ドキュメントは、どちらも簡潔に書くことを最初にすすめています。理由は、スキルを呼び出した本文が会話の中に残り続け、1行ごとに使用量を消費するからです。

書くかどうかは、次の問いで判断します。

• この説明は、Claudeがすでに知っていることではないか（一般的な知識は不要）
• この1段落は、使用量を消費するだけの価値があるか
• 書いてあることは、「どうするか」か。「なぜそうなのか」の長い説明になっていないか

たとえば「PDFとは何か」の説明や、「メールは丁寧に書くのが望ましい」のような一般論は、書かなくても動きます。反対に、自社だけの決まり（社内の言い回し、保存場所、使わない表現、確認する人）は、書かなければClaudeには分かりません。スキルに書くべきは、こちらです。

どこまで細かく指示するかを決める

Claude開発者ドキュメントは、指示の細かさ（自由度）を、仕事の性質に合わせて変えるようすすめています。

公式のガイドでは、細い橋と開けた野原のたとえが使われています。両側が崖になった細い橋では、決まった道筋を示す必要があります。何も危険がない野原では、方向だけを示せば、Claudeが最適な道を選びます。

できあがりの型と、例を入れる

出力の形が大事なスキルでは、型（テンプレート）や例を入れると、仕上がりが安定します。Claude開発者ドキュメントには、2つの書き方が紹介されています。

• 型を示す：「必ずこの構成で書く」と厳密にするか、「標準の形はこれ。状況に合わせて調整してよい」と柔らかくするかを、はっきり書きます
• 入力と出力の例を並べる：言葉で説明するより、例を2〜3個見せる方が、希望する書き方や詳しさが伝わる、とされています

## 出力の型
次の構成で書く。見出しは変えない。

# 打ち合わせの要点
## 決まったこと
## 宿題（担当者・期限つき）
## 次回までに確認すること

## 例
入力：「来週までにA社へ見積書を送る。担当は佐藤」
出力：宿題：A社への見積書の送付（担当：佐藤、期限：来週中）

例を入れるときは、実際の仕事で出てくる、少し癖のある例を選んでください。簡単な例ばかりだと、難しいケースでの動きを示せません。

確認の手順を入れる

間違いが目立ちやすい仕事では、「作る→確かめる→直す」の流れを、本文に書いておきます。Claude開発者ドキュメントでは、これを「フィードバックのループ」と呼び、品質を大きく上げる方法として紹介しています。

## 確認のしかた
1. 下書きを書く
2. 次の項目を確認する
   - 金額・日付が、元の資料と一致しているか
   - 「要確認」の項目が残っていないか
3. 問題があれば、該当箇所を直して、2に戻る
4. すべて満たしたら、保存する

手順の数が多いときは、チェックリストを本文に置いて、「このリストをコピーして、終わった項目に印をつけながら進める」と指示する方法もあります。途中の確認を飛ばしにくくなります。

ファイルが長くなったら分ける

SKILL.mdが長くなってきたら、詳しい資料を別のファイルに移します。公式ドキュメントと開発者向けドキュメントは、どちらもSKILL.mdは500行以内を目安としています。

reply-draft/
├ SKILL.md      概要と、ほかのファイルの案内（必須）
├ tone.md       言い回しの細かい決まり（必要なときに読む）
├ examples.md   過去の良い返信の例（必要なときに読む）
└ scripts/
   └ check.py   金額の確認用プログラム（実行するだけで、中身は読み込まない）

SKILL.mdには、「言い回しで迷ったときは tone.md を読む」のように、どのファイルに何が書いてあり、いつ読むかを書いておきます。Claudeは、必要になったときだけそのファイルを開きます。

分け方には、守りたい点が2つあります。

• SKILL.mdから直接つなぐ：「SKILL.md→tone.md→さらに別のファイル」のように、入れ子にすると、Claudeが途中までしか読まないことがあります。ファイルは、SKILL.mdから1段の深さに置きます
• 長いファイルには目次をつける：100行を超える資料の先頭に、内容の一覧を置くと、全体の範囲を見渡したうえで必要な部分を読めます

機能を足して作り込む

ここからは、スキルにできることを増やす機能です。最初のスキルは、説明文と本文だけで十分です。「呼び出すたびに同じ値を入力している」「毎回、最新の情報を読み込ませたい」といった場面になってから、必要な機能を足してください。

引数を受け取る

スキルの本文に$ARGUMENTSと書くと、呼び出したときに続けて入力した言葉が、そこに入ります。複数の値を使い分けたいときは、設定部分のargumentsに名前を並べておくと、名前で受け取れます。

---
name: reply-draft
description: お客様からの問い合わせメールへの返信の下書きを作る。
arguments: [company]
argument-hint: [会社名]
---

返信先の会社名：$company

## 返信の型
（省略）

この場合、/reply-draft 株式会社サンプルと入力すると、本文の$companyが「株式会社サンプル」に置きかわります。argument-hintは、入力するときに表示されるヒントです。位置で受け取りたいときは、$0、$1のように書きます。

引数に渡した文字は、そのままの文字として扱われます。渡した文字の中に$1のような書き方が含まれていても、置きかえは行われません。

コマンドの結果を、読み込む前に取り込む

本文に!`コマンド`と書くと、Claude Codeがスキルを読み込む前にそのコマンドを実行し、結果で置きかえます。Claudeには、コマンド自体ではなく、実行した結果がすでに入った状態で届きます。最初の見本の!`git diff HEAD`が、この書き方です。

複数行のコマンドは、```!で始まるコードのかたまりに書きます。次の点に気をつけてください。

• コマンドが失敗すると、スキル全体が動きません。エラーの終了コードが返るコマンドがあるときは、末尾に|| trueをつけると、失敗しても進めます（bashの場合）
• 行の先頭か、空白の直後にある!だけが対象です。KEY=!`cmd`のように、文字のすぐ後ろに書いても実行されません
• 各コマンドは、通常のBashツールと同じ2分の制限時間で動きます
• 実行の前に確認を求められることはありません。そのかわり、許可のルールに合わないコマンドがあると、確認なしでスキルの呼び出しが中止されます。allowed-toolsで、そのコマンドを許可しておきます

会社の設定では、disableSkillShellExecution: trueで、この書き方を一括で止められます。止めたあとは、コマンドの部分が「[shell command execution disabled by policy]」という文字に置きかわります。また、claude.aiから同期されたスキルでは、自分のパソコン上でこのコマンドが実行されることはありません。

付属のファイルとスクリプトを置く

スキルのフォルダには、SKILL.md以外のファイルを置けます。資料、見本、プログラムなどです。プログラムは、読み込まずに、実行だけさせることができるため、計算のように毎回同じ結果を出したい処理に向いています。

スキルの本文や、allowed-toolsの中では、${CLAUDE_SKILL_DIR}という書き方で、そのスキルのフォルダの場所を指せます。どこにスキルを置いても、同じ書き方で動きます。

---
name: render-chart
description: CSVファイルからグラフを作る。
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

${CLAUDE_SKILL_DIR}/scripts/render.sh を、CSVファイルを指定して実行する。

これは公式ドキュメントにある例を、日本語にしたものです。本文の命令とallowed-toolsに同じ書き方をそろえておくと、スクリプトが確認なしで動きます。

付属のプログラムを書くときは、Claude開発者ドキュメントにある2点に気をつけてください。

• エラーはプログラムの中で処理する：ファイルがない、権限がない、といった場合の動きを、Claudeに任せず、プログラムの中で決めておきます
• ファイルの場所は、スラッシュで書く：scripts/helper.pyのように書くと、WindowsでもMacでも通じます。scripts\helper.pyのような書き方は、Windows以外で動かないことがあります

確認なしで使える道具を決める

allowed-toolsに道具を書くと、そのスキルを呼び出したターンの間、書いた道具を確認なしで使えます。たとえば、次のような書き方です。

allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)

公式ドキュメントで押さえられている点は、次のとおりです。

• 許可は、次のメッセージを送ると解除される。スキルを呼び出し直すと、またそのターンだけ有効になる
• 道具の利用を制限するものではない。書かなかった道具も使える。使えなくしたい道具は、disallowed-toolsに書く（こちらも次のメッセージで解除される）
• フォルダを信頼するかどうかの確認とは関係なく適用される。リポジトリに入っているスキルのallowed-toolsは、Claude Codeを動かす前に確認する

コミットやメール送信のような、影響の大きい作業のスキルは、disable-model-invocation: trueと組み合わせます。そうすると、あなたが/名前と入力したときだけ動き、そのときだけ道具が許可されます。

別の担当（サブエージェント）で動かす

context: forkと書くと、スキルは本体の会話とは別の担当（サブエージェント）の中で動きます。長い調査や、ほかの作業の邪魔をしたくないまとまった仕事に向いています。

---
name: deep-research
description: テーマを調べて、根拠つきでまとめる
context: fork
agent: Explore
---

$ARGUMENTS について調べる。
1. 関係するファイルを探す
2. 内容を読んで整理する
3. ファイル名を示して、要点をまとめる

公式ドキュメントで、押さえておきたい点は次のとおりです。

• サブエージェントは、いままでの会話を見られません。スキルの本文だけで作業が完結するように書く
• 「このAPIの書き方を守る」のような、決まりごとだけで、作業の指示がないスキルには向かない。何も作業をせずに終わる
• agentで、動かす担当の種類を選ぶ（Explore、Plan、general-purpose、または.claude/agents/の自作のもの）。書かなければgeneral-purpose
• 最近のバージョンでは、バックグラウンドで動き、終わったら結果が会話に届く。結果を待ちたいときはbackground: falseと書く

サブエージェントの仕組みはサブエージェントの記事で詳しく解説しています。

特定のファイルのときだけ使う、モデルを変える

pathsにファイルの場所のパターンを書くと、そのパターンに合うファイルを扱っているときだけ、Claudeがスキルを自動で使います。たとえばarticles/**/*.mdと書けば、記事の原稿を扱うときだけ、校正のスキルが候補に入ります。

modelとeffortを書くと、スキルを使う間のモデルと、考える深さを変えられます。変更はそのターンの間だけで、次のメッセージを送ると、元に戻ります。重い分析のスキルだけ、深く考えさせたい、といった使い方ができます。

やりたいことと、書くものの早見表

効果を確かめて直す

スキルは、作ったあとの確かめと直しで、使えるものになります。公式ドキュメントも、「スキルが呼び出されたこと」と「期待どおりの結果が出たこと」は別の話で、どちらも確かめる必要があると説明しています。

まず、実際の依頼で1回動かす

最初は、本番の仕事に近い依頼を1つ選び、スキルを呼び出して結果を見ます。そのとき、次の3点を見てください。

• 呼び出されたか：自分で/名前と入力した場合は確実ですが、Claudeに任せる頼み方でも使われるかを確かめます
• 本文のとおりに動いたか：型、決まりごと、してはいけないことが守られているか
• 仕上がりは使えるか：手直しなしで、そのまま使える品質か

思ったとおりでなければ、SKILL.mdを直して、同じ依頼でもう一度動かします。Claude Codeは、スキルのファイルの変更を見張っているので、再起動は要りません。

スキルあり・なしを比べる

1回うまくいっても、たまたまかもしれません。公式ドキュメントでは、スキルがある状態とない状態で、同じ依頼を実行して比べる方法が紹介されています。スキルが本当に役に立っているのかを、確かめるための方法です。

1. 依頼を3つほど用意する実際の仕事で出てくる、少しずつ違う依頼を集めます。簡単なものと、癖のあるものを混ぜます。
2. スキルありで実行する新しいセッションを始め、1つずつ依頼します。新しいセッションにするのは、スキルを書いたときの会話の記憶が残っていると、書き足りない部分が隠れてしまうからです。
3. スキルなしで実行する個人用・プロジェクト用のスキルなら、skillOverridesで"off"にしてから、新しいセッションで同じ依頼を実行します。
4. 結果を比べる型や決まりごとが守られているか、手直しの量がどう違うかを見ます。差が小さければ、スキルが不要か、書き方が足りていないかのどちらかです。

スキルがプラグインに入っている場合は、skillOverridesが効きません。公式ドキュメントでは、claude plugin evalというコマンドで、プラグインなしの状態と比べる方法が案内されています。

skill-creatorで測る

公式マーケットプレイスには、Anthropic製のプラグインskill-creatorがあります。比較の手順を自動で進めてくれるもので、公式ドキュメントに、入れ方と使い方が載っています。Claude Codeの入力欄で、次のように入力します。

/plugin install skill-creator@claude-plugins-official

入ったあと、「reply-draftのスキルを、skill-creatorで評価して」のように頼むと、テストの作成から評価までを進めてくれます。公式ドキュメントに書かれている機能は、次のとおりです。

インストールで「Marketplace "claude-plugins-official" not found」と出たときは、/plugin marketplace add anthropics/claude-plugins-officialで公式マーケットプレイスを追加してから、もう一度入れます。

公式のガイドでは、評価はスキルを書き込む前から作るのが望ましいとされています。まずスキルなしで、代表的な仕事をClaudeにやらせ、つまずく点を書き出します。その点を確かめるテストを3つほど作り、必要な最小限の指示だけを書く、という順です。本当に困っている点だけをスキルに書くので、本文が膨らみにくくなります。

症状別の直し方

うまく動かないときは、症状から原因を絞ります。公式ドキュメントのトラブルシューティングを、表にまとめました。

説明文が省かれる問題について、補足します。Claude Codeは、スキルの名前と説明文の一覧を、文字数の予算の範囲で読み込みます。予算はモデルの文脈の長さの1%が目安です。あふれたときは、使う頻度が低いスキルの説明文から省かれ、名前だけが残ります。数が多いときは、/doctorで一覧の負担を確かめ、/skill-doctorで、使われていないスキルを探してください。

書き間違いを調べる方法

設定部分の書き方が間違っていると、スキルは読み込まれても、説明文が空になります。この場合、エラーの表示は出ません。次の方法で調べられます。

• claude --debugで起動して、読み込みのエラーを見る
• ターミナルでclaude plugin validate .claude/skillsと入力する（個人用なら~/.claude/skills）。設定部分が読み取れないSKILL.mdを探せる。公式ドキュメントでは、Claude Code v2.1.233以降で使えるとされている
• 設定部分の先頭の---が、ファイルの1行目にあるかを確かめる。2行目以降にあると、設定として読まれない

直しながら改善する進め方

Claude開発者ドキュメントでは、スキルを直す進め方として、書く役と使う役を分ける方法が紹介されています。スキルを書くのを手伝ってもらうClaude（Claude A）と、そのスキルを実際に使って作業するClaude（Claude B）を、別の会話にするのです。

1. 実際の仕事で使うテスト用の依頼ではなく、本物の仕事で、スキルが読み込まれた新しい会話を使います。
2. つまずいた点を記録する「返信の下書きで、納期を勝手に書いた」のように、何が起きたかを具体的に書き留めます。
3. 書く役に相談するSKILL.mdと、起きたことを見せて、「なぜ守られなかったか、どう書けば守られるか」を尋ねます。強い言い方にする、目立つ場所に移す、といった提案が返ってきます。
4. 直して、もう一度使う直したら、新しい会話で、似た依頼を試します。

1回に直す点は、1つか2つにとどめてください。いくつも一度に直すと、どの変更が効いたのか分からなくなります。

チームで共有して運用する

個人で使い込んだスキルは、チームで使えるようにすると、効果が広がります。一方で、人数が増えるほど、「誰が直すのか」「何が入っているのか」が分からなくなりやすくなります。共有の方法と、運用のルールを決めておきましょう。

共有の方法を選ぶ

公式ドキュメントでは、スキルを共有する範囲として、次の3つが紹介されています。

置き場所と読み込まれる範囲の一覧は、Claude Code Skillsとはの記事にまとめています。

プロジェクトのスキルを共有する手順

1. 個人用から移す共有したいスキルのフォルダを、個人用の~/.claude/skills/から、プロジェクトの.claude/skills/へ移します。同じ名前のスキルが個人用に残っていると、個人用が優先されるため、移したら個人用の方は削除します。
2. 中身を確かめる説明文が、作った本人以外にも分かる書き方か、本文に自分の環境だけで通じる言葉（自分のフォルダ名など）が残っていないか、allowed-toolsが広すぎないかを確認します。
3. コミットして共有するリポジトリにコミットして、チームに知らせます。
4. メンバーが取り込むメンバーは、リポジトリを最新にします。Claude Codeを起動して/skillsを開き、一覧に出ているか確かめます。

クラウドで動くClaude Codeの作業では、リポジトリにコミットされたスキルは読み込まれますが、自分のパソコンの~/.claude/skills/のスキルは読み込まれません。公式ドキュメントでは、ルーチン（予約実行）やCoworkでも、パソコン上の個人用スキルは読まれないと説明されています。そうした場面で使うスキルは、プロジェクトに置くか、claude.aiのアカウントで有効にします。なお、デスクトップアプリの予約タスクは自分のパソコンで動くため、個人用のスキルも読み込まれます。

運用のルールを決める

スキルは、作って終わりではありません。業務の手順や社内の決まりが変わると、スキルの中身も古くなります。次のようなルールを、最初に決めておくと運用しやすくなります。

• 担当者：スキルごとに、直す責任を持つ人を決める。決めておかないと、誰も直さないまま古くなる
• 変更の確認：allowed-toolsや!`コマンド`を変える変更は、別の人が確認してから取り込む。これらは実際にコマンドを動かす部分だからです
• 見直しの時期：月に1回など、/skill-doctorで、使われていないスキルや、負担の大きいスキルを確認する
• 他人のスキルを入れるときの確認：出所を確かめ、中身をすべて読んでから入れる。詳しくはClaude Codeのセキュリティの記事と、おすすめスキルの記事の「入れる前の安全確認」を参照してください
• 名前のつけ方：チームで同じ書き方にそろえる。標準スキルと重なる名前は避ける

CoworkやClaudeのチャットでも使いたいとき

スキルの形式は、Claude Code、Cowork、claude.aiのチャットで共通です。ただし、Claude Codeで自分のパソコンに作ったスキルは、Coworkやクラウドの作業には、そのままでは届きません。

公式ドキュメントでは、パソコンのスキルを、claude.aiのアカウントで有効にすることで、Cowork・クラウドの作業・同じアカウントでログインしたターミナルから使えるようになると説明されています。そのときは、アップロードにあたって次の制限がかかります。

• 設定部分で使える項目が、name・description・license・compatibility・metadata・allowed-toolsの6つに限られる（argument-hintなどはエラーになる）
• !`コマンド`のような、Claude Code独自の書き方は、claude.aiのチャットやAPIでは動かない
• claude.aiから同期されたスキルは、Claude Code側で書き換えても、claude.aiには戻らない。直すときは、claude.ai側で直す

Claude Codeだけで使うスキルと、Coworkなどでも使うスキルは、最初から分けて作っておくと、あとで困りません。

よくある質問

まとめ

スキルは、最初から完璧に作る必要はありません。まずは、毎回貼り付けている指示を1つ選んで、短いスキルにしてみてください。使いながら、うまくいかなかった点を1つずつ直していくと、自分の仕事に合った形になっていきます。

社内の業務に合わせたスキルの設計、チームでの共有と運用のルールづくりは、業務の整理とあわせて進める必要があります。INTERCREATE JAPANでは、Claude CodeやCodexの導入から、社内で使い続けられる仕組みづくりまでをお手伝いしています。