install-script-generator

インストールスクリプトジェネレーター

GitHub の raw URL を使って、ユーザーが単一の bash コマンドで実行できる、堅牢でクロスプラットフォーム対応のインストールスクリプトを生成します。この SKILL.md は簡潔なインデックスです。長いテンプレートや表は、エージェントのコンテキスト予算を節約するため、references/ 以下にあります。

使用するタイミング

• ユーザーが、プロジェクト用の curl | bash ワンライナーを求めている場合。
• リポジトリに、OS、アーキテクチャ、パッケージマネージャーを自動検出する install.sh が必要な場合。
• Python／Go／Node／Rust のモジュールを、まっさらなマシンから1つのコマンドでインストール可能にする場合。

Dockerfile、CI/CD パイプライン、または一度限りのローカルシェルスクリプトには、このスキルを使用しないでください。

前提条件

• リポジトリの <owner>/<repo> が判明しており（git remote -v で確認）、デフォルトブランチが設定されていること。
• 対象ソフトウェアのビルドシステムが特定できること（Makefile、package.json、setup.py、Cargo.toml、go.mod など）。
• scripts/ 以下のヘルパースクリプトを実行するために、ローカルで python3 が利用できること。python3 がない場合は、各ヘルパースクリプトの手順を省略して not run (python3 not found) と記録し、続行してください。その場合、実行結果は PARTIAL になります。

参照ファイル（トークン節約のため必要に応じて読む）

ファイル	読むタイミング
references/install-template.md	install.sh の生成時 — 検出ヘルパー、依存関係インストーラー、メインエントリーポイントを含む完全な bash テンプレート
references/readme-snippet.md	README の更新時 — コピーして使えるインストールブロックと URL 形式の補足
references/edge-cases.md	特殊な OS／sudo／パスの状況に対応するとき、および手順のレポートを書くとき
references/final-report.md	最終レポートを書くとき — 4つのパート、ステータスのルール、結果の表、例、読者向けチェック項目
scripts/env_explorer.py	ローカル環境の調査（OS、アーキテクチャ、パッケージマネージャー、sudo）
scripts/plan_generator.py	環境と対象から installation_plan.yaml を生成
scripts/executor.py	フェーズ3の生成前に、ロールバック機能を使って installation_plan.yaml をドライラン
scripts/doc_generator.py	ユーザー向けの USAGE_GUIDE.md を生成

コンテキストウィンドウを節約するため、これらの内容を会話内に直接記載せず、リンクしてください。

編集前のリポジトリ同期（必須）

フェーズ1の前に、これを一度実行してください。既存のリポジトリでファイルを作成、更新、削除する前に、現在のブランチをリモートと同期します。

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

作業ツリーに変更がある場合は、まず git stash push -u -m pre-sync を実行してから同期し、その後 git stash pop を実行してください。origin がない場合、または rebase／stash の競合が発生した場合は、停止して続行する前にユーザーに確認してください。

ワークフロー

修正試行とは、編集を1回行って、失敗したチェックを再実行することです。同じチェックに対する修正試行は3回までとし、その後はチェックを失敗として記録し、次のフェーズに進んでください。BLOCKED で停止する場合は、残りのフェーズを省略して最終レポートを出力してください。

フェーズ1 — 調査

1. 対象のソフトウェア／モジュール／ツールを特定します。ユーザーが指定しておらず、リポジトリ内にビルド可能なプロジェクトが複数ある場合は、どれを対象にするか尋ねてください。
2. リポジトリ内でビルドファイル（Makefile、package.json、setup.py、Cargo.toml、go.mod など）を調べます。
3. インストール方法を記録します。対象がパッケージマネージャーで公開されている場合はパッケージ名を、そうでない場合はビルドファイルに記載されたビルドおよびコピーのコマンドを記録します。いずれも確認できない場合は、ユーザーに尋ねてください。ユーザーからインストール方法が提示されない場合は、BLOCKED で停止してください。
4. ソフトウェアのビルドと実行に必要な依存関係を列挙します。
5. git remote get-url origin を実行して <owner>/<repo> を確認します。
6. git symbolic-ref --short refs/remotes/origin/HEAD を実行し、origin/ を取り除いてデフォルトブランチを確認します。
7. 手順5または手順6が失敗した場合は、値をユーザーに尋ねてください。ユーザーから回答がない場合は、BLOCKED で停止してください。
8. python3 scripts/env_explorer.py を実行し、OS、アーキテクチャ、パッケージマネージャー、シェル、sudo の利用可否を env_info.json に記録します。

