Claude Code /code-reviewを置き換える手順 — 自作スキルとの線引き

.claude/skills/code-review/SKILL.mdを置くと、Claude Codeの/code-reviewはそのスキルに差し替わります。ただし/reviewエイリアスは差し替わらず、組み込みのレビューを走らせ続けます。ここを知らないまま置き換えると、チームの中で/code-reviewと/reviewが別のレビューを実行する状態になります。

この記事では、自チームのレビュー規約で/code-reviewを置き換える手順と、置き換えずに済ませる選択肢との線引きを扱います。

同名のスキルを置くと何が差し替わるのか

/code-reviewは組み込みの「同梱スキル」です。指示文はClaude Codeに内蔵されていて、ディスク上に開いて編集できるSKILL.mdはありません。そのため、同梱版を書き換える方法はありません。用意されているのは、同じ名前のスキルを置いて差し替える方法です。

同名のスキルが複数あるときにどれが走るかは、場所で決まります。

3行目の意味は、プラグインで配られているcode-review系のスキルを入れても、/code-review自体は差し替わらないということです。プラグイン側は名前空間が付くため、/code-reviewは引き続き同梱版を指します。プラグイン版の使い方はcode-reviewプラグインの解説にあります。

もう1点、.claude/commands/のファイルと同名のスキルがぶつかった場合はスキルが優先されます。古い形式のコマンドが残っているリポジトリでも、スキルを置けば差し替えは成立します。

自チーム版のcode-reviewスキルを置く手順

手順は3つです。置く場所の判断、SKILL.mdの記述、動作の確認の順に進みます。

次のSKILL.mdは、書き方を示すための例です(公式のスキル仕様に沿ったfrontmatterで、観点の中身は仮のチーム規約です)。

---
name: code-review
description: 自チームの規約で差分をレビューする。PR前の確認に使う
argument-hint: "[PR番号 | ブランチ | パス]"
context: fork
agent: general-purpose
background: false
---
 
次の対象をレビューする。引数が空なら、上流ブランチより先の
コミットと未コミットの変更を対象にする。
 
対象: $ARGUMENTS
 
観点(チーム規約):
1. DBマイグレーションに戻し手順(down)がある
2. 公開APIを変えたらCHANGELOGを更新している
3. 認可チェックを通らない経路が増えていない
 
出力は重大度順に、ファイルと行番号つきで返す。
コードは編集しない。

context: forkを付けると、スキルは別のサブエージェントの中で動き、会話の履歴は渡されません。そのため、指示文は単体で意味が通るように書きます。agentを省くとgeneral-purposeが使われます。background: falseは、結果を待ってから次のターンに進めたいときの指定で、v2.1.218以降で使えます。省くと、同梱の/code-reviewと同じようにバックグラウンドで走ります。

$ARGUMENTSには、/code-reviewの後ろに打った文字列がそのまま入ります。/code-review src/authなら、src/authが対象になります。

置き換えると何が変わるのか

差し替えた時点から、/code-reviewで起きることはすべて自分のSKILL.mdの内容で決まります。同梱版が持っていた次の挙動は、自動では引き継がれないものとして扱うのが安全です。

• --fixや--commentといったフラグの解釈
• 前回入力したeffortレベルの再利用
• 対象が何も指定されないときの既定範囲

同梱版のフラグとeffortの仕様は、/code-reviewのeffort指定で扱っています。自作スキルがこれらを理解するかどうかについて、公式ページには引き継ぎの記載がありません。必要なフラグはSKILL.mdの本文に自分で書きます。

同梱版が見るもの(正しさのバグが中心で、モデルとeffortによっては再利用・単純化・効率の指摘も含む)も、自作スキルが見るものとは別になります。役割が近い/simplifyとの関係は/simplifyコマンドの記事にあります。

--fix相当の自動修正を自作スキルに持たせるなら、編集の扱いに注意が必要です。バックグラウンドで走るcontext: forkのスキルは、編集をセッションのチェックポイントの外側で適用します。/rewindでは、すでに会話の中で編集したファイル以外は戻りません。取り消しはgitで行います。background: falseで待つ場合のチェックポイントの扱いは、公式ページに記載がありません。編集を伴うスキルでは、実行前にgitで戻せる状態にしておくのが確実です。

/reviewは、v2.1.223より前は単独のコマンドでした(GitHubのPRを1回のパスで読むだけの、読み取り専用のレビュー)。今のエイリアスの位置づけはv2.1.223のリリースノートでも触れています。古い手順書に書かれた/reviewの挙動と、今の挙動は別物です。

置き換えるか、CLAUDE.mdに足すか、reviewerを書くか

置き換えは、3つある選択肢の1つに過ぎません。同梱の/code-reviewは、自分のCLAUDE.mdに従います。したがって、規約を足したいだけなら、スキルを置く必要はありません。

線引きの目安は、「何を見るか」だけならCLAUDE.md、「どう進めて何を返すか」まで握りたいなら置き換えです。たとえば「マイグレーションには戻し手順を書く」は規則なのでCLAUDE.md向きです。「差分の取得から重大度順の出力まで毎回同じ手順で回す」は手順なので、スキル向きです。CLAUDE.mdを肥やしすぎる場合は、CLAUDE.mdをSkillsに移す方法の考え方が参考になります。

