setup-skills

スキルのセットアップ

ship スキルが読み込む、リポジトリごとのドキュメントを作成します。書き込みの前には毎回、人に確認してください。このスキルが行うのは、親スキルである setup-matt-pocock-skills が未完了のまま残し、ship が必要とすることだけです。トラッカー、トリアージの用語、ドメインドキュメントの構成に関する親スキルの回答はそのまま使い、親スキルが未確定のまま残した点だけを質問します。

ここで作成するすべてのドキュメントはエージェントが読みます。文章には writing-for-agents を適用してください。

プロセス

1. 前提条件：指示して停止

調査を始める前に、次の3点をすべて確認してください。いずれかに失敗したら、正確なコマンドを表示し、続けて「then rerun /setup-skills」と表示して停止します。

1. 親ドキュメント。 docs/agents/issue-tracker.md、docs/agents/triage-labels.md、docs/agents/domain.md が存在すること。存在しない場合：/setup-matt-pocock-skills。例外：ホスト（ステップ2）が Azure DevOps で、issue-tracker.md が存在しないか、親スキルの自由記述形式の「Other」ページである場合は、同ファイルの代わりにベンダー提供の issue-tracker-ado.md を書き込むことを提案し（先に確認）、その後続行します。親スキルが提供するのは GitHub、GitLab、ローカル用のテンプレートのみです。

2. 派生コピーとしての合成スキル。 .claude/skills/ に code-review、tdd、codebase-design、writing-for-agents、triage、find-docs、show-me があり、それぞれがリポジトリの skills-lock.json に記録されていること（インストール時に skills CLI が書き込みます）。各スキルは、その行で固定された ref を使っている必要があります。これはソースリポジトリでテストされたアップストリームのコミットです。ロックファイルに別の ref で記録されているコピー、または記録のないコピーは、固定された ref と一致していません。その行を表示してください。コピーが存在するのにロックファイルに記録されていない場合は、手動管理されているため「will be replaced by the derived copy」と報告し、確認を得てから同じ行で更新してください。~/.claude/skills にあるグローバルコピーでは、この確認を満たしません。個人用スキルがリポジトリのスキルを気付かれずに上書きするため、ship の合成スキルはリポジトリ内に置く必要があります。満たしていない場合は、次を表示してください。

   npx skills add mattpocock/skills#f3fc5632f401156837ee3872f14fe33ccf1024ea --skill code-review --skill tdd --skill codebase-design --agent claude-code -y
   npx skills add mattpocock/skills#c55ee46073ed923f86ce59a5eb3b6d895095d1b7 --skill writing-for-agents --agent claude-code -y
   npx skills add mattpocock/skills#d81f3a183412e71a5b1e84ca21bc1a35eea03a60 --skill triage --agent claude-code -y
   npx skills add upstash/context7#3131245817e9e40626d8f43ce85dabab09d4ff35 --skill find-docs --agent claude-code -y
   npx skills add humanlayer/skills#ca7c8088db69e315a8b2deea43820270457f8f3c --skill show-me --agent claude-code -y
   

3. ship、cloud-ship、setup-skills。 .claude/skills/ship、.claude/skills/cloud-ship、.claude/skills/setup-skills が存在し、ロックファイルにも記録されていること。ship フォルダーのフロントマターに metadata.version がない場合は、汎用スキルができる前の手動管理コピーです。「will be replaced by the derived copy」と報告し、確認を得てから更新してください。setup-skills にはステップ1.2の扱いを適用します。この確認を実行しているコピーは証拠にならないため、skills-lock.json を読み込んでください。満たしていない場合は、次を表示してください。

   npx skills add Gharib89/skills --skill ship --skill cloud-ship --skill setup-skills --skill update-skills --agent claude-code -y
   

   update-skills は前提条件ではありません。これがなくても処理は拒否されません。ロックファイルに存在しない場合はそのことを報告し、インストールを行う同じ行を表示して続行してください。

   常にプロジェクトスコープを使います。つまり、インストール行には -g を付けません。

2. ホスト

git remote get-url origin から判定します。github.com は github、dev.azure.com または visualstudio.com は ado です。それ以外は対象範囲外として停止します。

docs/agents/issue-tracker.md のタイトル行と照合してください。一致しない場合は、両方を明示して停止します。

次に、ship 独自の事前チェックを実行してホストのツールを検証します。存在するホストチェックはこれだけです。イシューなしで呼び出し、ホストとプロファイルだけを判定します。

.claude/skills/ship/scripts/preflight.sh none