フェーズ 2 — 計画

1. 依存関係を並べ替え、それぞれが必要とするものより先にインストールされるようにします。
2. 各依存関係について、すでにインストール済みの場合にスキップするために install.sh が使う command -v <dep> チェックを記録します。
3. python3 scripts/plan_generator.py --target "<name>" --env-file env_info.json --deps <dep1> <dep2> ... を実行し、installation_plan.yaml を出力します（依存関係には手順 1 のものをスペース区切りで指定します。依存関係がない場合に限り --deps を省略します）。
4. 検出されたパッケージマネージャーで対象が公開されていない場合は、installation_plan.yaml の Install <name> ステップを編集し、command、verify、rollback に install_<tool> が実行するコマンドを設定します。
5. 計画内の # TODO プレースホルダーをすべて置き換えます。plan_generator.py が除外したと警告した依存関係ごとに、ステップを追加します。
6. python3 scripts/executor.py --plan installation_plan.yaml --dry-run を実行します。
7. ドライランを確認します。終了コードが 0 で、最後のサマリー行が DRY RUN: で始まり、標準エラー出力に placeholder command の警告がなく、ステップが手順 1 の順序に従い、各 Install ... ステップの rollback が null 以外であることを確認します。パッケージマネージャーのチェックと最後の検証ステップでは、仕様上 rollback: null です。チェックに失敗した場合は計画を修正し、手順 6 を再実行します。

ドライランでは実行がスキップされるため、確認できるのは計画の構成であり、インストールやロールバックが実際に機能するかどうかではありません。

フェーズ 3 — 生成（主な成果物）

リポジトリのルートに install.sh がすでに存在する場合は、予定している変更をユーザーに示し、上書きする前に許可を求めます。ユーザーが同意しない場合は、BLOCKED で停止します。

references/install-template.md を使って、リポジトリのルートに install.sh を生成します。テンプレートには、組み合わせて作成する 4 つのセクションがあります。

1. ヘッダーと色付き出力のヘルパー（info、ok、warn、err、die）。
2. 検出ヘルパー（detect_os、detect_arch、detect_package_manager、need_sudo）。
3. apt/dnf/yum/pacman/brew/zypper を網羅する install_deps スイッチ。
4. 対象に合わせてカスタマイズした install_<tool>、verify_installation、main。

正確なコードは references/install-template.md を読み取ってください。チャットに貼り付けてはいけません。Windows のサポートが必要な場合は、install.ps1 も生成します（ワンライナー：irm <raw_url> | iex）。

次にスクリプトをチェックします。チェックに失敗した場合は install.sh を修正し、そのチェックを再実行します。

1. bash -n install.sh の終了コードが 0 であること。
2. grep -nE '<owner>|<repo>|<branch>|<software_name>|<Software Name>|install_<tool>' install.sh の出力が空であること。
3. shellcheck が PATH 上にある場合、shellcheck -S error install.sh の終了コードが 0 であること。ない場合は shellcheck not run (not on PATH) と記録します。

ユーザーのマシンで install.sh を実行してはいけません。ソフトウェアをインストールし、sudo を呼び出す可能性があるためです。ユーザーがローカルでの実行を依頼するか、使い捨てのコンテナでの実行を承認した場合に限り、実行します。実行時は、最後の行が [ OK ] Installation complete! でなければなりません。

フェーズ 4 — ドキュメント

1. references/readme-snippet.md のインストールブロックを、<owner>/<repo>/<branch> を置き換えてプロジェクトの README に挿入します。リポジトリに README がない場合は、そのブロックのみを含む README.md を作成します。
2. python3 scripts/doc_generator.py --target "<name>" --plan installation_plan.yaml を実行し、USAGE_GUIDE.md を出力します。
3. 実際の値を使って grep -n "raw.githubusercontent.com/<owner>/<repo>/<branch>/install.sh" <README> を実行し、1 行以上が出力されることを確認します。
4. git ls-tree --name-only origin/<branch> install.sh が install.sh を出力する場合は、curl -fsSI <raw-url> を実行して HTTP ステータスを記録します。それ以外の場合は raw URL not live until install.sh is pushed と記録します。
5. 最終レポートを出力します。

最終レポート

最後のステップ完了レポートの後に、チャット内にプレーンテキストで1回だけ出力します。順番に4つの部分を記載します。Result:（ステータス、対象、一文での要約）、Evidence:（実行したチェックとその結果のみ）、Uncertainty:（未テストの動作。install.sh was not executedを含めます）、Decision:（必要な承認、またはNo approval needed.に続けて、プッシュとクリーンアップの作業）。各部分の内容、結果表、例についてはreferences/final-report.mdを参照してください。

