SKILL.mdの書き方と使い方：Claude Codeに手順を覚えさせる

本記事では、Claude Codeに特定タスクの手順を渡すための仕組みであるスキル（Skills） について解説します。スキルはSKILL.mdという名前のMarkdownファイルを中心としたディレクトリで構成され、関連するタスクが要求されたときにだけClaudeに読み込まれます。SKILL.mdの書き方、descriptionがトリガー精度を左右する仕組み、そしてPythonスクリプトを同梱して実際の処理まで任せる方法を、2つの実践例を通して扱います。

Claude Code自体のインストールや起動方法については、当サイトの「Claude Code CLIの導入と基本操作（Windows）」を参照してください。本記事はClaude Codeのインストールと初回起動が完了している前提で進めます。また、Claude Codeにルールを渡すのに用いるCLAUDE.mdの概要については「CLAUDE.mdの書き方と運用：Claude Codeにプロジェクトのルールを渡す」に記載しています。

本記事の動作確認は2026年5月時点を想定しています。

目次

• スキルとは
• スキルの起動方法
  • 自動起動
  • 手動起動
• SKILL.mdの構造
• 配置場所
  • 適用対象の選択
  • Pluginとして管理する場合
• 実践例１：議事録フォーマッタを作る
  • SKILL.mdの作成
  • 動かしてみる
  • descriptionを変えて挙動を確認する
• 実践例２：CSV集計スキルを作る
  • スクリプトを用意する
  • SKILL.mdを書く
  • 動かしてみる
• CLAUDE.mdとの使い分け
• まとめ
• 関連記事

スキルとは

スキルは、SKILL.mdという名前のファイルを中心としたディレクトリで構成されるClaude向けの手順書です。タスクの内容に応じて、Claudeが必要だと判断したスキルだけがその場で読み込まれます。

CLAUDE.mdとSKILL.mdの違いは次のとおりです。

「常に使うルール」はCLAUDE.mdに、「特定の場面でだけ使う手順」はスキル（SKILL.md）に分けるのが基本的な方針です。

CLAUDE.mdを肥大化させずにルールを整理したいときには、.claude/rules/でpathsフロントマターを使うと、特定のファイルを操作するときだけルールが読み込まれるため、コンテキストウィンドウを節約できます。

スキルはディレクトリ単位であり、SKILL.mdの隣にPythonスクリプトやテンプレートファイル、参照用ドキュメントなどを同梱できます。これにより、Claudeはそれらを必要に応じて読み込んだり実行したりできます。

スキルの起動方法

スキルの起動には2つの方法があります。

自動起動

ユーザーのリクエスト内容がSKILL.mdのdescriptionにマッチすると、Claudeが自動でそのスキルを読み込んで使用します。たとえば、descriptionに「会議メモ」「議事録」と書かれたスキルがあれば、ユーザーが「この会議メモを整理して」とリクエストしたときに自動的に起動します。

手動起動

Claude Codeの対話モードで/スキル名と入力すると、スキルを直接呼び出せます。スキル名はディレクトリ名です。たとえば~/.claude/skills/meeting-notes/SKILL.mdであれば、/meeting-notesで起動できます。後述のSKILL.mdでnameを指定すると、その名前がエイリアスとして使えるようになり、/nameと入力することでそのスキルを呼び出せます。

後述するdisable-model-invocationフィールドをtrueにすると、自動起動を無効にして手動起動のみに限定できます。デプロイやコミットなど、意図しないタイミングでの実行を避けたいスキルに有効です。

SKILL.mdの構造

SKILL.mdは、先頭にYAML形式のメタデータを置き、その下に本文として手順を書くという構造になっています。最小構成は次のとおりです。

---
description: いつ・どのような場面でこのスキルを使うかの説明
---

# マークダウンコンテンツ

ここにClaudeに実行させたい手順を書きます。

YAMLフロントマター（---マーカー間）はClaudeにスキルをいつ使用するかを伝え、マークダウンコンテンツにはスキルを実行したときにClaudeに実行させる手順を記述します。すべてのフィールドは省略可能ですが、descriptionは指定が推奨されます。

YAMLフロントマターに記述できる主なフィールドには、以下のようなものがあります。

このほかにもcontext（サブエージェントでの実行）、agent（使用するサブエージェントの指定）、hooks（スキルのライフサイクルに紐づくフック）などのフィールドがあります。全フィールドの一覧は公式ドキュメントを参照してください。

