CLAUDE.mdとSkillsの違い｜使い分け判断表と移し替え手順

CLAUDE.mdとSkillsの違いは、CLAUDE.mdが「毎回のセッションの最初に必ず読み込まれる前提の情報」であるのに対し、Skillsは「必要になったときだけ本文が読み込まれる、手順や専門知識のパッケージ」であることです。毎回知っておいてほしい事実はCLAUDE.mdに、特定の作業のときだけ必要な手順や長い参考資料はSkillsに置くと、Claude Codeは少ない文脈（コンテキスト）で、より正確に動けるようになります。

Claude Codeには、このほかにも.claude/rules/、Hooks（フック）、サブエージェント、設定のpermissionsといった仕組みがあり、「どこに何を書くか」で迷いやすくなっています。この記事では、公式ドキュメント（2026年9月時点）を確認したうえで、Claude Code v2.1.283 で実際にSkillを作って動かし、読み込まれるトークン数や自動で呼び出されるかどうかを確かめた結果を載せながら、使い分けの判断表、置き場所の具体例10件、CLAUDE.mdからSkillsへの移し替え手順までを解説します。CLAUDE.md自体の書き方は姉妹記事「CLAUDE.mdの書き方」で扱っているため、ここでは使い分けと移し替えに絞ります。

CLAUDE.md・Skills・関連機能の早見表

決定的な違いは「いつ読み込まれるか」：実測で確認

公式ドキュメントでは、Skillsについて「CLAUDE.mdの内容と違い、スキルの本文は使われるときだけ読み込まれるので、長い参考資料も必要になるまでほとんどコストがかからない」と説明しています。これを実際に確かめました。

同じ150行の規約（画面の入力チェックのルール）を、3つの置き方で用意し、/context コマンドで起動直後の文脈の使用量を比べました。

# A: Skillとして置く
.claude/skills/screen-rules/SKILL.md   # frontmatter + 150行の規約

# B: .claude/rules/ に paths なしで置く
.claude/rules/screen-rules.md          # 150行の規約のみ

# C: .claude/rules/ に paths つきで置く
.claude/rules/screen-rules.md          # paths: ["src/screens/**/*.ts"] + 150行の規約

claude -p "/context" の出力から、該当する行を抜き出した結果です（Claude Code v2.1.283、パスは省略）。

## A: skill
| Memory files | 20 | 0.0% |
| Skills | 4.3k | 0.9% |
| screen-rules | Project | < 20 |

## B: rules without paths
| Memory files | 8.9k | 1.8% |
| Skills | 4.3k | 0.9% |
| Project | .../.claude/rules/screen-rules.md | 8.9k |

## C: rules with paths
| Memory files | 20 | 0.0% |
| Skills | 4.3k | 0.9% |

（Memory files の20トークンは、別に置いた2行のCLAUDE.md、Skills の4.3kは組み込みスキルなどを含む一覧全体の量です。）

Skillとして置いた場合、起動時に文脈に入ったのは説明文の20トークン未満だけでした。同じ内容をpathsなしのルールに置くと、毎セッション8.9kトークンが使われます。pathsつきのルールは、起動時には読み込まれず、該当するファイルを読んだときに読み込まれます。

「毎回は要らないが、使うときは詳しく書いておきたいもの」はSkillsに置くと、文脈を大きく節約できます。文脈が軽いほど、CLAUDE.mdに書いた大切な指示も守られやすくなります。

Skills（SKILL.md）の基本

置き場所

同じ名前のスキルがある場合は、組織 → 個人 → プロジェクトの順で優先されます。まずはプロジェクトの.claude/skills/に置き、Gitにコミットしてチームで共有する形から始めるのがわかりやすいでしょう。

SKILL.mdの書き方

SKILL.mdは、先頭のfrontmatter（---で囲んだYAML）と、その下のMarkdownの本文でできています。---はファイルの1行目に置きます。

---
name: release-note
description: リリースノートの下書きを作る。リリースノート、変更履歴、CHANGELOGの作成を頼まれたときに使う。
disable-model-invocation: true
argument-hint: "[version]"
---

バージョン $ARGUMENTS のリリースノートを作ります。

1. 前回のタグからのコミットを確認する
2. 「新機能」「改善」「修正」に分類する
3. 利用者に関係のない内部の変更は省く

