machine-setup

Imported from miyabi-satoh/yorozuya (.agents/skills/machine-setup/SKILL.md). Install upstream with npx skills add miyabi-satoh/yorozuya --skill machine-setup. Copyright stays with the author.

新しいマシンに、ユーザーが選んだアプリ・ツールを入れ、ユーザーの設定ファイルを取り込む。人の手が要ることと判断は、なるべくステップ0で先に聞き、その後は放っておけるように進める。

この手順を最後まで通したのは、Ubuntu の Docker コンテナでの1回だけ。手順と違う挙動に出会ったら、進み具合のファイルの「想定外」に書き、最後の報告に載せる。

ユーザーと話す言語は、ステップ0の最初に聞いて決め、以降はずっとその言語で聞き、答える。 新しいマシンには、ユーザーの言語や対話の好みの設定がまだ無い。決めた言語は進み具合のファイルに書き、続きからのときも同じ言語を使う。

読むファイル

どれもこの SKILL.md と同じ場所の references/ にある。この SKILL.md を URL から読んでいるなら、URL の SKILL.md を references/<ファイル名> に替え、中身をそのまま返す手段（curl -fsSL。Windows PowerShell では curl.exe -fsSL）で取る。取れなかったら、始めずにユーザーに伝える。

決まり

1. 進み具合は ~/machine-setup-progress.md に書く。 頭には「続きは <この SKILL.md の URL かパス>（<読んだ日時>）を読み（URL なら curl -fsSL、Windows PowerShell では curl.exe -fsSL で取る）、その『続きを頼まれたら』に従う」と文で書く。そのあとに次の欄を置き、ステップを終えるたびに更新する: 使う言語、ステップ0の答え、ステップごとの状態、失敗、ユーザーが手でやること、ステップ6で確かめる、再起動のあとで確かめること、想定外。認証の欄には「済み / 未」だけを書き、鍵・トークン・パスワードの中身は載せない。
2. 入れ方は、その場で公式の情報を確かめて決める。 パッケージ ID や URL は変わる。パッケージマネージャ（Homebrew、apt、winget など）でまとめて更新できる手段を優先し、無ければ公式のインストーラを使う。バージョンの指定が無ければ、選んだ入れ方で入る最新の版にする。OS 標準のリポジトリの版が大きく古いときは、公式が案内する別の入れ方を案に出して聞く。入った版は進み具合に書く。入っているものと、今の OS に手段が無いものは飛ばして記録する。WSL では GUI アプリを飛ばす。
3. 失敗は記録して次へ進む。 ステップ7でまとめて報告する。
4. 入れたものの PATH は、動いているプロセスには届かない。 入れた直後に使うものは、フルパス、ランタイムの管理ツールの exec（mise なら mise exec）、PATH の読み直し（os-notes）で呼ぶ。シェルの呼び出しの間で環境変数は引き継がれないので、読み直しは使うコマンドと同じ呼び出しの頭で行う。再起動はステップ7の1回にまとめる。先に再起動しないと進めないステップに当たったら、そこまでを進み具合に書き、ユーザーに再起動を頼む。
5. rc ファイルなどの設定は、ステップ5で取り込む設定ファイルから来る。 インストーラが rc への追記を案内したとき、または rc に書き足したときは、その行を進み具合の「ステップ6で確かめる」に書き留める。rc を書き換えないフラグがあれば、それを使う。Claude Code 自身の PATH（~/.local/bin。Windows は %USERPROFILE%\.local\bin）は、最初からそこに載せておく。ステップ6では、取り込んだ設定に無いものだけを追記する。設定ファイルを持ってこないユーザーなら、ステップ6で案内どおりに追記する。
6. 実行の前にユーザーに確かめるもの: ログインシェルの変更、既存ファイルの上書きと退避、sudo や管理者権限の要る大きな変更、鍵や認証の要る操作。ステップ0で先に決めてもらえたものは、その答えに従う。
7. ユーザーに打ってもらうものは、Claude が動いている端末とは別の端末で打ってもらう。 この手順で「別の端末」は、もう1つのターミナルを指す。ステップ0で無いと答えられたら、Claude Code を終了してもらった端末を指す。打ってもらうコマンドはメッセージの最後に置き、打ち終わったら何と返せばよいかを添える（途中に置くと見落とされる）。
8. 対話を求めるコマンドは、非対話のフラグで Claude が打つか、別の端末で打ってもらう。 非対話のフラグの例: apt / dnf / flatpak の -y、winget の --silent --accept-source-agreements --accept-package-agreements。フラグで避けられない対話（gh auth login、パスワードの入力、規約の同意、y/n 以外の選択など）は、別の端末で打ってもらうコマンドとして扱う。! で打ったコマンドは出力を会話に取り込むだけで、入力を受け付けない。エラーを出さずに何もせず終わることもある。Claude Code 自身の案内が対話式のコマンドに ! を勧めても、別の端末で打ってもらう。
9. 管理者権限の要るコマンドは、1本のスクリプトのファイルにまとめ、別の端末で1行だけ打ってもらう。 長いコマンドを端末に貼ってもらうと、折り返しで途中から切れる。スクリプトは最初の失敗で止まるようにする（bash は set -e、PowerShell は $ErrorActionPreference = 'Stop'）。打ち終わったら、中の操作を1つずつ確かめて進み具合に書き、それからファイルを消す。途中で失敗していたら、済んだ操作を外してから打ち直してもらう。
   • macOS / Linux / WSL: まず sudo -n true で、パスワード無しで通るかを見る。通らなければ、そのステップで sudo の要るコマンドをまとめ、bash <ファイルのパス> と打ってもらう。別の端末で打った sudo -v は、Claude のコマンドには効かない。ログインシェルの変更も本人のパスワードを聞くので、sudo chsh -s <シェルのパス> <ユーザー名> としてスクリプトに入れる
   • Windows: 管理者権限の要るコマンドを .ps1 にまとめ、管理者として開いた PowerShell で powershell -NoProfile -ExecutionPolicy Bypass -File "<ファイルのパス>" と打ってもらう。既定の実行ポリシーでは .ps1 をそのまま実行できないので、その実行だけ許す（試していない）
