【Claude Code】スキル（Skills）の作り方｜SKILL.mdの書き方

Claude CodeのSkills（スキル）とは

Skillsは、ひとことで言うとClaudeに渡す「手順書」です。SKILL.mdというファイルにやり方やルールを書いておくと、Claudeが必要な場面でその内容を読み込み、指示に従って作業します。

呼び出し方は2通りあります。

CLAUDE.mdとの大きな違いは、本文が「使われるときだけ」読み込まれることです。長い手順書を何個ストックしても、使わない間にコンテキスト（Claudeが一度の会話で扱える情報量）に載るのは名前と説明文だけなので、消費はごくわずかです。

また、以前あった「カスタムスラッシュコマンド」（.claude/commands/）は現在Skillsに統合されています。昔のコマンドファイルもそのまま動きますが、これから作るならスキル形式が推奨されています。

スキルの作り方｜最小のSKILL.mdを5分で動かす

まずは動くものを作ってみましょう。スキルは、skillsフォルダの中に「スキル名のフォルダ」を作り、SKILL.mdを1枚置くだけで完成します。

題材は、メールや資料づくりなど身近な文章に使える「文章の校正チェック」スキルです。

1. スキル用のフォルダを作る

   ターミナルで次のコマンドを実行します（エクスプローラーやFinderで直接フォルダを作ってもかまいません）。

   ターミナル

   Copy

   mkdir -p ~/.claude/skills/proofread

   冒頭の~はホームディレクトリ（WindowsならC:\Users\ユーザー名、Macなら/Users/ユーザー名）のことです。ここに置いたスキルは、PCのどのフォルダでClaude Codeを起動しても使えます。

   また、このフォルダ名（proofread＝「校正する」という意味の英語）が、そのまま/proofreadというコマンド名になります。

2. SKILL.mdを書く

   作ったフォルダの中に、SKILL.mdという名前でファイルを作ります。全体の構成はこうなります。

   ホームディレクトリ
   └── .claude/
       └── skills/
           └── proofread/       ← 手順1で作ったフォルダ
               └── SKILL.md     ← このファイルを作る
   

   ---で挟んだ部分（フロントマター）に説明文を書き、その下に指示の本文を書くだけです。

   SKILL.md

   Copy

   ---

   description: 文章の校正チェックを行う。文章の推敲や見直しを頼まれたときに使う。

   ---

    

   文章を校正するときは、次の順番でチェックしてください。

   - 誤字脱字・変換ミスがないか

   - 一文が長すぎないか（60字を目安に2文に分ける）

   - 文体が「です・ます」調で統一されているか

3. 動作確認する

   校正したい文章を貼り付けて（またはファイルを開いて）/proofreadと入力すれば、書いた観点に沿ってチェックが始まります。「この記事を見直して」と自然に頼んだ場合も、descriptionに合致すればClaudeが自動でこのスキルを読み込みます。

   スキルが認識されているか不安なときは、Claudeに「利用可能なスキルは何ですか？」と聞くと一覧で確認できます。

これだけで完成です。チェック項目は自分の仕事に合わせて自由に書き換えてください。コードのレビューでも、日報の確認でも、スキルの作り方は変わりません。

SKILL.mdの追加や編集はセッション中に自動で反映されるので、基本的に再起動は不要です。ただし、~/.claude/skills/フォルダ自体をセッション中に初めて作った場合だけは、Claude Codeの再起動が必要です（新しいフォルダの監視が再起動時に始まるため）。

スキルの置き場所は2種類

スキルをどこに置くかで、使える範囲が変わります。

ここでの「プロジェクト」は、Claude Codeを起動している作業フォルダのことです。プロジェクト側の.claude/skills/はGit（ファイルの変更履歴を管理する仕組み）に登録できるので、チーム全員で同じスキルを共有できます。このほか、組織全体に配布するEnterprise用の置き場所や、プラグインに同梱する形式もあります。

SKILL.mdの書き方（フロントマターの設定項目）

最小構成が動いたら、次はSKILL.mdの中身を整えていきます。SKILL.mdは、冒頭の---で挟んだ設定欄（フロントマター）と、その下に書く指示の本文の2つでできています。まずは設定欄から見ていきましょう。

自動で呼ばれるかはdescriptionで決まる

フロントマターの項目はすべて省略可能ですが、descriptionだけは書くことが推奨されています。なぜなら、スキルが自動で呼ばれるかどうかは、descriptionの書き方でほぼ決まるからです。Claudeは常時、各スキルの名前とdescriptionだけを見ていて、依頼内容と照らし合わせて「このスキルを読み込むか」を判断しています。

コツは、「何をするか」と「いつ使うか」の両方を書くことです。

