カスタムコマンド深掘り — Skills との違いとベストプラクティス
読了 5分 ＋ 実践 30分
カスタムコマンドを使いこなすと、繰り返し発生する作業フロー（ブログ記事の作成・PR レビュー・i18n 同期など）をスラッシュ一つで実行できるようになります。このページでは、コマンドファイルの構造・設計ルール・実際の作成手順を体系的に学びます。
Commands と Skills の違い
Section titled “Commands と Skills の違い”コマンドとスキルは混同されやすいですが、役割がまったく異なります。
| 観点 | Commands（/command） | Skills（SKILL.md） |
|---|---|---|
| トリガー | ユーザーが /command と入力する | Claude が状況に応じて自動判断する |
| 呼び出し | 明示的・意図的 | 暗黙的・自動 |
| 用途 | 決まった作業フローを実行する | コンテキストに応じた動作を定義する |
| ファイル場所 | shared/commands/*.md | shared/skills/*/SKILL.md |
| テンプレート変数 | $ARGUMENTS が使える | なし |
コマンドは「何をするか」をユーザーが決める。スキルは「どう振る舞うか」を Claude が自動で判断します。ブログ記事を書く作業フロー全体は /blog コマンドで実行し、記事内の文体ルールや品質基準は blog-content/SKILL.md が定義するという使い分けになります。
コマンドファイルの構造
Section titled “コマンドファイルの構造”コマンドファイルは Markdown 形式で記述し、shared/commands/ に配置します。.claude/commands/ はこのディレクトリへのシムリンクです。
基本構造：
# コマンド名
コマンドの説明文。`$ARGUMENTS` でユーザーの入力を受け取れる。
## 手順
1. 最初に実行すること
2. 次に実行すること
3. 最後に確認すること$ARGUMENTS はユーザーが /command 引数 と入力したときの引数部分に展開されます。/blog React の useEffect とは と実行すると、コマンド内の $ARGUMENTS が React の useEffect とは に置き換わります。
実際の例: blog.md の構造
Section titled “実際の例: blog.md の構造”このプロジェクトの shared/commands/blog.md は次の構造を持ちます。
ブログ記事を作成・更新してください。
## 新規記事の場合
1. `src/content/blog/ja/` に日本語記事を作成する（先に書く）
2. frontmatter テンプレートを使用する
3. 対応する英語記事を作成する
4. `node scripts/ensure-slugs.js` を実行する
5. 校閲・ファクトチェックを実施する
6. `npm run dev` でローカルプレビューを確認する$ARGUMENTS を使わないコマンドも有効です。引数なしで決まった作業フロー全体を実行する場合に適しています。
ベストプラクティス
Section titled “ベストプラクティス”コマンド名は動詞で始める
Section titled “コマンド名は動詞で始める”コマンド名は何をするかが一目で分かるよう、動詞始まりにします。
| 良い例 | 避けるべき例 |
|---|---|
/blog | /article |
/sync-i18n | /i18n |
/pr | /pullrequest |
このプロジェクトの shared/commands/ には blog.md、docs.md、pr.md、sync-i18n.md、build.md が揃っています。いずれも「動作」を名前に持ちます。
$ARGUMENTS を活用して柔軟な入力を受け取る
Section titled “$ARGUMENTS を活用して柔軟な入力を受け取る”ユーザーがコマンドに追加情報を渡せるようにすることで、コマンドの再利用性が高まります。
# PR サマリー
指定した PR の変更内容を要約し、レビューポイントを整理してください。
PR 番号または URL: $ARGUMENTS
## 手順
1. `gh pr view $ARGUMENTS --json title,body,files` で詳細を取得する
2. 変更ファイルの diff を確認する
3. 変更の目的・影響範囲・注意点をまとめて報告する冪等性を意識する
Section titled “冪等性を意識する”同じコマンドを2回実行しても、システムが壊れない設計にします。ファイルを新規作成するコマンドでは「同名ファイルが既に存在する場合は上書きせず確認する」という手順を入れるとよいです。
## 手順
1. 対象ファイルが既に存在するか確認する
2. 存在する場合はユーザーに上書き確認を求める
3. 存在しない場合は新規作成する承認が必要な操作は確認ステップを入れる
Section titled “承認が必要な操作は確認ステップを入れる”build.md の設計パターンを参考にします。本番デプロイや不可逆な操作を含むコマンドは、実行前にユーザー確認を求める手順を明示します。
> ⚠️ **このコマンドは本番デプロイを引き起こします。**
> 実行前に必ずユーザーへ承認を求めてください。
## 実行前の確認事項
ユーザーに以下を確認してから進めてください。
1. ローカルプレビューは確認済みか？
2. main へのマージが完了しているか？
3. 本番公開して問題ない状態か？shared/commands/ に置いてシムリンクで共有する
Section titled “shared/commands/ に置いてシムリンクで共有する”コマンドファイルは .claude/commands/ に直接書かず、必ず shared/commands/ に配置します。.claude/commands/ は shared/commands/ へのシムリンクとして設定することで、チームのすべてのメンバーが同じコマンドを使えます。
# シムリンクの確認
ls -la .claude/commands
# → .claude/commands -> ../shared/commandsStep 1: 既存コマンドの構造を確認する
Section titled “Step 1: 既存コマンドの構造を確認する”cat shared/commands/blog.md✅ 確認: ファイルの内容が表示され、手順番号・
npm runコマンド・ファクトチェックの記載があれば読み込み成功です。
Step 2: /blog コマンドを実際に使う
Section titled “Step 2: /blog コマンドを実際に使う”Claude Code を起動し、コマンドを実行します。
> /blog Claude Code のハーネス入門Claude が shared/commands/blog.md の手順に沿って記事作成を開始します。
✅ 確認: Claude が「
src/content/blog/ja/に日本語記事を作成します」という内容で応答し始めれば、コマンドが正しく読み込まれています。
Step 3: 新しいコマンド summarize-pr.md を作成する
Section titled “Step 3: 新しいコマンド summarize-pr.md を作成する”shared/commands/summarize-pr.md を新規作成します。
# PR サマリー
指定した PR 番号の変更内容を要約し、レビューポイントを整理してください。
PR 番号または URL: $ARGUMENTS
## 手順
1. `gh pr view $ARGUMENTS --json title,body,files` で PR の詳細を取得する
2. 変更されたファイルの diff を確認する
3. 変更の目的・影響範囲・レビューで注意すべき点を整理して報告する✅ 確認:
ls shared/commands/を実行してsummarize-pr.mdが表示されれば作成成功です。
Step 4: コマンドが動作することを確認する
Section titled “Step 4: コマンドが動作することを確認する”Claude Code で新しいコマンドを実行します。
> /summarize-pr 123Claude が PR #123 の内容を取得して要約を始めます。
✅ 確認: Claude が
gh pr view 123 --json ...を実行しようとする挙動が見られれば、$ARGUMENTSの展開が正しく機能しています。
- Commands はユーザーが明示的に呼び出す作業フローの定義。Skills は Claude が自動的にロードする動作定義
- コマンドファイルは
shared/commands/に Markdown 形式で配置し、.claude/commands/はシムリンクにする $ARGUMENTSを使うとユーザーからの追加入力をコマンド内で展開できる- 冪等性・承認フローの設計が、チームで安全に使えるコマンドの鍵
次のステップ
Section titled “次のステップ”- Skills 設計パターン — Commands と対をなす、Claude の自動動作を定義するスキルの書き方を学ぶ
- Agents スペック設計 — サブエージェントを使った複雑なワークフローの設計へ進む
よくある質問
Section titled “よくある質問”Q: コマンドファイルは .claude/commands/ と shared/commands/ のどちらに書くべきですか？
A: shared/commands/ に書きます。.claude/commands/ は shared/commands/ へのシムリンクです。シムリンク先ではなく実体に書くことで、Git 管理・チーム共有・harness:check による検証が正しく機能します。
Q: $ARGUMENTS を使わないコマンドに意味はありますか？
A: あります。引数なしのコマンドは「特定の手順を毎回同じ方法で実行する」ときに便利です。/sync-i18n のように引数が不要な定型作業に向いています。
Q: コマンドが認識されない場合の確認方法は？
A: まず ls -la .claude/commands でシムリンクが正しく ../shared/commands を向いているか確認します。次に shared/commands/ にファイルが存在するか確認します。それでも認識されない場合は Claude Code を再起動してください。
Q: Commands と Skills を同じファイルに混在させることはできますか？
A: 技術的には可能ですが、推奨しません。Commands は「ユーザーが実行するフロー」、Skills は「Claude の振る舞いの定義」として責務を分離することで、保守性と可読性が高まります。