10. ユーザーに任せるもの: アカウントの認証（gh auth login など）、Claude Code の API キー、GUI アプリのログイン、管理者権限の確認画面（UAC など。マシンの前でしか押せない）。

手順

0. 聞き取る。 先に ~/machine-setup-progress.md があるかを見る。あれば、そこに書いた言語で、続きからか最初からかを聞く（最初からなら、古いファイルは名前を変えて残す）。続きからなら「続きを頼まれたら」に移る。

   次に、OS、アーキテクチャ、入っているパッケージマネージャ（brew / apt / dnf / snap / flatpak / winget など）を調べる。os-notes に節があるのは macOS・Ubuntu / WSL・Windows で、ほかの OS なら近い節を読み替える。そのあとユーザーに聞く。1回に聞くのは1問だけにする。 選択肢で答えられる手段（Claude Code の AskUserQuestion など）があれば使う。その手段は選択肢が2〜4個で、「他のもの（自由に書く）」が自動で付く。無ければ番号付きの選択肢を並べ、「他のもの」も自分で足す。答えが出るたびに進み具合のファイルに書く。大きな分岐から聞き、答えで要らなくなった問いは飛ばす。

   1. 使う言語。依頼文の言語を案にする。この問いだけは、依頼文の言語と英語を並べて聞いてよい
   2. Claude が動いている端末とは別に、ユーザーが打てる端末があるか（GUI の別の窓、SSH、tmux などのペイン）。あると、ずっと楽に進められると伝える。無ければ、ユーザーに打ってもらうたびに、先に進み具合のファイルを更新してから Claude Code を終了してもらい、打ち終わったら同じディレクトリで claude --continue を打って戻ってもらう。Remote Control を使っていて、戻ったあとつながっていなければ /rc も打ってもらう
   3. 確認画面（UAC など）が出る OS なら、マシンの前にそれを押せる人がいるか
   4. 自分の一覧があるか。あれば、それを使う。認証なしで読めなければ、問い7は「ステップ3のあとで一覧を読んで聞く」と進み具合に書いて済ませる
   5. 設定ファイルを持ってくるか。持ってくるなら、次を1問ずつ: 置き場所（git のリポジトリ、クラウドストレージ、手元のメディアなど。例は github.com/<owner>/<repo> の形で示す）、取ってくる手段（gh auth login、SSH 鍵、認証なし、ストレージのアプリ）、管理ツール（genres.md の「設定ファイルの管理」から候補を出す）、手元に置くパス（管理ツールの標準の場所を案にし、作業用のディレクトリの外にする。そこを消すとリンクが切れる）。private なリポジトリを SSH で取るなら SSH の URL も
   6. SSH 鍵を使うなら、鍵がこのマシンにあるか。無ければ、別のマシンから移すか、新しく作って登録するか
   7. 入れるもの: genres.md のとおりに、節ごと・ジャンルごとに聞く。管理ツールを入れるのに要る言語やツールは、聞かずに足して、足したと伝える
   8. ログインシェルを変えるか
   9. 設定ファイルとぶつかった実ファイルの退避先

   すべての問いに答えが出るか、あとで聞くと進み具合に書いたら、このステップは終わり。

1. パッケージマネージャを用意する。 無ければ公式の手段で入れ、os-notes に従って今のシェルから呼べるようにする。今のシェルで --version が通れば終わり。

2. 取ってくる道具を入れる。 ステップ0で選ばれた手段に要るもの（git、手段によって gh、またはストレージのアプリ）。Windows では、手段によらずここで Git for Windows を入れる（os-notes）。入れた道具のそれぞれで、--version が通るか、インストール先に実体があると確かめたら終わり。

3. 認証してもらい、設定ファイルを取ってくる。 認証は別の端末で打ってもらう。SSH で初めてつなぐなら、ホスト鍵を、つなぐ先が公開している fingerprint と照らしてから known_hosts に登録する（GitHub なら https://api.github.com/meta の ssh_key_fingerprints）。取ってきたものは、ステップ0で決めた手元のパスに置くだけにし、展開はステップ5でする。git なら git -C <パス> rev-parse HEAD が通ること、ストレージなら同期が済んで実体があること（プレースホルダでないこと）を確かめ、置いた場所を進み具合に書く。自分の一覧をあとで読むことにしていたら、ここで読み、ステップ0の問い7の残りを1問ずつ聞いて進み具合に書く。ここまで済んだら終わり。