たとえば「文章の校正チェックを行う。」とだけ書くと、/proofreadと直接入力すれば動くのに、「この記事を見直して」と自然に頼んだときは読み込まれない、ということが起こりがちです。そこで「文章の推敲や見直しを頼まれたときに使う。」という一文を足し、自分が実際に頼むときに言いそうな言葉（推敲・見直し）を入れておくと、自然な頼み方でも読み込まれやすくなります。

NG: 文章の校正チェックを行う。
    →「何をするか」だけで、いつ使うかが分からない

OK: 文章の校正チェックを行う。文章の推敲や見直しを頼まれたときに使う。
    →「いつ使うか」＋依頼に出てくる言葉（推敲・見直し）が入っている

なお、descriptionが長すぎると、後半が切り捨てられてClaudeに読まれない場合があります（読み込まれるのは先頭から1,536文字まで）。切られるのは後ろ側なので、「いつ使うか」のような大事な内容ほど文の前半に書いておくのがコツです。

よく使うフロントマターの項目

description以外によく使う項目をまとめます。繰り返しになりますが、すべて省略可能です。

name

スキル一覧に表示される名前。省略するとフォルダ名がそのまま表示される
※/の後に入力するコマンド名は、nameではなくフォルダ名で決まる

description

スキルの説明文。「何をするか」と「いつ使うか」を書く。Claudeはここを見て、自動で読み込むかどうかを判断する（書くことが推奨されている唯一の項目）

argument-hint

/スキル名の入力時に「後ろに何を付ければいいか」の案内として表示されるヒント
例：argument-hint: "[文字数]"
※[ ]を含む値は引用符で囲む。囲まないと書式エラーでフロントマター全体が無効になる

disable-model-invocation

trueにすると、Claudeが自分の判断でこのスキルを使うことがなくなり、自分で/スキル名と入力したときだけ動く。実行のタイミングを自分で決めたい作業に付ける

user-invocable

falseにすると、/メニューにこのスキルが出なくなる。自分で呼び出す作業ではなく、Claudeに覚えておいてほしい前提知識を渡すときに使う

allowed-tools

Claude Codeは通常、コマンド実行などのたびに「実行していいですか？」と確認してくるが、ここに書いたツールはこのスキルの実行中だけ確認なしで使えるようになる
例：allowed-tools: Bash(git add *) Bash(git commit *)（gitのコミット操作を確認なしで許可）

model

このスキルの実行にだけ使うAIモデルの指定。かんたんな定型作業を、速くて料金の安いモデルに任せるといった使い方ができる

context / agent

context: forkと書くと、スキルがメインの会話から切り離された別の作業場所（サブエージェント）で実行される。agentは、そのとき実行役になるエージェントの指定

本文は「簡潔な指示」に絞る

本文には、Claudeに従わせたい手順やルールをMarkdownで書きます。注意したいのは、スキルは一度読み込まれると、その内容がセッションの間ずっとコンテキストに残ることです。

長い説明や背景をダラダラ書くと、それが毎ターン分のコストになります。「何をするか」を箇条書きで簡潔に書き、詳しい資料は後述の補助ファイルに分けるのが公式の推奨です（SKILL.md本体は500行以下が目安とされています）。

スキルに引数を渡す（$ARGUMENTS）

スキルは呼び出すときに引数を受け取れます。本文に$ARGUMENTSと書いておくと、/スキル名の後ろに入力したテキストがそこに展開されます。

文字数を指定して要約させる「summarize」スキルの例です。

/summarize 200のように実行すると、$ARGUMENTSの部分が200に置き換わった状態でClaudeに渡ります。

引数が複数あるときは、$0（1つ目）、$1（2つ目）のように、何番目かを指定して1つずつ取り出すこともできます。$ARGUMENTSには入力した引数の全体（例：200 初心者）がひとかたまりで入るため、複数の値を文中の別々の場所に差し込みたいときは$0や$1を使います。

たとえば「文字数」と「読者層」の2つを受け取る「rewrite」スキルなら、本文をこう書きます。

このスキルを呼び出すときは、argument-hintに書いた内容が入力欄に次のように表示されます。

/rewrite 200 初心者のように実行すると、$0が200に、$1が初心者に置き換わり、「対象の文章を 200 字以内で、初心者 にも伝わる表現に書き直してください。」という指示になります。

スペースを含む値は"社会人 1年目"のように引用符で囲むと、まとめて1つの引数として渡せます。

一歩進んだSKILL.mdの書き方

コマンドの実行結果を埋め込む（動的コンテキスト）

本文に!`コマンド`という書き方（!＋バッククォート囲み）をすると、スキルの内容がClaudeに渡る前にそのシェルコマンドが実行され、行が実行結果に置き換わります。