よく使うfrontmatterの項目です。

本文では、$ARGUMENTS（渡された引数すべて）、$0・$1（n番目の引数）が使えます。また、行頭などに !`コマンド` と書くと、スキルが読み込まれる前にコマンドが実行され、その出力が本文に差し込まれます。

---
name: diff-summary
description: 未コミットの変更を要約する。
disable-model-invocation: true
---

## 変更されたファイル
!`git status --short`

上のファイル一覧だけを、そのまま箇条書きで出力してください。ツールは使わないでください。

新しいファイルを1つ置いた状態で claude -p "/diff-summary" を実行した結果です。git status --short の出力が差し込まれていることがわかります。

- ?? .claude/skills/diff-summary/
- ?? newfile.txt

SKILL.mdは500行以内が目安です。詳しい参考資料は、同じディレクトリに reference.md などとして分け、本文からリンクしておくと、必要なときだけ読まれます。

.claude/skills/api-guide/
├── SKILL.md         （必須。概要と手順）
├── reference.md     （詳しい仕様。必要なときに読まれる）
└── scripts/
    └── check.py     （実行するスクリプト。中身は文脈に入らない）

読み込まれるタイミング

スキルの本文は「1回読まれたら、その会話の中にずっと残る」ため、作業の途中で守ってほしいことは、1回きりの手順ではなく、作業全体に通じる指示として書くのがコツです。

誰が呼び出すかを決める

実際に確かめました。指定なしのスキル api-errors（APIのエラー形式の規約）を置いて「このプロジェクトのAPIのエラーレスポンスはどんな形式にすればいい？」と聞くと、Claudeが自分でスキルを呼び出しました。

TOOL_USE Skill {"skill": "api-errors"}
RESULT `{"error": {"code": "E-XXXX", "message": "..."}}` の形式にする。(api-errors skill)

一方、disable-model-invocation: true のスキル release-note を置いて「バージョン2.0.0のリリースノートを作って」と頼んだ場合は、スキルは呼び出されず、一般的な回答が返りました。/release-note 1.4.0 と明示的に入力すると、スキルの本文どおりに動きました。

$ claude -p "/release-note 1.4.0"
RELEASE-NOTE-SKILL-LOADED v1.4.0

（確認用に、本文を「決まった文字列を出力する」だけの内容にして試しています。）

スラッシュコマンドとの関係

カスタムのスラッシュコマンドは、Skillsに統合されました。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md は、どちらも /deploy を作り、同じように動きます。既存の .claude/commands/ のファイルもそのまま使えます。実際に .claude/commands/hello.md を置いて claude -p "/hello RJC" を実行すると、コマンドファイルの内容どおり COMMAND-FILE-LOADED RJC が返りました。

/help や /compact のような組み込みコマンドは、スキルとは別のものです。

使い分けの判断表

迷ったら、上から順に質問に答えていくと、置き場所が決まります。

それぞれの性質を、もう少し詳しく比べます。

CLAUDE.md・rules・Skillsは「Claudeへのお願い」、Hooksとpermissionsは「仕組みで保証するもの」と覚えておくと、判断がぶれにくくなります。公式ドキュメントも、CLAUDE.mdは強制される設定ではなく文脈として扱われるため、Claudeの判断に関係なく操作を止めたい場合はPreToolUseフックを使うよう案内しています。

Hooksは「確実に止める」ための仕組み

公式ガイドの例にならい、.env などの編集をブロックするフックを設定して試しました。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/protect-files.sh（公式ガイドの例をもとにしたもの）
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done
exit 0

編集を許可するモード（--permission-mode acceptEdits）で「.env の末尾に1行追加して」と頼んだ結果です（パスと一部の項目は省略）。

TOOL_USE Edit {"file_path": ".../.env", ...}
TOOL_RESULT PreToolUse:Edit hook error: ["$CLAUDE_PROJECT_DIR"/.claude/hooks/protect-files.sh]: Blocked: .../.env matches protected pattern '.env'
RESULT .envはprotect-files.shフックにより保護されており、Editツールでの編集をブロックされたため追加できませんでした。

終了コード2でツールの実行が止まり、理由がClaudeに伝わって、Claudeが状況を説明しました。.env の中身は変わっていませんでした。

permissionsは「使ってよい操作」を決める仕組み

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git commit *)"],
    "deny": ["Bash(git push *)", "Read(./.env)"]
  }
}

