はじめに
Claude Code でカスタムコマンドを作って運用していたところ、.claude/commands/ がレガシー形式になり、.claude/skills/ への移行が推奨されていることを知りました。この記事では Commands と Skills の違い、そして推奨される3層アーキテクチャをまとめます。
この記事の対象読者・前提条件
対象読者
- Claude Code で
.claude/commands/にカスタムコマンドを作っている方 - Skills と Commands の違いがよくわからない方
前提条件
- Claude Code をインストール済み
- スラッシュコマンドの基本的な使い方を知っている
課題：Commands と Skills の違いがわからない
Claude Code には「Commands」と「Skills」という2つの仕組みがありますが、現在はこれらが統合され、Skills が推奨形式になっています。
一言でいうと：
- Commands = 「やること」を指示する手順書
- Skills = 「知っていること」を教える知識集
Spring Boot に例えると：
- Command = Controller（「POST /users が来たら、バリデーションして、Service呼んで、201返す」）
- Skills = application.yml + 共通設定クラス（「DBの接続先はこれ、命名規約はこれ」）
アプローチ：3層アーキテクチャ
2層構成（従来）
Command（コマンド）→ Claude本体が直接実行
例: /generate-component Button
→ CLAUDE.md + rules を参照しながら実装
3層構成（推奨）
Command（入口）→ Agent（実行者）→ Skills（知識）
例: /generate-component Button
→ component-developer エージェントを起動
→ component-conventions スキルをプリロード
→ エージェントがスキルの知識を使って実装
Spring Boot のアーキテクチャに例えると：
- Command = Controller（リクエストの受け口）
- Agent = Service（ビジネスロジックの実行）
- Skills = Repository / 設定ファイル（知識・データへのアクセス）
なぜ Commands がレガシーになったのか
| Commands | Skills | |
|---|---|---|
| ファイル構成 | 1ファイルに全部 | フォルダで補助ファイルを持てる |
| Claudeの自動利用 | ×（スラッシュコマンドのみ） | ○（自動判断も可） |
| frontmatter | 限定的 | 豊富な制御オプション |
| トークン効率 | 毎回全部読み込み | 必要なときだけ読む |
まとめ
-
.claude/commands/はレガシー。.claude/skills/への移行が推奨 - Commands は「手順書」、Skills は「知識集」という役割の違い
- 3層構成（Command→Agent→Skills）で関心を分離するのがベストプラクティス