run-skill-generatorで起動手順をスキルとして記録する

run-skill-generatorは、Claude Codeの/runと/verifyがアプリを起動する手順を教えるコマンドです。クリーンな環境からの起動を、推測ではなく記録済みのレシピとして実行できるようにします。データベース接続や環境変数ファイル、複数段階のビルドが必要なプロジェクトほど、このコマンドの価値が上がります。名前のとおり「スキルを生成するコマンド」であり、生成物は普段書くSKILL.mdと同じ形式でリポジトリにコミットできます。本稿では、何を記録し、どこに保存され、/verify自身が持つ別の自己記録機能とどう違うのかを扱います。/verifyそのものの検証範囲はClaude Code verifyコマンドとは何かで解説しています。

run-skill-generatorは何を解決するコマンドか

run-skill-generatorは、/runと/verifyにプロジェクトのビルド・起動方法を教えるコマンドです。公式ドキュメントは「クリーンな環境からプロジェクトのアプリをビルド・起動・操作する方法を、プロジェクト固有のスキルとして書くことで/runと/verifyに教える」と定義しています。バンドルスキルの1つで、/run・/verifyと同じくClaude Codeのv2.1.145以降が必要です。バージョンはclaude --versionまたは/statusコマンドで確認できます。

/runと/verifyはセットアップなしで動作します。READMEやpackage.json、Makefileからプロジェクトの種類(CLI・サーバー・TUI・ブラウザー駆動)と起動方法を推測するためです。この推測は、標準的な起動を超える条件が絡むと不安定になります。データベース接続が必要な場合、環境変数ファイルの読み込みが必要な場合、GUIセッションを必要とする場合、複数段階のビルドが必要な場合です。run-skill-generatorはこの推測に頼る代わりに、実際にクリーンな環境からアプリを起動してみて、うまくいった手順をそのまま記録します。

起動の推測が不安定になる典型パターン

4つの条件は、それぞれ推測が外れる理由が異なります。

• データベース接続: READMEには「起動コマンド」しか書かれておらず、接続先やマイグレーションの実行順は省略されがちです。クリーンな環境では、この省略された前提が推測の失敗として表面化します
• 環境変数ファイル: .env.exampleのようなテンプレートはあっても、実際に動かすための値は各自のローカル環境に依存します。テンプレートをコピーしただけでは起動しないプロジェクトが少なくありません
• GUIセッション: ブラウザーやデスクトップアプリのように画面を持つプロセスは、起動できたかどうかをログだけで判定しづらく、推測ベースの確認と相性が悪くなります
• 複数段階のビルド: READMEが最終的な起動コマンドだけを載せ、その前提になるビルド手順を省略しているケースがあります。中間のビルド工程が抜けると、起動コマンド自体は合っていても失敗します

run-skill-generatorは、これらの条件を毎回推測し直すのではなく、一度だけ実際に動かして「何が効いたか」を記録することで解決します。

記録の中身と保存先

run-skill-generatorが記録するのは、インストールコマンド・環境変数・起動スクリプトの3種類です。アプリをクリーンな環境から起動させ、その過程でうまくいった手順を捕捉し、プロジェクト専用のスキルとして.claude/skills/run-<name>/にコミットします。生成されるファイルはSKILL.mdを自分で書く場合と同じ形式です。個人スキル(~/.claude/skills/)ではなくプロジェクトスキルとして記録されるため、リポジトリを共有すればチーム全員が同じ起動手順を使えます。

/run-skill-generator

引数は不要です。実行すると、プロジェクトの起動を実際に試しながらレシピを組み立てます。記録が終わると、/run・/verifyだけでなく、リポジトリ内の他のエージェントも、この記録済みレシピに従うようになります。毎回READMEやビルド設定から起動方法を再発見するのではなく、記録済みの手順をそのまま再利用する形です。

記録の作られ方は、READMEを読んで手順を書き写すのとは異なります。実際にクリーンな環境でインストール・ビルド・起動を試し、うまくいったコマンドと値だけを残す仕組みです。README止まりの手順書と違い、実際に動いたことを確認した上で記録されるため、書き手の思い込みや古い記述がそのまま残るリスクが小さくなります。READMEの更新が追いついていないプロジェクトほど、この違いが効いてきます。

いつ実行し、いつ再実行するか

公式ドキュメントは、プロジェクトごとに1回実行し、ビルドや起動のプロセスが変わったときにもう一度実行するとしています。起動方法そのものが変わらない限り、記録済みのレシピは有効なままです。ここが/verifyの自己記録との大きな違いでもあります。/verifyの自己記録は実行を誤った方向に進めたときに自動で更新されますが、run-skill-generatorによる記録は自動更新されません。ビルドや起動の手順を変えたことに気づき、再実行するかどうかは開発者側の判断に委ねられています。実行の目安は次の早見表のとおりです。