公式ドキュメントで最初の例として紹介されている「変更内容の要約スキル」が分かりやすいので、日本語にして紹介します（gitを使った開発向けの例ですが、仕組みの理解用として見てください）。

Claudeが自分でgitコマンドを実行するのではなく、最初から実際のdiffが貼り込まれた状態の指示が届くのがポイントです。推測ではなく実データに基づいた回答が返ってきます。gitに限らず、出力がテキストになるコマンドなら何でも埋め込めます。

補助ファイルで手順書を分割する

スキルのフォルダには、SKILL.md以外のファイルも入れられます。詳細なリファレンスや実行用スクリプトを分けておき、SKILL.md側から「詳細は◯◯を参照」と書いておくと、Claudeは必要になったときだけそのファイルを読みに行きます。

proofread/
├── SKILL.md        ← 本体（必須）。概要と手順だけ書く
├── reference.md    ← 詳しい表記ルールの一覧（必要なときだけ読まれる）
└── scripts/
    └── check.sh    ← Claudeに実行させるスクリプト

この仕組みのおかげで、SKILL.md本体を短く保ったまま、大きな資料をスキルに持たせられます。

勝手に実行されないようにする

ファイルの一括変更や外部への送信のように、実行すると簡単には元に戻せない操作は、Claudeの判断で自動実行されると困ります。

「実行のタイミングを自分で決めたいスキル」には、disable-model-invocation: trueを付けます。これで自動実行されなくなり、自分が/スキル名と入力したときだけ動くようになります。

スキルがうまく動かないときのチェックリスト

つまずきやすいポイントと対処法を、よくあるケース別にまとめます。

自動で呼ばれない

/メニューにスキル名が出てこない

手動では動くのに、descriptionが効いていない気がする

フロントマターの書式が崩れていると、本文は読み込まれるのにdescriptionなどの設定だけが無視されます。原因に気づきにくいパターンなので、次の4点を確認してください。

それでも原因が分からないときは、claude --debugで起動すると、フロントマターの読み取りエラーの内容を確認できます。

よくある質問

Q. 昔作ったカスタムスラッシュコマンド（.claude/commands/）はどうなる？

A. そのまま動きます。カスタムコマンドはSkillsに統合されており、.claude/commands/deploy.mdと.claude/skills/deploy/SKILL.mdはどちらも/deployとして同じように機能します。ただしスキル形式のほうが補助ファイルの同梱など機能が多いので、新規に作るならスキル形式がおすすめです。

Q. CLAUDE.mdとスキルはどう使い分ける？

A. 「毎回必要な事実」はCLAUDE.mdに、「特定の場面でだけ使う手順」はスキルに置きます。公式ドキュメントには、CLAUDE.mdのセクションの中身が「事実の説明」から「作業の手順」に変わってきたら、スキルに切り出すサインだという趣旨の説明があります。たとえば、「文章は『です・ます』調で書く」のような常時使うルールはCLAUDE.md向きで、「公開前の校正はこの手順で行う」のような場面限定の手順はスキル向きです。

Q. スキルとサブエージェントは何が違う？

A. スキルは「手順書」で、メインの会話の中に読み込まれてClaude自身が従います。サブエージェントは「別の作業者」で、独立したコンテキストで作業して要約だけを持ち帰ります。詳しい比較と使い分けは、導入で紹介した記事で解説しています。

Q. スキルはClaudeに書いてもらえる？

A. 書いてもらえます。「◯◯をするスキルを作って」と頼めば、フロントマター付きのSKILL.mdを生成してくれます（公式ドキュメントでも推奨されている方法です）。ただしClaudeの書くスキルは本文が長くなりがちなので不要な説明は削ること、そして意図どおり呼び出されるかは実際に使って確認することをおすすめします。

Q. チームでスキルを共有するには？

A. プロジェクトの.claude/skills/にスキルを置いてGitに登録すれば、そのプロジェクトを自分のPCに複製（clone）したメンバー全員が同じスキルを使えます。なお、プロジェクトのスキルにallowed-tools（ツールの事前承認）が設定されている場合、そのフォルダの信頼確認に同意してから有効になります。共有されたプロジェクトを信頼する前に、中のスキルには目を通しておきましょう。

まとめ

Claude CodeのSkills（スキル）の作り方を解説しました。

まずは「毎回チャットに貼り付けている指示」を1つ、そのままSKILL.mdにするところから始めてみてください。細かい仕様は更新されることがあるので、最新の情報は以下の公式ドキュメントで確認してください。

• スキルで Claude を拡張する - Claude Code 公式ドキュメント
• スキル作成のベストプラクティス - Claude 公式ドキュメント

スキルと混同しやすい「サブエージェント」との違い・使い分けは、以下の記事で比較表つきで解説しています。