host-unreachable の理由（CLI がない、拡張機能がない、サインインしていない、プッシュ権限がない）で終了コード2になった場合は、その理由を示してここで停止します。セットアップは人がその場にいて認証を修正できる唯一の機会です。profile missing で終了コード1になるのはこの時点では想定どおりなので、続行します。

事前チェックでは Git リモート自体を検証できないため、git ls-remote --heads origin も実行してください。これが失敗すると、後で existing branch: remote unreadable として表面化し、実行中のすべてのプッシュが失敗します。Azure DevOps で Entra の az login を使い、PAT がない場合は、トラッカードキュメントの Auth 行にあるリポジトリローカルの認証情報ヘルパーを提案してください。同じトークンから Git のパスワードを発行します。

3. 調査

何かを話す前に、リポジトリ全体を各セクションまで一度読み込んでください。右側の列は、調査だけでそのセクションの内容を確定できるか、それともウォークスルー（ステップ4）が必要かを示しています。 まずハーネスです。Local gate と Cloud lane の行を決めるためです。ハーネスのプロファイル docs/agents/harness.md が唯一の判定材料です。単独の scripts/check.sh や、ハーネスの CLAUDE.md ブロックは該当しません。存在する場合は、## Check entry point の Location: と ## Cloud の Setup: の2行を読み、リポジトリのルートから <Location> full を1回実行します。ここでの <Location> は、ship プロファイルの行ではなく、ハーネスの行です。エントリーポイントは、その実行が終了コード 0 または 1 で終了し、stdout に rung、verdict、および checks オブジェクトを含む JSON の1行を出力した場合に適合します。チェックが失敗していても、回答としては適合です。それ以外の場合は harness present, check entry point non-conforming: re-run /setup-harness と報告します。この場合、ハーネス上の Local gate はそこで停止します。そのエントリーポイントでは何も対応付けられないため、ゲートの新規作成も書き換えも行いません。既存のゲートは引き続きステップ5で1回実行し、ship プロファイルの Location: にそのパスを記録します。ゲートがない場合は、Location: に scripts/local-gate.sh を記録します。これは /setup-harness でエントリーポイントを修正した後、setup-skills を再実行した際に書き込まれるパスです。また、ステップ7で、それまではローカルゲートが存在しないことをユーザーに伝えます。それ以外のすべての項目は続行します。check.sh を呼び出さない Cloud bootstrap も含まれます。ハーネスが存在しない場合は、ステップ4の冒頭でハーネスがない場合の質問をします。