ルールは deny → ask → allow の順に評価され、最初に一致したものが適用されます。ユーザー設定で許可していても、プロジェクト設定で禁止していれば禁止が優先されます。

サブエージェントとSkillsの違い

同じ内容をどこに置くか：具体例10件

同じ「ルール」でも、「毎回か、特定の場面か」「お願いか、保証か」で置き場所が変わることがわかります。

CLAUDE.mdからSkillsへの移し替え手順

CLAUDE.mdが長くなってきたら、手順や長い資料をSkillsに移します。公式ドキュメントも、複数ステップの手順や、コードの一部にしか関係しない内容は、スキルやパス限定のルールに移すよう案内しています。

手順

移し替え前と後

移し替え前のCLAUDE.md（手順が混ざっている）：

# コマンド
- テスト: npm test

# リリースの手順
1. 前回のタグからのコミットを一覧にする
2. 「新機能」「改善」「修正」に分類する
3. 利用者に関係のない内部の変更は省く
4. CHANGELOG.md の先頭に追記する
5. バージョン番号を package.json に反映する

移し替え後のCLAUDE.md（事実だけ）：

# コマンド
- テスト: npm test

# 作業の入口
- リリースノートの作成は /release-note を使う

移し替え後の .claude/skills/release-note/SKILL.md：

---
name: release-note
description: リリースノートを作り、CHANGELOG.mdとバージョン番号を更新する。リリースの準備、変更履歴の作成を頼まれたときに使う。
disable-model-invocation: true
argument-hint: "[version]"
---

バージョン $ARGUMENTS のリリースを準備します。

1. 前回のタグからのコミットを一覧にする
2. 「新機能」「改善」「修正」に分類する
3. 利用者に関係のない内部の変更は省く
4. CHANGELOG.md の先頭に追記する
5. バージョン番号を package.json に反映する

CLAUDE.mdは短く保たれ、手順は必要なときだけ読み込まれる形になりました。

よくある失敗と直し方

よくある質問

Q. Skillsと.claude/commands/は、どちらを使えばよいですか？ A. これから作るならSkills（.claude/skills/<name>/SKILL.md）がおすすめです。どちらも /name で呼び出せますが、Skillsは補足ファイルを置けて、description による自動呼び出しや、呼び出す人の制御もできます。既存のコマンドファイルはそのまま使えます。

Q. スキルを作ったのに、Claudeが自動で使ってくれません。 A. description に使う場面が書かれているか、disable-model-invocation: true になっていないか、paths で対象が絞られていないかを確認してください。確実に使いたいときは /name で直接呼び出します。

Q. .claude/rules/のpathsつきルールとSkillsは、どう使い分けますか？ A. 「特定のファイルを扱うときに、常に守ってほしい規約」はpathsつきルール、「特定の作業のときに使う手順や資料」はSkillsが向いています。ルールはファイルを読んだときに自動で入り、Skillsは作業の内容に応じて呼び出されます。

Q. チームで共有するには、どこに置けばよいですか？ A. ./CLAUDE.md、.claude/rules/、.claude/skills/、.claude/agents/、.claude/settings.json をGitにコミットします。個人の好みは ~/.claude/ 配下や CLAUDE.local.md、.claude/settings.local.json に分けると、チームのファイルと混ざりません。

まとめ

• CLAUDE.mdは毎回全文が読み込まれる「前提」、Skillsは必要なときだけ本文が読み込まれる「手順と知識」です
• 実測では、150行の規約がSkillsなら起動時20トークン未満、paths なしのルールなら8.9kトークンでした
• SKILL.mdは.claude/skills/<name>/SKILL.mdに置き、nameとdescriptionを書くのが基本です
• 副作用のある作業はdisable-model-invocation: trueで、自分のタイミングだけで実行します
• カスタムのスラッシュコマンドはSkillsに統合されており、/nameで同じように呼び出せます
• 「必ず守らせたい」ことはHooksとpermissionsで、大量の出力を伴う作業はサブエージェントで扱います
• CLAUDE.mdが長くなったら、棚卸し→移し先の決定→SKILL.md作成→削除→確認の順で移し替えます

株式会社RJCでは、AIに渡す前提と手順を整理し、チームで再利用できる形にする工夫を、プロジェクトの中で仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。