descriptionはスキルの動作精度を大きく左右します。Claudeはdescriptionを読んでスキルを使うかどうかを判断するため、曖昧だとスキルが起動しません。

descriptionには、「何をするスキルか」を書き、「トリガーとなる用語」を含めると動作精度が上がります。

配置場所

適用対象の選択

スキルは、適用対象に応じて以下のいずれかのディレクトリに置きます。

<skill-name>と<plugin>はディレクトリ名であり、ユーザーが任意ディレクトリを使うことができます。

スキル名が重複している場合は、Enterprise>Personal>Projectの順で優先されます。プラグインスキルについては、独自の名前空間を持つため、他のレベルとスキル名が競合することはありません。

個人的な用途ですべてのプロジェクトで使いたい汎用的なスキルはPersonalに、個別のプロジェクトで限定して使いたいスキルはProjectに配置するのが基本です。チームやコミュニティに対して配布・共有したい場合や、スキルを含む複数のコンポーネント（エージェント、フック、MCPサーバーなど）をまとめて複数プロジェクトで再利用したい場合にはPluginが選択肢になります。

Pluginとして管理する場合

Pluginは、スキルを含む複数のコンポーネント（エージェント、フック、MCPサーバーなど）を1つのディレクトリにまとめてパッケージ化する仕組みです。スキルはskills/ディレクトリにスキルを配置します。

my-plugin/
├── .claude-plugin/  # オプション。plugin.jsonを置く場合のみ必要
│   └── plugin.json
└── skills/
    └── meeting-notes/
        └── SKILL.md

ここで、my-pluginは前述の＜plugin＞に相当し、任意のディレクトリを指定できます。

.claude-plugin/plugin.jsonはオプションです。省略した場合、Claude Codeはデフォルトの場所からコンポーネントを自動検出し、ディレクトリ名からプラグイン名を導出します。plugin.jsonが必要なのは、プラグイン名・バージョン・説明などのメタデータを明示したい場合や、コンポーネントのパスをカスタマイズしたい場合です。詳細は公式ドキュメント（Plugins reference）を参照してください。

ローカルでの動作確認は--plugin-dirフラグで行います。

claude --plugin-dir ./my-plugin

Plugin化したスキルのコマンド名は/my-plugin:meeting-notesのようにプラグイン名が接頭辞としてつきます。

プラグインが有効なのは、このコマンドを用いて開いたClaudeを閉じるまでです。閉じてしまえば無効になるので、プラグインファイルを削除したい場合はプラグインを置いているディレクトリをそのまま削除します。

実践例１：議事録フォーマッタを作る

SKILL.mdの作成

最小構成のスキルとして、雑に書かれた会議メモを整形するスキルを作ります。ディレクトリ構成を以下のようにします。

~/.claude/skills/
└── meeting-notes/
    └── SKILL.md

そして、SKILL.mdを作成します。~/.claude/skills/meeting-notes/SKILL.mdに次の内容を記述します。

---
name: meeting-notes
description: 会議メモ、議事録、打ち合わせメモを渡されたときに使用する。雑然としたメモを「決定事項」「ToDo」「論点」の3つに分類し、Markdownで整形する。
---

# 議事録フォーマッタ
ユーザーから会議メモを受け取ったら、以下のフォーマットで整形してください。

## 出力フォーマット
```markdown
# 議事録：<会議名（推測できれば）>

## 決定事項
- ...

## ToDo
- [ ] <内容>（担当：<名前>、期限：<日付>）

## 論点・未解決事項
- ...
```

## 分類の基準
- **決定事項**：その場で結論が出たもの。「〜することに決まった」「〜で進める」など。
- **ToDo**：誰かが今後実行するアクション。担当者と期限を可能な限り抽出する。
- **論点**：結論が出ていない議題、保留事項、次回への持ち越し。

## 注意
- 元のメモに無い情報を補わない。担当者や期限が書かれていなければ「未定」と記す。
- 雑談や脱線は出力に含めない。

動かしてみる

会議メモをmeeting.txtとして保存します。Claude Codeはデフォルトで起動したディレクトリとそのサブディレクトリ内のファイルにのみアクセスできるため、claudeを実行するディレクトリ以下に置いてください。