最初に該当するステータスルールを適用します。

1. BLOCKED — <reason> — install.shが作成されていません。
2. PARTIAL — <reason> — install.shは作成されましたが、必須チェックが失敗したか、実行されませんでした。対象は、bash -n、プレースホルダーのgrep、（PATHにある場合の）shellcheck -S error、Phase 2のドライラン、READMEのワンライナー、USAGE_GUIDE.md、または承認を得て実行したinstall.shが[ OK ] Installation complete!で終わらなかった場合です。
3. COMPLETE — すべての必須チェックに合格しました。COMPLETEはinstall.shが実行されたことを意味しません。

出力ファイル

ファイル	説明
install.sh	主な出力 — curl | bashで使用するスタンドアロンのインストーラー
install.ps1	オプションのWindows PowerShellインストーラー
USAGE_GUIDE.md	ユーザー向けドキュメント
env_info.json	ローカル環境の調査結果（一時ファイル）
installation_plan.yaml	順序付けされたインストール手順（一時ファイル）
install_report.md	executor.pyによるドライランのレポート（一時ファイル）

3つの一時ファイルには、このマシンのホームパスとPATHが含まれます。ユーザーから依頼されない限り、これらをコミットしないでください。クリーンアップ対象としてDecision:に記載してください。

受け入れ基準

• install.shがリポジトリのルートに存在し、#!/usr/bin/env bashとset -euo pipefailで始まり、Phase 3の3つのチェックに合格すること。
• OS、アーキテクチャ、パッケージマネージャーを自動検出すること。サポート対象外の場合は、明確なメッセージを表示してゼロ以外のステータスで終了すること。
• sudoを適切に処理すること（root、sudo、または即時終了）。
• 最後にインストールを検証すること（command -v $TOOL_NAMEと、利用可能な場合は--version）。
• READMEに、<owner>/<repo>/<branch>のraw GitHub URLを指定するcurl -sSL ... | bashのワンライナーが含まれること。
• install.shが正常に実行された場合、最後の行が[ OK ] Installation complete!であること。
• 最終レポートがResult:で始まり、上記ルールに基づくステータスを記載し、references/final-report.mdにある4つの確認事項を満たすこと。結果を見つけやすいこと、事実と推測を区別すること、主張の根拠をたどれること、次の判断が明確であること。

エッジケース

一覧についてはreferences/edge-cases.mdを参照してください。主な項目は次のとおりです。

• サポート対象外のOS／アーキテクチャ — 検出した値を示してdieを呼び出し、何が原因かをユーザーに伝えます。
• パッケージマネージャーがない — install_depsはUnsupported package manager 'unknown'で中止します。
• sudoがない — need_sudoはRequires root. Run as root or install sudo.で終了します。
• Windowsネイティブ環境 — install.ps1を別途生成します。MSYS／Cygwinではinstall.shが警告を表示します。
• スクリプトがサブディレクトリにある — raw URLのパスを調整し、READMEのスニペットに記載します。
• 対象がパッケージマネージャーにない — その計画ステップ（Phase 2のステップ4）を編集し、ビルドファイルからinstall_<tool>を記述します。

ステップ完了レポート

各フェーズの後に、√／×のチェック項目とResult: PASS | FAIL | PARTIALの行を含む◆ブロックを出力します。形式とフェーズごとのチェック項目についてはreferences/edge-cases.mdを参照してください。

期待される出力

完全に実行した場合の最終レポート（全体の例はreferences/final-report.mdにあります）：

Result: COMPLETE — mytool installer
  curl -sSL https://raw.githubusercontent.com/owner/mytool/main/install.sh | bash
Evidence:
  bash -n install.sh: exit 0; placeholder grep: no matches; shellcheck -S error: exit 0
  executor.py --dry-run: "DRY RUN: 5 step(s) listed for mytool; nothing was executed."
Uncertainty:
  install.sh was not executed. Raw URL not live until install.sh is pushed to main.
Decision: No approval needed.
  Remaining action: commit and push install.sh; delete the three working files.

後でユーザーがワンライナーを実行すると、スクリプトのバナーは次の行で終わります。

[INFO]  OS: linux | Arch: x86_64 | Package Manager: apt
[ OK ]  Dependencies installed
[ OK ]  mytool 1.2.0 installed
[ OK ]  Installation complete!