run

ローカルサイトやアプリを起動し、実際のブラウザで表示します。`package.json` や設定ファイル、プレーンな `index.html` からスタックを検出し、空きポートを選んで開発サーバーまたは静的サーバーを起動し、応答を待ってスクリーンショットを撮るかブラウザを開き、フラグひとつで停止します。ユーザーがプロジェクトをローカルで「実行」「サーブ」「起動」「プレビュー」「開始」「開く」、ブラウザでページを確認する、サイトのスクリーンショットを撮る、またはビルドを評価する必要があるときに使用します。

run とは?

このスキルは、あらゆるウェブプロジェクトをローカルで実行し、実際のブラウザ表示を確認するための最短パスを提供します。主なユースケースは、ユーザーが「サイトをプレビューして」「スクリーンショットを撮って」「アプリをローカルで起動して」と依頼したときです。対応プラットフォームは、Claude Code、Cursor、Codex などの AI エージェント環境で、Node.js が利用可能な環境です。仕組みとしては、`serve.mjs` スクリプトがプロジェクトフォルダを解析し、`package.json` のスクリプト (`dev`, `start`, `serve`, `preview`)、`index.html`、または静的ビルド出力 (`dist/`, `build/`) から適切なサーバーコマンドを自動検出します。空きポートを動的に割り当て、Playwright を使ってスクリーンショットを撮るか、ブラウザを開きます。起動情報は `.run/state.json` に保存され、`--stop` フラグでプロセスツリーを確実に停止します。開発者はこのスキルを使うことで、プロジェクトのセットアップ手順をいちいち調べなくても、即座に動作確認とビジュアルレビューを AI に依頼できるようになります。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/itsdanylol/claude-sitecraft/tree/HEAD/skills/run

Installed? Explore more 生産性&コラボレーション skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

run は何をしますか?

サイトは、実際に動いている姿を見るまでは完成したとは言えません。ソースコードは作者の意図を教えてくれますが、ブラウザはユーザーが実際に目にするものを教えてくれます。このスキルは、フォルダからレンダリングされたページへの最短経路です。

実行方法

node <skill folder>/scripts/serve.mjs <dir> [--port 4173] [--open] [--shot out.png] [--stop] [--detect]
  • --detect は検出結果を表示して何も起動しません。フォルダが不明な場合は最初にこれを行ってください。
  • --port はそこから空きポートを探し始めます。これにより、2つのプロジェクトを同時に実行できます。
  • --open はデフォルトのブラウザを開きます。
  • --shot out.png は Playwright を使ってページを幅1440、フルハイトでレンダリングします。
  • --stop は .run/state.json からプロセスツリーを強制終了します。

プロジェクトの隣に .run/state.json (pid, port, url, command) と .run/server.log が書き込まれます。この2つのファイルが、起動と停止の間のすべての引き継ぎ情報となります。

検出するもの

検出対象実行内容
dev, start, serve, preview のいずれかを含む package.json空きポートで npm run <該当スクリプト> を実行し、PORT を設定
ルートの index.htmlそのフォルダで python -m http.server を実行
public/index.html, dist/index.html, build/index.htmlビルド出力をルートとした静的サーバーを実行
設定ファイルのみでスクリプトがない報告して停止:プロジェクトは独自のコマンドが必要
go.mod, Cargo.toml, pubspec.yaml報告して停止:プロジェクト独自の実行コマンドを使用

フレームワーク固有の情報、ポートのデフォルト値、知っておくべき障害モードについては、references/stacks.md を参照してください。

結果の解釈

このスクリプトは、以下の3点を証明するだけです。プロセスが起動したこと、ポートが応答したこと、ページがレンダリングされたこと。これではわからないことは次の通りです。

  • レイアウトが375、768、1440の各幅で適切かどうか(これには sitecraft/scripts/verify.mjs を使用)
  • コンソールがクリーンかどうか(ここではキャプチャされません。verify.mjs がキャプチャします)
  • スクリーンショットを撮ったページがユーザーの意図したページかどうか(URL を、あなたがリクエストしたルートと照合してください)

したがって、ループは次のようになります。serve.mjs --shot を実行し、自分の目で画像を確認し、修正し、再度スクリーンショットを撮る。1回のパスでスクリーンショットは3回までとします。それを超えた場合、問題はCSSではなく計画にあります。

ルール

  • サーバーを稼働させたままにしないでください。 チェックが終わったら停止するか、まだ起動中でありそのポート番号を明確に伝えてください。ユーザーのマシンに放置された開発サーバーは、ユーザーが後片付けをしなければならない問題です。
  • 止められないものは起動しないでください。 プロジェクトに Docker、データベース、有料のAPIキーが必要な場合は、何かを起動する前にその旨を伝えてください。
  • 実際のURLを報告してください。 「アプリ」ではなく localhost:4173 と報告します。ポート4173が使用中で番号が変わった場合は、新しいポート番号を伝えてください。
  • 推測する前にログを読んでください。 起動失敗のほとんどは、依存関係の欠落、環境変数の欠落、ポートの既存バインドが原因です。.run/server.log に答えがあり、実際のエラーを引用することが理論よりも効果的です。
  • 断りなしにインストールしないでください。 node_modules がない場合、npm install は通常正しい対応ですが、それはプロジェクトに変更を加えることでもあります。実行した場合はその旨を伝え、インストールが大規模な場合は一度確認を取ってください。
  • フレームワークより静的を優先。 ビルド出力が存在し最新の場合、dist/ を配信する方が開発サーバーよりも高速で信頼性が高くなります。

起動しない場合

  1. .run/server.log を読み、最初の実際のエラーを引用してください(最後の行ではありません)。
  2. 依存関係の欠落:プロジェクトで npm install を実行してから再試行してください。
  3. 環境変数の欠落:.env.example を探し、必要なものを特定し、値が秘密で欠落している場合は停止してください。
  4. ポートが既にバインドされている:スクリプトは次の空きポートに自動的に移動します。それでも失敗する場合、フレームワーク設定でポートがハードコードされているのが通常の原因です。
  5. ビルドステップが必要:最初に npm run build を実行し、その後 dist/ を配信してください。
  6. ネイティブまたはコンテナ化:プロジェクトがドキュメント化しているコマンドをユーザーに返してください。すべてのスタックがスクリプトで処理できるわけではありません。

チェックリスト

  • スタックを推測ではなく検出した
  • 起動し、実際のHTTP応答を確認した(単にプロセスを起動しただけではない)
  • 正確なURLとポートを報告した
  • ログだけでなくスクリーンショットも確認した
  • ルートが意図したページと一致していることを確認した
  • 停止した、またはまだ実行中でその場所を伝えた
  • 失敗した場合は実際のエラーを引用した

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

関連スキル