5/20 定例
- 新機能Aのリリースは6/15で確定
- 田中さんがドキュメント書く、5/30まで
- パフォーマンス問題はまだ調査中
- ランチの話で盛り上がった
- 最近一蘭のラーメンにはまっている
- 次回までに鈴木さんがベンチマーク取る
- 次回打ち合わせは6/20

Claude Codeを起動し、ファイルを指定して処理を依頼します。

meeting.txt の会議メモを整理して

descriptionに書いた「会議メモ」「議事録」というキーワードに反応してmeeting-notesスキルが自動で読み込まれ、整形済みの議事録が返ってきます。「ランチの話」のような雑談が除外され、ToDoは担当者と期限つきで抽出されるはずです。以下は、実際に試した結果になります。

● Skill(meeting-notes)
  ⎿  Successfully loaded skill

● meeting.txt を読み込みます。

  Read 1 file (ctrl+o to expand)

● 内容を確認しました。スキルのフォーマットに従って整理します。

  ---
  議事録：5/20 定例

  決定事項

  - 新機能Aのリリースは6/15で確定

  ToDo

  - [ ] ドキュメント作成（担当：田中、期限：5/30）
  - [ ] ベンチマーク取得（担当：鈴木、期限：未定）

  論点・未解決事項

  - パフォーマンス問題は調査中（未解決）
  - 次回打ち合わせは6/20

/meeting-notesで手動起動する場合はファイルパスを引数として渡します。

/meeting-notes meeting.txt

descriptionを変えて挙動を確認する

descriptionの効果を確認するため、次のように内容を書き換えてみます。

description: 要約してと言ったときだけ実行して

この状態で同じ会議メモを渡して「meeting.txt の会議メモを整理して」といっても、スキルを使わなくなります。逆に「meeting.txt の会議メモを要約して」するとスキルが発動します。LLMなので同じ結果にならないこともありますが、その場合は自分で思うように試してみて、どのようにすると発動したり、しなくなったりするのかを試してみると面白いです。

実践例２：CSV集計スキルを作る

スキルの強みは、SKILL.mdの手順書だけでなく、補助ファイルを同梱できる点にあります。ここではPythonスクリプトを同梱したスキルを作り、Claudeが手順書を読みつつスクリプトを実行する流れを確認します。題材は、CSVを渡されたら集計結果をMarkdown表にまとめるスキルです。ディレクトリ構成を以下のようにします。

~/.claude/skills/
└── csv-summary/
    ├── SKILL.md
    └── summarize.py

SKILL.mdの隣にPythonスクリプトを置きます。SKILL.md本文の中からこのスクリプトを参照し、Claudeに実行させます。

スクリプトを用意する

~/.claude/skills/csv-summary/summarize.pyを作成します。指定されたCSVファイルを読み込み、行数・列ごとの統計をJSON形式で出力するスクリプトです。

"""CSVファイルを集計してJSONで結果を返す。

使い方:
    python summarize.py <csv_path>
"""
import json
import sys
import pandas as pd


def summarize(csv_path: str) -> dict:
    df = pd.read_csv(csv_path)
    result = {
        "rows": len(df),
        "columns": list(df.columns),
        "numeric_summary": {},
        "categorical_summary": {},
    }
    for col in df.columns:
        if pd.api.types.is_numeric_dtype(df[col]):
            result["numeric_summary"][col] = {
                "min": float(df[col].min()),
                "max": float(df[col].max()),
                "mean": float(df[col].mean()),
            }
        else:
            counts = df[col].value_counts().head(5).to_dict()
            result["categorical_summary"][col] = counts
    return result


if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python summarize.py <csv_path>", file=sys.stderr)
        sys.exit(1)
    print(json.dumps(summarize(sys.argv[1]), ensure_ascii=False, indent=2))

SKILL.mdを書く

~/.claude/skills/csv-summary/SKILL.mdを作成します。スクリプトの存在と使い方をSKILL.mdの中で明示するのがポイントです。スクリプトのパスには${CLAUDE_SKILL_DIR}を使うと、スキルがPersonal・Project・Pluginのどの場所に配置されても正しいパスに展開されます。

---
name: csv-summary
description: CSVファイルを渡されたときに使用する。同梱のsummarize.pyで集計し、結果をMarkdown表にまとめて出力する。
---

# CSV集計スキル
ユーザーからCSVファイルを渡されたら、以下の手順で集計結果を返してください。

