🔥

.claude/commands/ はもう古い？Commands を Skills へ移行した記録と references/ 設計パターン

に公開
AI
commands
Claude Code
Skills
tech

毎回同じ指示、まだコピペしてますか？

「コミットメッセージは日本語で」「実装前に必ず計画を立てて」「このフォーマットで書いて」

こういった繰り返しの指示を .claude/commands/ に書いて運用していたエンジニアの方、多いのではないでしょうか。自分もそのひとりでした。

しかし最近、カスタムコマンド（Commands）が Skills に統合されました。 既存の Commands は引き続き動作しますが、Skills に移行することで得られる恩恵は大きく、特に references/ ディレクトリを使った設計パターンは「なぜ今まで知らなかったのか」と思えるほど便利です。

この記事では、実際に plan-made コマンドを Skills へ移行した記録をベースに、移行手順と設計のコツを解説します。

🎯 Skills とは何か？Commands との違い

Skills は .claude/skills/<skill-name>/SKILL.md に配置するファイルです。YAMLフロントマター付きの Markdown に「こうやってほしい」と書くだけで、Claude Code の振る舞いを制御できます。

Commands と Skills、何が違う？

カスタムコマンドは Skills にマージされました。

.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md は、どちらも同じ /deploy コマンドを作ります。既存の Commands ファイルは引き続き動作しますが、Skills の方が多くの機能を提供しています。

主な違いを整理するとこうなります。

機能 Commands Skills
/ コマンドとして呼び出し ✅ ✅
自動トリガー（description による） ❌ ✅
references/ サポート ❌ ✅
context: fork（サブエージェント実行） ❌ ✅
allowed-tools の事前許可 ❌ ✅
agents: フロントマター ✅ ❌
rules: フロントマター ✅ ❌

Commands が持っていた agents: と rules: は Commands 専用の機能であり、Skills には存在しません。これが移行時の最大のハードルです。後述する references/ でカバーします。

📁 .claude/ フォルダ、各ディレクトリの役割と移行方針

移行前に、各フォルダが何のためにあるのかを整理します。

.claude/commands/ — 旧来の Custom Commands

スラッシュコマンドを定義するフラットな Markdown ファイル置き場です。Skills に統合済みのため、新規作成は不要。既存ファイルは動作しますが、Skills の機能は使えません。

→ 削除可。Skills に移行推奨。

.claude/agents/ — Subagent 定義

独立したコンテキストでタスクを実行するサブエージェントの定義です。Commands の agents: [planner, architect] フロントマターで参照されていましたが、Skills では agents: が使えません。

→ 内容を Skills の references/ に移行して削除可。

.claude/rules/ — Commands 用のルール参照

Commands の rules: [common/agents.md] で読み込まれていたカスタムルール群です。Skills 移行後は rules: フロントマターが使えないため、references/ への統合が必要です。

→ references/ または SKILL.md 本文に統合して削除可。

.claude/skills/ — 最新の拡張方式

SKILL.md を中心に、templates / examples / references / scripts などのサポートファイルを同一ディレクトリで管理できる最新の方式です。

→ これがメイン。

🔑 SKILL.md の構造とフロントマター全フィールド

---
name: my-skill-name
description: 何をするか + いつ使うか（250文字以内。キーワードを前半に）
---
# スキル名

## 手順
1. ○○を確認する
2. ○○を実行する
3. ○○で検証する

フロントマターで指定できるフィールドは以下のとおりです。

フィールド 必須 説明
name No 表示名。省略するとディレクトリ名が使われる
description 推奨 最重要。自動トリガーの判断に使われる。250文字で切り詰められるのでキーワードを前半に
argument-hint No オートコンプリート時のヒント（例: [issue-number]）
disable-model-invocation No true で手動呼び出しのみに制限
user-invocable No false で / メニューから非表示
allowed-tools No 承認なしで使えるツールを事前許可（例: Read Grep Glob）
model No Skill 実行時のモデル上書き
effort No 思考レベル（low / medium / high / max）
context No fork でサブエージェントコンテキストで実行
paths No Glob パターンで自動発動条件を限定

🧹 実践：plan-made コマンドを Skills へ移行した記録

移行前の構造

.claude/
├── commands/
│   └── plan-made.md        ← agents: / rules: フロントマターで外部参照
├── agents/
│   ├── planner.md          ← 実装計画の専門エージェント
│   └── architect.md        ← システム設計の専門エージェント
└── rules/
    └── common/
        └── agents.md       ← エージェントオーケストレーションのガイド

plan-made.md のフロントマターはこうなっていました：

---
description: 要件の再確認、リスクの評価、および段階的な実装計画の作成
agents: [planner, architect]
rules: [common/agents.md]
---

agents: も rules: も Commands 専用の機能です。Skills にはこれらのフロントマターキーが存在しないため、内容ごと references/ に取り込む必要があります。

移行後の構造

.claude/skills/plan-made/
├── SKILL.md                         ← メイン（簡潔な手順 + 参照指示）
└── references/
    ├── planner-instructions.md      ← agents/planner.md の内容を移行
    └── architect-instructions.md   ← agents/architect.md の内容を移行

設計のポイント：SKILL.md は「薄く」保つ

移行後の SKILL.md はこうなりました：

SKILL.md
---
name: plan-made
description: コードでの新規実装の際に発動する。要件の再確認、リスクの評価、および段階的な実装計画の作成。新機能の開発、大規模なアーキテクチャ変更、複雑なリファクタリング、複数ファイルへの変更が必要な時に使用。
allowed-tools: Read Grep Glob
---
# Plan スキル

コードを書き始める前に **planner** のロールとして包括的な実装計画を作成します。
大規模なシステム設計・技術的意思決定が必要な場合は
`references/architect-instructions.md` を参照してください。
詳細な計画プロセスは `references/planner-instructions.md` を参照してください。

📝 description の書き方が成否を分ける

description は Claude Code が「いつこのスキルを使うべきか」を判断する唯一の情報です。曖昧だとトリガーされないか、関係ない場面でトリガーされます。

# ❌ 悪い例（曖昧すぎる）
description: 便利なスキル

# ✅ 良い例（具体的なトリガー条件を含む）
description: コードでの新規実装の際に発動する。要件の再確認、リスクの評価、段階的な実装計画の作成。新機能・アーキテクチャ変更・複雑なリファクタリング時に使用。

書き方のコツ

  • 「何をするか」と「いつ使うか」の両方を書く
  • キーワードを前半に置く（250文字で切り詰められるため）
  • 具体的なトリガー条件（「新機能開発時」「エラー発生時」など）を明示する

🚀 まとめ

  • Commands は Skills に統合済み。新規作成は Skills で行うのが推奨
  • agents: rules: フロントマターは Commands 専用。Skills 移行後は references/ に統合して削除可能
  • SKILL.md は薄く保ち、詳細は references/ に分離するとトークン節約になる
  • description は 250 文字以内でキーワードを前半に。「何をするか + いつ使うか」を具体的に書く
  • 最初は name と description だけで十分。使い込んでから context: fork などを追加する

Skills は一度作ると「あ、あのスキルがある」と思えるようになり、作業の立ち上がりが確実に速くなります。まずは今使っている Commands を 1 つ移行してみてください。

最後まで読んでいただきありがとうございました！質問やフィードバックがあれば、ぜひコメントで教えてください 🙏

Discussion