/verifyが持つ別の自己記録機能との違い

run-skill-generatorとは別に、/verify自身にも、記録済みレシピが無い状態でビルド・起動したときに自己記録する機能があります。この2つは記録先も更新の仕組みも異なるので、混同すると設定を見失います。

どちらも最終的には.claude/skills/配下にレシピを残しますが、性格は異なります。run-skill-generatorは狙って1回実行するコマンドで、/verifyの自己記録は検証を実行した結果として副次的に生まれます。両方が動いているプロジェクトでは、run-skill-generatorの記録が/runと/verifyの起動部分を、/verifyの自己記録がその後の検証観察の部分を担う形になります。

手書きのSKILL.mdと比べるとどちらを選ぶか

run-skill-generatorが生成するのは、SKILL.mdを自分で書く場合と同じ形式のスキルファイルです。両者の違いは形式ではなく、手順の正しさをどう担保するかにあります。手書きのSKILL.mdは、書き手が把握している範囲でしか正確になりません。READMEに書かれていない暗黙の前提(先に起動しておくべきサービス、順番に実行する必要があるマイグレーション等)があると、手書きの手順はそこで欠落しがちです。run-skill-generatorは実際にクリーンな環境から動かした結果だけを記録するため、書き手が気づいていなかった前提も、動作した限りにおいては手順に反映されます。手書きとの使い分けの目安は次のとおりです。

よくあるつまずき

• 推測が不安定なままrun-skill-generatorを試していない: /run・/verifyが起動に失敗する状態が続くなら、まずrun-skill-generatorを1回実行してレシピを固定します
• ビルド・起動プロセスを変えたのに再実行していない: 記録済みレシピは自動更新されません。手順を変えたらrun-skill-generatorをもう一度実行します
• /verifyの自己記録と混同する: run-skill-generatorによる記録と/verify自身の自己記録は別物です。前者は明示的な1回の実行、後者は検証の副産物として自動で書き込まれます。保存先のパスもrun-<name>/とverify/SKILL.mdで異なるので、記録が見当たらないときはどちらの機能の話をしているかを先に確認します
• バンドルスキルを無効化した環境で呼び出そうとする: disableBundledSkillsを有効にすると、バンドルスキルとワークフローが丸ごと取り除かれ、run-skill-generatorも呼び出せなくなります。環境変数CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1でも同じ効果です。run-skill-generatorだけを個別に隠したい場合はskillOverridesに"run-skill-generator": "off"のように設定します(値は"on"・"name-only"・"user-invocable-only"・"off"の4種類)。設定の詳細はsettings.jsonの設定項目で確認できます

よくある質問

run-skill-generatorは毎回実行する必要がありますか

いいえ。公式ドキュメントは「プロジェクトごとに1回、ビルドや起動プロセスが変わったときにもう一度」実行するとしています。記録済みのレシピが有効な間は、再実行の必要はありません。

生成されたレシピはコミットしてよいですか

はい。記録はプロジェクト専用のスキルとして.claude/skills/run-<name>/に保存される形式なので、リポジトリにコミットしてチームで共有する運用が前提です。

run-skill-generatorと/verifyの自己記録はどちらを先に使うべきですか

順序を決める規則は公式ドキュメントに明記されていません。ただし起動そのものが不安定なプロジェクトでは、先にrun-skill-generatorで起動手順を固定してから/verifyを使うほうが、/verifyの自己記録が余計な試行錯誤を拾わずに済みます。

生成されたrun-<name>スキルは手動で編集してよいですか

編集して問題ありません。生成されるファイルは、自分で書くSKILL.mdと同じ形式のプロジェクトスキルです。起動コマンドが変わった、環境変数が増えたといった小さな修正なら、run-skill-generatorを再実行せずに直接編集しても構いません。大きく手順が変わった場合は、再実行して一から記録し直すほうが確実です。

まとめ

run-skill-generatorは、/runと/verifyがクリーンな環境からアプリを起動する手順を、推測ではなく記録済みのレシピとして実行できるようにするコマンドです。インストールコマンド・環境変数・起動スクリプトを.claude/skills/run-<name>/に記録し、以降は/run・/verify・他のエージェントがこのレシピに従います。v2.1.145以降が必要で、実行はプロジェクトごとに1回、ビルドや起動プロセスを変えたときに再実行します。/verify自身が持つ別の自己記録機能(v2.1.200以降)とは記録先も更新の仕組みも異なるため、両者を混同しないことが実務上のポイントです。

標準的な起動で済むプロジェクトでは無理に使う必要はありません。データベース接続や複数段階のビルドが絡むプロジェクトでは、/run・/verifyを使い始める前に一度run-skill-generatorを実行しておくと、以降の起動の推測が安定します。記録済みのレシピはリポジトリに残る資産なので、一度整えておけば、その価値は長く続きます。