Claude CodeにおけるカスタムコマンドとSkillの設計：開発ワークフローの自動化

Claude Codeを日常の開発ワークフローに導入する際、複雑なプロンプトを繰り返し入力することは、作業効率の低下や入力ミスの原因となります。チームの標準ルールに準拠したコードレビューや、特定のセキュリティ脆弱性のチェックを毎回手動で指示する運用は非効率的です。これらの定型プロンプトをバージョン管理可能なアセットとしてコード化し、スラッシュコマンド（/command）や自律的に実行可能な「Skill」として登録することで、開発プロセスの自動化が可能になります。本稿では、これらの実装方法と設計手法について解説します。

1. カスタムスラッシュコマンドの基礎

最もシンプルな自動化手法は、Markdownファイルを用いてカスタムスラッシュコマンドを定義することです。ファイル名がそのままコマンド名（例: review-pr.md の場合は /review-pr）として登録されます。カスタムコマンドは、プロジェクト個別、またはユーザー環境全体のグローバルスコープのいずれかに配置できます。

• プロジェクト個別スコープ: プロジェクトルート直下の .claude/commands/ に保存します。
• グローバルスコープ: ユーザーのホームディレクトリ配下の ~/.claude/commands/ に保存します。

以下は、Pull Requestの差分を取得してレビューを実行するカスタムコマンドの実装例です。

---
description: PRの差分をレビューし、改善案を提示します
---
!git diff main...HEAD
上記の差分を確認し、以下の観点でレビューを行ってください：
1. パフォーマンス上の懸念点
2. セキュリティ脆弱性
3. コーディング規約の遵守

このファイルを保存した後、Claude Codeのインタラクティブセッションで / を入力すると、補完候補に /review-pr が表示されます。以下のように引数を渡して実行することも可能です。

/review-pr

これにより、手動で差分を取得してプロンプトを貼り付ける手間が排除されます。

2. 高度なコマンド機能：引数、名前空間、フロントマター

より柔軟な自動化を実現するため、カスタムコマンドでは動的引数、名前空間による整理、およびYAMLフロントマターによるメタデータ設定がサポートされています。

動的引数（$ARGUMENTS）: $ARGUMENTS プレースホルダーは、スラッシュコマンドの後ろに入力された任意のテキストをキャプチャします。/fix-issue 1234 と実行した場合、内部で "Find and fix issue #1234" として処理されるよう定義できます。

名前空間（サブディレクトリ）: コマンドの数が増えた場合、サブディレクトリを作成して整理できます。例えば、.claude/commands/frontend/component.md に配置したファイルは、以下のように呼び出せます。

/frontend/component "Button"

YAMLフロントマターによる制御: Markdownファイルの先頭にYAMLフロントマターを付与することで、実行環境、使用モデル、ツールへのアクセス権限を制御できます。

---
description: コミットメッセージを自動生成します
argument-hint: 追加のコンテキスト（任意）
allowed-tools:
  - shell
model: claude-3-5-haiku-latest
---
<git_diff>
!git diff --cached
</git_diff>

上記の差分に基づき、Conventional Commits形式でコミットメッセージを生成してください。
$ARGUMENTS

主要パラメータの仕様は以下の通りです。description はコマンドの用途を示し、allowed-tools は実行を許可するツールを制限します。model 指定において、コミットメッセージ生成のような軽量タスクには haiku を指定することで、応答速度の向上とトークン消費の抑制が可能です。感嘆符（!）で始まるバックティック構文は、ローカルシェルでコマンドを実行し、その出力をプロンプトに直接注入します。

3. Skillへの拡張

Claude Codeのアップデートにより、カスタムコマンドと「Skill」は統合された実行フレームワークとして整理されました。.claude/commands/review.md と .claude/skills/review/SKILL.md は、どちらも /review コマンドとして登録されますが、新規実装ではSkill形式が推奨されます。同一名称が存在する場合、Skillが優先されます。

Skillはフォルダ単位のアセットとして管理され、.claude/skills/<name>/SKILL.md の構造を持ちます。自律的な呼び出し（Autonomous Triggering）が可能であり、ユーザーが明示的にコマンドを実行しなくても、Claudeがコンテキストから判断して自動的にSkillを起動できます。また、フォルダ構造であるため、関連するドキュメントやテンプレートを同梱できる利点があります。

---
description: プロジェクトのセキュリティ脆弱性をスキャンし、修正案を提示します
disable-model-invocation: true
---
プロジェクト全体のソースコードを静的解析し、OWASP Top 10に該当する脆弱性がないか確認してください。

💡 重要なパラメータ: description は自律起動のトリガーとなるセマンティックな説明文です。Claudeはこの記述を解析し、適用シーンを判断します。disable-model-invocation: true は、インフラ変更やデータベース操作など、副作用を伴う処理において自律実行を防ぎ、手動実行のみに制限するために使用します。

4. アーキテクチャ比較：CLAUDE.md と コマンド/Skill の使い分け

プロジェクトの設定を整理された状態に保つためには、CLAUDE.md とカスタムコマンド/Skillの役割の違いを理解し、適切に使い分ける必要があります。

5. 実践例：レビューから修正へのパイプライン構築

特定の技術スタックに特化したコードレビューを自動化することは、品質維持に有効です。以下は、Flutterプロジェクト向けのカスタムコードレビューSkillの実装例です。

---
description: Flutterのベストプラクティスに基づきコードをレビューします
model: claude-3-5-sonnet-latest
---
以下のFlutter/Dartの観点でコードを精査してください：
- Widgetの肥大化（抽出の必要性）
- Riverpod等の状態管理の適切な利用
- const修飾子の不足
- 非同期処理の例外ハンドリング

実行フローとして、まず /flutter-review lib/src/features/ を実行して指摘事項を取得し、続けて /fix コマンド等で修正を適用するパイプラインが構築できます。これにより、一貫した品質管理が自動化されます。

6. コマンドおよびSkill設計における留意事項

• 説明文の最適化: 自動起動を許可するSkillでは、description の冒頭にトリガーとなる明確なキーワードを配置し、モデルの誤判定を抑制します。
• 安全対策の徹底: ⚠️ システムに影響を与える破壊的な処理を含む場合は、必ず disable-model-invocation: true を設定し、手動実行を強制してください。
• 軽量モデルの活用: 🛠️ 複雑な推論を必要としないタスクには model: haiku を指定し、実行速度の向上とコスト削減を図ります。
• バージョン管理: .claude/ ディレクトリをGitリポジトリに含めることで、チーム全体で自動化ワークフローを共有します。
• トークン消費の抑制: 構造化されたコマンドファイルに指示を集約することで、セッション中のコンテキストウィンドウの逼迫を防ぎます。

Key Takeaways

• コマンドによる効率化: 頻出プロンプトを .claude/commands/ に保存し、引数付きで即座に実行可能です。
• 動的コンテキスト: ! 構文によるシェル実行結果の注入や $ARGUMENTS による動的処理が活用できます。
• 自律的なSkill: .claude/skills/ を用いて、コンテキストに応じた自動起動が可能なSkillを定義できます。
• 役割の分離: 永続的なルールは CLAUDE.md に、実行手順はコマンドやSkillに定義することで、クリーンな構成を維持します。