4. 選ばれたものを入れる。 ステップ0で選ばれたもののうち、シェル、OS の設定、設定ファイルの管理ツールを除くすべてを、GUI アプリ、CLI ツール、開発言語、フォント、それ以外の順に入れる。これらのすべてが、進み具合に「入れた / 入っていた / 飛ばした / 失敗」のどれかで載ったら終わり。

5. 設定ファイルを展開する。 管理ツールがあれば入れる。ぶつかりは、展開先ごとに実物を見て調べる。管理ツールの dry-run の表示は、実物を見る前の目安として使う。

   • symlink を張るもの: 取ってきた設定を指す symlink か（test -L と readlink。Git Bash に切り替わる前の Windows では (Get-Item <パス>).LinkType と .Target）
   • 生成・コピーするもの: 取ってきた設定と同じ中身か（管理ツールの diff か diff）

   ぶつかる実ファイル（Claude Code が起動したときに作った ~/.claude/ の中身、gh auth login が作った ~/.gitconfig、ステップ4までにできた rc ファイルなど）は、ステップ0で決めた退避先へ展開先ごとに退避する。退避先に同じ名前が既にあれば、上書きせずにユーザーに聞く。退避したものが退避先にあることを確かめてから、展開し直す。退避した rc と取ってきた設定を見比べ、ステップ4までにインストーラが書き足した行があれば「ステップ6で確かめる」に写す。~/.claude は中の展開先ごとに扱い、ディレクトリそのものは、動いている Claude Code の会話や認証と一緒にその場に残す。展開先が ~/.claude そのものなら、そこで止めてユーザーに聞く（マシンの前で Claude Code を止めてから差し替えてもらう）。

   Claude Code 自身の設定（~/.claude/settings.json など）は最後に展開する。その前に、hooks や statusLine が呼ぶコマンドが入っているかを見て、無ければ入れるか、「ユーザーが手でやること」に書く。ランタイムの管理ツールで入れたコマンドは動いている Claude Code の PATH に無いので、展開した直後から hooks が失敗しうる。「再起動のあとで確かめること」に、起動し直した Claude Code で hooks が通るかを書く。

   すべての展開先が、取ってきた設定を指す symlink か、同じ中身になっていると確かめたら終わり。

6. シェルと初期設定。 ステップ0で選ばれたシェルとその拡張、OS の設定、選ばれたものに公式が案内する初期設定（グループへの追加、サービスの有効化、プラグインなど）、取り込んだ設定ファイルが前提にしているもの（ロケール、指定されたエディタなど）を進め、進み具合の「ステップ6で確かめる」を片付ける。どれもすべて進み具合に載ったら終わり。

7. 仕上げる。

   • 次のログインで claude が見つかるかを、Claude のプロセスの PATH を引き継がない形で確かめる。macOS / Linux は env -i HOME="$HOME" USER="$USER" TERM="$TERM" <ログインシェルのパス> -lic 'command -v claude'。Windows は、ユーザーの PATH（[Environment]::GetEnvironmentVariable('Path', 'User')）に .local\bin が含まれ、Test-Path "$env:USERPROFILE\.local\bin\claude.exe" が通るかを見る。見つからなければ、Claude Code 自身の PATH を設定ファイルに足すよう報告に書き、足すまではフルパスで起動できると添える（macOS / Linux は ~/.local/bin/claude、Windows は $env:USERPROFILE\.local\bin\claude.exe）。
   • 再起動や再ログインで効くもの（OS の機能の有効化、グループへの追加、ログインシェル、wsl --shutdown など）を集め、進み具合の「再起動のあとで確かめること」に書く。
   • 次を Markdown で報告する。
     • 入ったもの
     • 失敗したもの、原因、勧める対処
     • ユーザーが手でやること（ログイン、GUI での初期設定など）
     • 想定外（この手順の直すべきところ）
     • 再起動のあとの続け方。このマシンで最初と同じ作業用のディレクトリに移って claude を起動し直し、「~/machine-setup-progress.md を読んで続けて」と送ってもらう。Remote Control を使っているなら、再起動で止まるので、起動し直したあと /rc を打ってからアプリで送ってもらう（信頼の確認は、その作業用のディレクトリについて記録されている）

   報告したら、このステップは終わり。

続きを頼まれたら

~/machine-setup-progress.md を読み、そこに書いた言語で話す。頭に書いた場所から SKILL.md と references を読み直して、終わっていないステップから続ける。読み直した手順と進み具合のファイルの欄やステップが合わなければ、ユーザーに伝える。「再起動のあとで確かめること」があれば、先にそれを確かめて結果を進み具合に書く。すべてのステップが終わっていたら、確かめた結果を報告し、進み具合のファイルを消すか残すかをユーザーに聞く。