【Claude Code】Skills に入れるもの、入れないもの。判断基準を徹底解説
こんにちは、とまだです。
先日、「Claude Code の7つの拡張機能、結局どう使い分ければいいの？」という記事を書きました。
Claude Code の7つの拡張機能、結局どう使い分ければいいの？
その後、そちらに連動した Youtube動画 も公開したところ、こんな質問をいただきました。
Skillsに各画面の設計書を配置するのは良いですか？それともClaude Codeとは関係ないdocsに配置がおすすめですか？
こちらの質問を受けて、確かにややこしいところだと感じましたので、改めて解説させていただきます。
今回伝えたいことの要点は、Skills には「考え方・ガイドライン」を、設計書などの「成果物」は別の場所に置くということです。一言で言えば、「知識」と「決定事項」を分けて管理する、ということになります。
忙しい人のために要約
この記事のポイントを3行でまとめます。
- Skills は「こうするとうまくいく」という考え方・ベストプラクティス置き場
- 設計書やスペックは「ベストプラクティスをもとにした成果物」なので外に出す
- 判断基準は「繰り返し参照するか？」「比較的安定した内容か？」の2軸
「Skills に設計書を置いていい？」という疑問
この質問は、非常に良い質問だと感じています。なぜなら、私自身も最初は「全部Skills に入れればいいのでは？」と考えていたからです（正直、今でも迷うことはあります）。
ただ、実際に運用してみると、Skills に入れるべきものと、そうでないものには明確な違いがあることに気づきます。その違いを理解すると、プロジェクトの構成がスッキリします。
「考え方」と「成果物」で整理する
私は以下のように使い分けています。
| 分類 | 置き場所 | 例 |
|---|---|---|
| 考え方・ガイドライン | Skills | 「画面をこう設計すべき」というルール |
| 成果物・ドキュメント | docs/ や specs/ | 「この画面はこう設計した」という結果 |
前回の記事で使ったコンビニの例えで言うと、こうなります。
- Skills = マニュアル棚にある「接客マニュアル」「陳列ガイドライン」
- 成果物 = 「今月のシフト表」「今日の発注リスト」
マニュアルは何度も参照して、いろんな場面で使えます。一方、シフト表は今月だけのものであり、来月には新しいものになります。
つまり、再利用可能かどうかが一つの判断基準になるわけです。
設計書をSkills 外に置く理由
たとえば、「ユーザー一覧画面の設計書」を考えます。
設計書をSkills ではなくdocsに置く理由は2つあります。
1つ目は、決定事項であるからです。あくまで考え方やガイドラインに基づいて決められた結果であり、再利用可能な知識ではありません。
2つ目は、要件変更で内容が変わるからです。「やっぱり検索機能を追加しよう」となれば、設計書は書き換わります。ベストプラクティスのように「こうすべき」という普遍的な内容ではないわけです。
逆に、docs ではなくSkills に向いているものは、こういうものだと思います。
- 「画面設計時のチェックリスト」
- 「UIコンポーネントの命名規則」
- 「状態管理の設計パターン」
これらは、どの画面を作るときにも参照できます。つまり今後も繰り返し使える知識なのです。
「『〇〇画面の設計書』は成果物、『画面設計のルール』は考え方」と覚えておくと、迷いにくくなります。
迷った時の「2つの質問」
実際には、グレーゾーンもあります。そんな時は、次の2つの質問で判断してみてください。
質問1は「繰り返し参照する知識か？」です。
- Yes → Skills に入れる候補
- No → プロジェクト固有のdocsへ
ここで言う「繰り返し」には、他のプロジェクトでの再利用だけでなく、同じプロジェクト内で何度も参照するケースも含まれます。たとえば、「このプロジェクト専用のコーディング規約」や「このチーム独自のレビュー観点」も、繰り返し使うならSkills に入れる価値があるでしょう。
質問2は「比較的安定した内容か？」です。
- Yes → Skills に入れる候補
- No → プロジェクト固有のdocsへ
ただし、「安定」といっても永久に変わらないわけではありません。ベストプラクティス自体も、技術の進化や経験の蓄積で更新されます。大事なのは、頻繁に変わる「決定事項」ではなく、ある程度の期間有効な「考え方」かどうかです。
たとえば、「React + TypeScriptでのフォーム設計パターン」は、繰り返し使えるし、基本的な考え方は安定しています。Skills向きの内容です。
一方、「このプロジェクトのログイン画面の仕様」は、要件変更で内容が変わります。これはdocs/に置く方が適切です。
私の使い分け例と注意点
参考までに、私が実際に使っているディレクトリ構成を紹介します。
# グローバル
~/.claude/skills
├── planning-tickets/ # チケット計画のベストプラクティス
├── designing-requirements/ # 要件設計のガイドライン
└── ui-ux-designing/ # UI/UX設計パターン
# プロジェクト固有
プロジェクト/.claude/
├── skills / # このプロジェクト専用
│ └── project-coding-rules/ # プロジェクト固有のコーディング規約
│
└── docs/ # 成果物
├── architecture.md # アーキテクチャ設計書
└── ui-designs/ # 画面設計書
ポイントは、グローバルスキル（どのプロジェクトでも使える）とプロジェクト専用スキル（このプロジェクトだけで使う）を分けている点です。
どちらも「繰り返し参照する知識」であり、「成果物」はdocs/に分離しています。
ただ、この「考え方 vs 成果物」という分け方にも限界があります。たとえば、「コンポーネントのインターフェース定義」は考え方なのか成果物なのか、判断が難しいケースです。
また、ファイルの置き場所を厳密に分けすぎると、「あれ、これどこにあったっけ？」となることもあります。
したがって、「迷ったらdocs/に置いて、必要になったらSkills に移動する」くらいの気楽さがちょうどいいのではないかと考えています。
実際にSkillsを作成する方法については、別の記事で詳しく解説しています。
Claude Code Skillsの作り方！SKILL.mdの書き方から references フォルダの活用まで
Skillsの作り方そのものを基礎から学びたい場合は、拙著『Claude Codeで作って学ぶ AI駆動アプリ開発入門』（技術評論社、2026年9月8日発売）の5.5節と付録Cで、SKILL.mdの書き方から/code-reviewのようなスキル作成の実践まで扱っています。
スキルのほかにも、伝わる指示の出し方やタスクの分割方法など、AIとの協業をスムーズにする考え方もハンズオンで扱う構成です。
まとめ
Skills に何を入れるべきか、整理してきました。
- Skillsには「考え方・ガイドライン」を入れる
- 設計書などの成果物はdocs/に分離する
- 判断基準は「繰り返し参照するか」「比較的安定した内容か」
迷った時は、「この知識は何度も使うかな？」と自問してみてください。正解は一つではないので、まずは運用しながら調整してみてください。
Xをフォローいただけると嬉しいです！
AI駆動開発（特に Claude Code）のノウハウや Tips をよく発信しています！
Discussion