セクション	読み取る内容	調査で確定済み？
ホスト	ステップ2	はい
Worktree	git status --ignored --short の Carry:。小さなドットファイル（.env*、*.local）に限定します。Bootstrap: は、ローカルゲートでは担当できないセットアップスクリプトが存在しない限り None.	はい。リストを確認
Local gate	ハーネスがある場合、ステップ5のゲートはハーネスプロファイルの Location: に書き込みます。それ以外の場合は scripts/local-gate.sh、次に .claude/skills/ship/scripts/local-gate.sh、次に scripts/ship/local-gate.sh です。ロックファイルで実行ランナーが決まります（package-lock.json は npm、pnpm-lock.yaml は pnpm、uv.lock は uv run pytest、pyproject.toml のみの場合は pytest）。Small node: の構文はランナーに合わせます。また、変更したドキュメントのパスを示す docs クラスの行も記録します	場所ははい。node の構文は確認
CI	Legs: は、pull_request トリガーを持つすべてのワークフローのすべてのジョブ（.github/workflows/*.yml。ADO の場合は、ビルド検証ポリシーで指定されたパイプライン）です。その他のワークフローは、PR 向けではないものとして文章で記載します。No-checks legal: yes とするのは、PR ワークフローに paths: フィルターがある場合、または PR ワークフローがまったくない場合に限ります。Legs: None. と合わせると、この組み合わせによって ci-wait の no-checks grace がゼロになります。Push policy:	legs ははい。push policy は確認
レビュアー	レビュアーの種類ごとに1つのリスト。下記の ### レビュアー	確認済み
コーディング規約	CLAUDE.md に記載されたパス、CODING_STANDARDS.md、CONTRIBUTING.md、docs/contributing/*	はい。なければスタブ
検証	発見できない項目です。テストマーカー（e2e、integration）、Docker の使用、ブラウザーテスト用スクリプトをもとに設定します	確認済み
バージョン管理と変更履歴	semantic-release の設定、changesets、version-gate またはバージョン更新スクリプト、CHANGELOG.md。In-PR requirement:	確認済み
PR	.github/pull_request_template.md または .azuredevops/pull_request_template.md：存在の有無、見出し、および終了参照が最初の ## 見出しの前後どちらにあるか	はい
公開サーフェス	Default. を提案	確認済み
トリアージ	triage-labels.md の needs-triage 行の右列からコピー	はい
ドキュメントの同期	README.md、docs/、GLOSSARY.md、リポジトリに含まれるスキル。Agent-facing: は docs/agents/、.claude/skills/	はい。確認
現在のドキュメント	常に context7。Microsoft のスタック（D365、Azure、Power BI、.NET）がある場合は Microsoft Learn。Pinned:	確認済み
Cloud lane	PR cap: 3。ハーネスがある場合、Bootstrap: は scripts/cloud-ship-bootstrap.sh で、ステップ5の Cloud bootstrap が書き込みます。ハーネスがない場合は、そのファイルが存在すればそのパス、なければ None.	はい

また、ステップ5用に次の3項目を記録します。

• 汎用的な仕組みで置き換える、リポジトリごとの ship スクリプト：scripts/ship/ 配下の claim、isolate、preflight、poll-pr、ci-wait、merge-and-verify、merge、reflect、release、_lib、および .claude/skills/ship/scripts/ 配下の claim、merge-and-verify、release。後者のほかのファイルは、派生コピー独自の仕組みです。
• ホストがすでに持っている、triage-labels.md の5つの役割ラベルと dimension-labels.md の14のディメンションラベル。gh api --paginate "repos/{owner}/{repo}/labels" --jq '.[].name' で確認してください。gh label list はデフォルトで30件を取得して黙って切り捨てるため、ページネーションを使って読み取ってください。GitHub のラベル名は大文字と小文字を区別しないため、大文字と小文字を区別せずに照合してください。別の大文字・小文字で同じラベルがある場合は、未設定ではなく名前変更として記録します。ADO ではタグは使用された時点で存在するため、確認するものはありません。
• docs/agents/triage-labels.md に ## Dimension labels の見出しがすでにあるかどうか。

レビュアー

reference/reviewers.md の指示に従い、レビュアーの種類をそれぞれ検出し、Resolve:、Workflow:、Cap: の各行を確定してください。

4. 提示してから進める

調査全体を一度だけ提示します。各セクションで確認する内容を、それぞれ1行で示してください。その後、確認対象の行だけを、セクションごとに1つずつ質問します。ユーザーが一言で回答できるよう、推奨回答を先に示してください。選択肢によって本当に分岐する場合のみ、1行で説明を添えます。調査の段階で確定したセクションはドラフトに表示し、質問は省略します。

質問の順序と、最初に提示する推奨回答：

• ハーネスなし：ステップ3でハーネスプロファイルが見つからなかった場合に限り、最初に質問します。「ハーネスが見つかりませんでした。先に /setup-harness を実行する（推奨）か、このまま続行してください」。最初の選択肢では何も書き込まずに処理を終了し、「/setup-harness を実行してから /setup-skills を再実行してください」と表示します。これがないリポジトリでは、インストール行として npx skills add Gharib89/skills --skill setup-harness --agent claude-code -y を表示します。続行を選ぶと、自己完結型ローカルゲート項目を採用し、クラウドのブートストラップはスキップします。ブートストラップはステップ3で確認した状態のままです。回答はどこにも記録されないため、実行のたびに再度尋ねます。
• ローカルゲート、小規模なノード：ランナー自身の Node 構文を、リポジトリのテストからの例を1つ添えて示します。また、変更したドキュメントのパスである docs クラスの値も、例を1つ添えて示します。
• CI、プッシュポリシー：分単位の課金がある場合（プライベートリポジトリ、ADO の並列ジョブ）は one push per review round。それ以外は Default.。
• レビュアー：検出した各レビュアーと、推定されるトリガーを示します。続けて「検出されていないレビュアーはいますか？」と尋ねます。その後、Claude Code に関する質問を1つだけ行います。調査で Claude のワークフローがすでに見つかった場合は尋ねません。ドラフトに別のレビュアーが記載されている場合は、そのレビュアーの代わりとなるものとして明示し、リクエスト時に実行する方式を先に提示します。ドラフトにレビュアーが記載されていない場合は、両方の方式とトレードオフを1つの質問で尋ねます。ship がほとんどの PR を作成するリポジトリではリクエスト時の方式を、それ以外ではプッシュ時の方式を先に提示します。リクエスト時（コメント経由、Fallback-for: None.、Cap: 2）なら、小規模レーンの実行は1ラウンドで、上限が適用されます。また、どのコメント投稿者も起動できます。プッシュ時は、人によるプッシュも含め、すべてのプッシュをレビューします。上限は目安です。この1つの回答で、ステップ5でひな形を作成する方式が決まります。追加の質問はありません。各レビュアーについて上限を尋ねます。推奨値は、リクエスト時なら2、プッシュ時なら3、自動で1回だけ実行する場合は None. です。最後に Self-review cap: を尋ねます。これは、実行中にフェーズ4のセルフレビューを繰り返す最大回数です。推奨値は3です。1にすると、Schema 5 以前と同様、すべての実行が1ラウンドに制限されます。
• 検証：シードごとに1つのブロックを提示します。リポジトリ内に実システムと連携する記述がなければ None. とします。
• バージョニング：調査で判明した内容を示した後、ship の動作を変える1行である In-PR requirement: を尋ねます。
• 公開対象：リポジトリが API 以外（ゲートルール、パレット、バンドル入力）も公開している場合を除き、Default.。
• 現在のドキュメント、固定バージョン：リポジトリのマニフェストでメジャーバージョンが固定されており、API が最近変更されたライブラリ。

5. 確認して編集する

以下のすべてを含むドラフト全体を表示し、書き込む前にユーザーが編集できるようにします。ここでフィールド単位の検証を行います。人がその場で修正できる唯一のタイミングです。レビュアーブロックには、テンプレートに記載されたすべての Label: 行（Cap: を含む）が含まれている必要があります。また、reference/reviewers.md にある、ship の事前チェックで拒否される10種類のレビュアー形式がそれぞれ含まれていないことを確認します。

次に、Self-review cap: は1以上の整数であること、すべての Also proven by CI: に ## CI で定義されたレッグが記載されていること、そのようなレッグがある場合に限り defer-to-ci が使われていること、Host: がステップ2と一致すること、見出しが14個あり順番どおりであること、Schema: 行が ship の metadata.profile-schema と一致することを確認します。

ship-profile.md に基づく docs/agents/ship.md：14個すべての見出し、軸をデフォルトにする場合は None. または Default.、テンプレートコメントを削除します。

ship-block.md に基づく ### Ship サブブロック：テンプレートコメントを削除し、親が選んだ CLAUDE.md または AGENTS.md の既存の ## Agent skills ブロック内（ブロックがあるファイル）に配置します。すでにある場合はその箇所を更新し、ファイル内に必ず1つだけ残します。

ハーネス上のローカルゲート（ステップ3のプローブが仕様に準拠している場合）。check.sh full は実行するすべてのゲートを、チェックごとにそのチェック名で提供します。ローカルゲートには Ship に必要なものだけを追加します。

• 存在しない場合：local-gate-harness.sh から scripts/local-gate.sh を作成します。__CHECK__ はハーネスプロファイルの Location: パスに、__DEPS__ と __RUNNER__ はステップ3の Local gate 行にある値に置き換えます。secrets は以下の自己完結型ゲートの項目と同じ方法で接続し、指定されたスロットには Ship 専用ゲートを配置します。これにはベースに対するチェックと、CI だけで証明できる各 CI レッグに対する mark <leg> deferred-to-ci が含まれます。ここでのゲートにはレッグ名ではなくチェック名を使うため、自己完結型ゲートの「レッグごとに1つのゲート」というルールは適用されません。ただし、各 deferred-to-ci マークには、## CI に記載されたレッグ名を指定します。
• 存在する場合：テンプレートに沿った書き換えを提案します。実行コマンドに基づいて照合し、名前に関係なく check.sh full がすでに実行する各ゲートを削除します。テンプレート独自の secrets、deps、小規模レーンの tests が既存ゲートのものに置き換わります。Ship に必要なゲート（ベースに対するものと deferred-to-ci マーク）は Ship 専用スロットに残し、チェックに一致せず Ship にも不要なゲートはそれぞれ人に提示して、回答に応じて残すか削除します。差分を表示し、確認後に書き込みます。

ハーネスを使わない自己完結型ローカルゲート：

• 存在しない場合：local-gate.sh から scripts/local-gate.sh を作成します。## CI の記載どおりのレッグ名で、CI レッグごとにゲートを1つ設定します。実行方法が明らかなものはローカルで実行し、そうでないものには deferred-to-ci を指定します。secrets は検出されたスキャナー（gitleaks、ggshield、detect-secrets、trufflehog）に接続します。スキャナーが検出されない場合は、何を追加すべきかを示すコメントを添えて unavailable のままにします。
• 存在し、仕様に準拠している場合（verdict と gates を含む JSON 判定、secrets ゲート、--small フラグと --base フラグ）：そのまま使用し、Location: に場所を記録します。
• 存在するものの仕様に準拠していない場合（テキストを出力する、--small が位置引数になっている、unavailable ステータスがない）：以前のゲートが実行していたチェックをすべて維持したうえで、契約に準拠するよう書き換えることを提案します。差分を表示し、確認後に書き込みます。人が同意した場合に限り、Location: を scripts/local-gate.sh に変更します。

どちらのローカルゲート項目を実行した場合も、または仕様に準拠していないプローブの後で既存ゲートを残した場合も、作成または維持したゲートを一度実行し（例の node を指定して --small を実行）、判定の形式を確認します。判定は verdict、base、lane、gates.secrets を含む JSON オブジェクトである必要があります。 クラウドのブートストラップはハーネスがある場合に実行し、ハーネスがない場合はスキップします。cloud-ship-bootstrap.sh をもとに scripts/cloud-ship-bootstrap.sh を作成します。このスクリプトは実行時に docs/agents/harness.md から Setup: を読み取り、そのクラウドセットアップを実行するため、その部分は記入しません。テンプレートの設定コメントに従って SCANNER と SCANNER_INSTALL を記入します。クラウドセッションのネットワークでブロックされる GitHub リリースアセットのダウンロードを、SCANNER_INSTALL に記入してはいけません。そのため、既存のブートストラップに固定ダウンロードがある場合は、残さず置き換えます。マークされた欄には、リポジトリの Ship 専用ステップを記入します。ライブ e2e の認証情報やプロファイルなど、Ship 専用のものが必要な場合を除き、ステップはハーネスのクラウドセットアップに含めます。既存のブートストラップは、テンプレートに沿って書き換える案を提示します。クラウドセットアップが対応する各ステップは、インストールするものを基準に特定して削除し、残りは Ship 専用ステップとして維持します。判断が曖昧なものはすべて人間に提示し、回答に応じて維持または削除し、差分を表示して、承認後に書き込みます。

PR テンプレート、コーディング規約、トリアージラベル、および ## Dimension labels セクション： reference/templates.md に従います。それぞれ、書き込む前にドラフトで確認します。

レビュアーの足場設定：ユーザーが指定したレビュアーのうち、まだインストールされていないものそれぞれについて、また reviewer-scaffolding を指定するセットアップセクションの再実行時は、reference/reviewers.md に従います。

置き換え対象の Ship スクリプト（リポジトリの移行時）：ステップ 3 で記録したものを一覧にして、削除案を提示し、承認後に削除します。local-gate.sh、live-e2e、copilot-pr-review-loop、および ## Cloud lane の Bootstrap: に指定されている cloud-ship-bootstrap.sh は残します。

6. 書き込み、検証する

確認済みのファイルをすべて書き込みます。その後、新しいプロファイルに対して Ship の事前チェックを実行します。

.claude/skills/ship/scripts/preflight.sh none

その reasons を報告します。イシューを指定しない呼び出しでは独自の理由は発生しないため、リストは空になるはずです。profile missing、profile invalid、skill missing、skill off pin、skills lock unreadable、または composes pin invalid のいずれかがあれば、終了前に修正してください。最後の理由の場合は、インストール済みの ship コピーが不正なため、更新コマンドを再実行します。skill missing または skill off pin の理由には、ステップ 1 で未インストール、または固定バージョンから外れている合成スキルのステップと、そのインストールコマンドが示されます。そのコマンドを実行してください。skills lock unreadable の理由は、インストールコマンドより前に発生します。skills CLI は解析できないロックファイルを新しいエントリだけを保持する形で書き換えるため、まず JSON を修復してください。

Ship は、許可ルールに一致する相対パスで merge を呼び出します。そのため、リポジトリの .claude/settings.local.json の permissions.allow に Bash(.claude/skills/ship/scripts/merge.sh:*) を追加するよう伝えてください。このルールがないと、自動モードでマージが拒否される場合があります。

7. 完了

ユーザーに次のように伝えます。プロファイルは docs/agents/ship.md にあり、最初の /ship <issue> を実行できます。また、cloud-ship がインストールされています。このリポジトリでクラウドルーチンを実行すると、1 行のプロンプト Run the cloud-ship skill. で起動します（イシューはルーチン自身が選択するため、プロンプトにリポジトリ名は含めません）。ルーチン自体はオペレーターごとのスケジュールであり、ここでは作成しません。後から docs/agents/ship.md を直接編集できます。

再実行

プロファイルの再実行はプロファイルが存在する場合に、セットアップセクションの再実行は更新時にテンプレートが移動したセットアップセクションが指定された場合に、それぞれ reference/re-run.md の各段落に従って実行します。該当するケースをそれぞれ適用し、両方に該当する場合はプロファイルの再実行を先に行います。