reviewerサブエージェントは、.claude/agents/code-reviewer.mdのように置きます。公式の例ではtoolsをRead, Grep, Glob, Bashに絞り、編集系のツールを持たせない読み取り専用のレビュー役にしています。

---
name: code-reviewer
description: 変更後のコードを品質と保守性の面でレビューする
tools: Read, Grep, Glob, Bash
model: inherit
---
 
git diffで直近の変更を確認し、重大度別に指摘を返す。

サブエージェントは、スキルをskillsフィールドで事前に読み込めます。つまり、「規約はスキルに書き、読み取り専用の担当者はサブエージェントにする」という組み合わせも成り立ちます。スキルとサブエージェントとhooksの役割分担は4つの仕組みの使い分けにまとめています。

サブエージェント側で注意したい点が1つあります。ExploreとPlanはCLAUDE.mdを読まずに始まります。context: forkのスキルでagent: Exploreを選ぶと、チームのCLAUDE.mdの規則はサブエージェントに届きません。規約をCLAUDE.mdに置いている場合は、agentを省くか、必要な規則をSKILL.mdの本文に書き込みます。

置き換える前に確かめておきたいこと

自作のcode-reviewを置いたあとに、次の3点を確かめます。

1. /skillsの一覧で、自分のスキルが出ているか。個人側に同名があれば、そちらが優先される
2. /code-reviewと/reviewを別々に打って、出力が別物になっているか。同じなら、置き換えは成立していない
3. 自動で起動してほしくない場合はdisable-model-invocation: trueを付けているか

3点目は、同梱版の自律起動との違いに関わります。同梱の/code-reviewは、「変更をレビューして」といった自然文から自律的に起動できます。自作のスキルは、descriptionが自然文に合えば同じように起動し得ます。起動を手動に絞りたいなら、disable-model-invocation: trueを付けます。このフィールドは、セッション内のスケジュールタスクがスキルをプロンプトにして発火するときの動作にも影響します。同梱版の起動を止めるskillOverridesの設定と、スキル自身のfrontmatterは別の仕組みです。

SKILL.mdの編集は、セッションの途中でも検出されます。ただし、.claude/skills/というディレクトリ自体をセッション開始後に初めて作った場合は監視の対象外なので、/reload-skillsを実行します。

チームに配る経路とモノレポでの見え方

リポジトリにコミットした.claude/skills/code-review/は、そのリポジトリで作業する全員に読み込まれます。開発者はgit pullするだけで差し替わり、各自の設定は要りません。

組織全体で揃えたい場合は、管理設定のディレクトリ(エンタープライズ)に置く経路があります。同名のスキルが複数あるときの優先順位は、エンタープライズ、個人、プロジェクトの順です。管理側で置いたものを、個人やプロジェクトのスキルが上書きすることはありません。逆に、個人のスキルがプロジェクトのスキルを上書きするため、チームの規約を守らせたい場合は、手元に古いcode-reviewが残っていないかを確認しておくのが無難です。

モノレポでは、起動したディレクトリから、リポジトリのルートまでの親ディレクトリにある.claude/skills/が読み込まれます。packages/frontend/で起動しても、ルートに置いたcode-reviewは有効です。サブディレクトリ側にもcode-reviewを置いた場合は両方が残ります。/code-reviewはルートのものを走らせ、サブディレクトリ側は/apps/web:code-reviewのようにディレクトリ名つきの形で呼び出せます。パッケージごとに観点を変えたいときの構成です。

プラグインとして配る場合は、名前空間が付いて/プラグイン名:code-reviewになります。/code-reviewそのものは差し替わらないので、「全員の/code-reviewを置き換える」目的には向きません。

元に戻すときと、同梱版を使い続けたいとき

置き換えをやめるときは、個人またはプロジェクトのスキルであれば、そのディレクトリを削除します。現在のセッションの/skillsからも外れます。削除すれば、/code-reviewは同梱版に戻ります。

一時的に同梱版を使いたいだけなら、削除せずに/reviewを使う手もあります。/reviewのエイリアスは置き換え後も組み込みのレビューを指すためです。自作スキルと同梱版を両方残して、用途で打ち分けられます。

反対に、同梱版を見えなくしたい場合は、skillOverridesで"off"にする方法や、disableBundledSkillsで同梱スキル全体を無効にする方法があります。ただし、ユーザー設定とプロジェクト設定のskillOverridesは名前だけを照合します。同名の自作スキルがあるときにcode-reviewのキーがどちらを指すかは、公式ページに記載がありません。

まとめ

/code-reviewを自チームの手順に変えたいなら、同名のスキルを置けば差し替わります。変わるのは/code-reviewだけで、/reviewは組み込みのまま残ります。規約を足すだけならCLAUDE.md、権限を絞った担当者がほしいならreviewerサブエージェントのほうが小さな変更で済みます。4つの経路の使い分けはコードレビューの実行経路の記事に任せ、置き換えるのは、出力形式と手順まで自チームで握りたいときに絞るのが現実的です。