## 手順
1. 同梱の`summarize.py`を、CSVファイルのパスを引数にして実行する。
   ```bash
   python ${CLAUDE_SKILL_DIR}/summarize.py <CSVファイルのパス>
   ```
2. スクリプトはJSONを標準出力に返す。これをパースする。
3. 結果を次の形式のMarkdown表にまとめて出力する。

## 出力フォーマット
```markdown
## CSV集計結果

- 行数：<rows>
- 列数：<columnsの要素数>

### 数値列の統計

| 列名 | 最小値 | 最大値 | 平均 |
|---|---|---|---|
| ... | ... | ... | ... |

### カテゴリ列の上位5件

| 列名 | 値 | 件数 |
|---|---|---|
| ... | ... | ... |
```

## 注意
- スクリプトの実行に失敗した場合は、エラー内容をそのまま報告する。

実行コマンドをpythonとしていますが、テスト環境に合わせて変更してください。

動かしてみる

集計したいCSVファイル（例：sales.csv）をclaudeを実行するディレクトリ（あるいはそれ以下の階層のディレクトリ）に配置します。

日付,商品名,地域,担当者,数量,単価,売上金額
2026-04-01,ノートPC,東京,田中,3,120000,360000
2026-04-02,マウス,大阪,鈴木,10,3000,30000
2026-04-03,キーボード,東京,田中,5,8000,40000
2026-04-04,ノートPC,名古屋,佐藤,2,120000,240000
2026-04-05,モニター,大阪,鈴木,4,45000,180000
2026-04-06,マウス,東京,田中,15,3000,45000
2026-04-07,キーボード,名古屋,佐藤,3,8000,24000
2026-04-08,ノートPC,東京,田中,1,120000,120000
2026-04-09,モニター,東京,田中,2,45000,90000
2026-04-10,マウス,名古屋,佐藤,8,3000,24000
2026-04-11,キーボード,大阪,鈴木,6,8000,48000
2026-04-12,ノートPC,大阪,鈴木,2,120000,240000
2026-04-13,モニター,名古屋,佐藤,3,45000,135000
2026-04-14,マウス,東京,田中,12,3000,36000
2026-04-15,キーボード,東京,田中,4,8000,32000

Pythonの仮想環境を作成して、pandasをインストールします。

python -m venv .venv
source .venv/bin/activate
pip install pandas

これらのコマンドはお使いのテスト環境に合わせてください。そして、Claude Codeを対話モードで起動して、次のプロンプトを渡します。

sales.csv を集計して

descriptionの「CSVファイル」というキーワードに反応してスキルが自動で読み込まれ、ClaudeはSKILL.mdの手順に従ってsummarize.pyを実行し、結果をMarkdown表にまとめて返します。以下は、実際に試した結果になります。

手動起動する場合はファイルパスを引数として渡します。

/csv-summary sales.csv

このとき重要なのは、CSV集計のロジック自体はSKILL.mdに書かれていないという点です。集計処理はPythonスクリプトに任せ、SKILL.mdは「いつ・どのスクリプトを・どう使うか」だけを記述しています。手順はMarkdown、処理はコードという役割分担が、補助ファイル同梱型スキルの基本的な考え方です。

CLAUDE.mdとの使い分け

判断に迷ったときは、「このルールはセッション中に1回も使われないことがあるか？」を考えると整理しやすくなります。使われないことがあるならスキル、毎回使うならCLAUDE.mdです。

公式ドキュメントではCLAUDE.mdは200行以内を目安とすることが推奨されています。肥大化した場合は、特定のファイルパスにのみ適用されるpath-scoped rules（.claude/rules/配下のルールファイル）に分離することが推奨されています（How Claude remembers your project）。一方、特定のタスクでのみ必要な手順はスキルに切り出すのが適切です（Extend Claude Code）。

まとめ

スキルは、CLAUDE.mdを補完する「必要なときだけ読まれる手順書」の仕組みです。起動方法は、descriptionにマッチした場合の自動起動と、/スキル名による手動起動の2通りがあります。最小構成ではSKILL.md単体で動きますが、Pythonスクリプトなどの補助ファイルを同梱することで、Claudeに実際の処理まで任せられるようになります。

SKILL.mdのdescriptionがトリガーの精度を決めるため、ここを具体的に書くことが何より重要です。CLAUDE.mdで土台を固め、繰り返し発生する作業をスキルとして切り出していくと、Claudeに任せられる作業の幅が広がります。

関連記事