initialise-skills

initialise-skills

共有エージェントスキル（changelog、send-it、cleanup-repo、linear-sync、triage-pr、…）が実行時に読み込む、スキルごとの config.json ファイルを作成し、正確な状態に保ちます。ホストリポジトリ内で実行すると、リポジトリの情報を検出し、インストール済みの各スキルの設定スキーマに対応付けて、正確な設定を書き込みます。人が意図的に設定した値を上書きすることはありません。

まずはドライランで、冪等性があります。最初に必ず差分をプレビューし、確認後にのみ書き込みます。新たに検出するものがない状態で再実行しても、すべてのファイルはバイト単位で変更されません。

書き込み内容の決定方法

インストール済みの各スキルについて、スキル独自の config.example.json（調整対象となるキーの一覧を定義）と既存の config.json（新規インストール時は存在しない場合があります）の2つを読み込みます。各キーは、サンプルのプレースホルダー、既存の値、検出された値を比較して、次のいずれかに分類されます。

ステータス	意味	動作
inferred	まだ値がない、またはサンプルのプレースホルダーのまま	検出された値を書き込みます
unchanged	既存の値が検出結果と一致	何もしません
drift	実際の値が検出結果と異なる — 意図的な編集	そのまま保持し、両方の値を報告します
needs-manual-input	検出方法がなく、値もない（例：MCP がない状態での Linear スラッグ）	入力できるよう、そのまま残します
manual-kept	検出方法がない実際の値	そのまま保持します
unknown-kept	config.json にあるが、どのスキルテンプレートにもないキー	変更せず、そのまま保持します

検出はスキルではなく、設定のキー名に基づきます。そのため、同じキーを使うすべてのスキルで1つの検出方法を共有できます（baseBranch の検出方法は changelog と send-it を、issueKeys の検出方法は changelog、cleanup-repo、linear-sync を対象にします）。キーの一覧、検出元、フォールバックについては、references/detectable-keys.md を参照してください。Changelog のモノレポ判定（affectedPackages / packageRoots）と、ホストを単一パッケージ構成とモノレポ構成の間で切り替える方法については、references/monorepo-config.md を参照してください。

preflight は意図的に対象外です。ベースブランチとワークスペースを自動検出し、リポジトリルートにある 任意の preflight.config.json を読み込むため、バンドル内の config.json にこのスキルが設定する項目はありません。（このスキルとの関連は、以下の .gitignore の処理のみです。preflight がインストールされている場合、スクラッチ出力の .preflight-summary.json がリポジトリの .gitignore に追加されます。）

.gitignore の処理

ホストリポジトリのルート .gitignore を調整する処理が2つあります。

1. Preflight のスクラッチファイル（A-569）。 preflight スキルは、実際の実行のたびにリポジトリルートへ .preflight-summary.json を書き込むため、無視ルールがないと /send-it の実行後に未追跡の変更として表示されます。preflight がインストールされている場合、このスキルはホストリポジトリのルート .gitignore でこのファイルが除外されるようにします。変更は追記のみで冪等です。コメント付きのエントリがない場合にのみ追加し（.gitignore がなければ作成）、このエントリに関する既存行の並べ替えや削除は行いません。

2. スキル設定の無視ルールの削除（A-812）。 一部の利用者（特に A-812 の修正前に npm-package-template から生成されたリポジトリ）は、誤って .claude/skills/*/config.json と .agents/skills/*/config.json を gitignore に追加しています。このパターンが正しいのは、agent-skills のソースリポジトリ（skills/*/config.json、A-615 — skills add --copy で ACME の識別情報がベンダー化されないようにするため）と、テンプレートのシード用ガードだけです。利用側のリポジトリでは、解決済みの config.json をコミットする必要があります。このスキルは、誤った利用側のパターン（および付随するコメントブロック）を削除し、CI や新規クローンで実行可能な設定を読み込めるようにします。ソースリポジトリの skills/*/config.json ルールには触れません。

ドライランのレポートには、保留中の変更（will add … / will strip …）が表示されます。書き込み後に再実行すると、already ignored / no erroneous skill-config ignore rules と表示されます。

skills.lock のステップ

設定の調整に加えて、このスキルはリポジトリのルートにコミット済みの .claude/skills.lock を出力します。これは、インストールされているスキルのバージョンとその入手元を記録した、 機械可読な一覧です。

{ "source": "https://github.com/rheged-studio/agent-skills", "ref": "main",
  "skills": { "changelog": "1.2.0", "send-it": "2.1.3", "…": "…" } }

• skills — インストール済みのすべてのバンドル（preflight とこのスキルを含む）の完全な一覧です。各 SKILL.md の metadata.version を読み取ります。キーはソートされるため、 バージョンに変更がない状態で再実行してもバイト単位で安定した処理となり、実際にバージョンが変わった場合にのみファイルが書き換えられます。バンドルをどこに配置したか（skills/、.claude/skills/、 .agents/skills/）にかかわらず、ロックは固定パス .claude/skills.lock に保存され、利用側はこれをコミットします。
• source / ref — スクリプトでは導出できない出所情報です（skills.sh は、利用側がどこからインストールしたかを記録しません）。書き込みステップの stdin で facts.lockSource / facts.lockRef として指定してください（ステップ 2 を参照）。省略した場合、既存のロックの値は保持されます。どちらも指定されていない場合は、フィールドに null が書き込まれ、レポートでその旨が通知されます（source/ref not supplied）。値を捏造することはありません。

これは、更新が必要なリポジトリを検出するための基盤です。詳しくは、以下の 更新の確認を参照してください。

プロセス

1. ドライラン。 ホストリポジトリのルートから、同梱スクリプトを実行して機械可読なプレビューを表示します。

   node <skills-dir>/initialise-skills/scripts/initialise.mjs --dry-run --json
   

   <skills-dir> は、バンドルがインストールされている場所です（例：skills/、 .claude/skills/、.agents/skills/）。スクリプトは自身の場所を基準に兄弟ディレクトリを自動検出するため、通常はリポジトリのルートから実行するだけでかまいません。JSON を解析してください。各キーの status を含む skills[] と、driftKeys、 manualKeys、totals が出力されます。

2. 情報を補完する。 needs-manual-input の Linear キー（linearTeamName、 linearWorkspaceSlug、および capture が有効な場合の followUpProject）ごとに、Linear MCP が利用可能であれば、Linear MCP 経由で値を取得してください。 チーム名には mcp__linear-server__list_teams を、プロジェクト名にはフォールバック用の全件受け皿プロジェクトを取得するため mcp__linear-server__list_projects を使用します（Rheged estate：Follow-up issues。リポジトリごとのホームプロジェクトではありません。triage-pr は可能な場合、PR の現在の Linear プロジェクトを引き継ぎます。A-1541）。ワークスペースのスラッグはチームまたは組織から取得します。利用できない場合は、ユーザーに確認してください。取得した値を facts オブジェクトにまとめます。また、ここにロックの出所情報も追加します。lockSource（スキルのインストール元であるソースリポジトリの URL。agent-skills リポジトリの URL）と、lockRef（インストール元の ref。タグや SHA を指定していない場合は、フリートの規約に従いデフォルトで main）です。既存の .claude/skills.lock に記録されている場合は、その値が保持されるため、どちらも指定しないでください。

3. 差分を提示して確認する。 人が読めるレポートを表示します（--json なしで再実行するか、解析済みの JSON を表示します）。書き込まれる inferred キー、保持される drift キー、および needs-manual-input キーを明示してください。 各 drift キーについて、検出された値を受け入れるか確認してください（キーごとのオプトイン）。受け入れたキーを、たとえば { "changelog": ["issueKeys"] } のように、スキル名をキーとする acceptDrift マップにまとめます。これが確認のゲートです。確認前に書き込んではいけません。

4. 書き込み。 --write を指定して再実行し、収集した facts と drift のオプトインを stdin の JSON としてパイプで渡します。

   echo '{"facts":{"linearTeamName":"…","linearWorkspaceSlug":"…","followUpProject":"…","lockSource":"https://github.com/rheged-studio/agent-skills","lockRef":"main"},"acceptDrift":{"changelog":["issueKeys"]}}' \
     | node <skills-dir>/initialise-skills/scripts/initialise.mjs --write --json
   

   返された totals に基づいて書き込まれた内容を報告し、さらに gitignore フィールドの status（added、created、present、negated のいずれか。preflight がインストールされていない場合は .gitignore のステップがスキップされるため、このフィールド自体がありません）と、lock フィールドの status（written、unchanged、would-write のいずれか）も報告してください。needsFacts: true は、lockSource / lockRef の指定がまだ必要であることを意味します。

5. 冪等性を確認します。 ドライランをもう一度実行します。残すことにした差分や、まだ不足している手動設定値を除き、すべてのキーが unchanged になっているはずです。preflight がインストールされている場合、gitignore.status は present になります（リポジトリで意図的にファイルの無視を解除している場合は negated です。これも安定した no-op です）。インストールされていない場合は、.gitignore の手順がスキップされ、確認する gitignore フィールドはありません。 lock.status は unchanged になります。これにより、設定ファイル、.gitignore、skills.lock が安定しており、 今後再実行しても no-op になることを確認できます。

6. GitHub App とトークンの確認。 このリポジトリで共有の Claude ワークフロー （reusable-claude*.yml と、それを呼び出すスタブ）を実行する場合は、GitHub App をインストールし、 リポジトリの Actions シークレットに CLAUDE_CODE_OAUTH_TOKEN を設定する必要があります。ワークフローは このトークンで認証し、空のトークンでは失敗します（A-646）。必要なシークレットは ANTHROPIC_API_KEY ではなく、CLAUDE_CODE_OAUTH_TOKEN です。

   シークレットの有無を調べます（ベストエフォートで行い、gh が利用できない場合や未認証の場合は黙ってスキップします。Claude ワークフローを実行しないリポジトリでは、どちらも不要です）。一覧の取得と名前の確認は、別々の 2 つの手順として実行し、それぞれの結果を確認してください。gh … | grep のようなパイプにまとめてはいけません。gh のエラーと実際にシークレットがない場合が同じ結果になり、確認できなかったケースが見えなくなるためです。

   # step 1 — list the repo's Actions secrets; a non-zero exit here is "can't verify"
   gh secret list --repo <owner>/<repo> --app actions
   # step 2 — only when step 1 succeeded, check whether the name is in that output
   

   • 存在する（手順 1 が成功し、一覧に名前がある）→ OK と報告します。対応は不要です。
   • 存在しない（手順 1 は成功したものの、名前がない）→ 警告し、オペレーターに /install-github-app を実行するよう伝えます。App をインストールし、シークレットを追加できます。
   • 確認できない（手順 1 自体がエラーになる。例：リポジトリ管理者スコープがない状態での 403、または gh が未インストール）→ 「トークンを確認できませんでした。CLAUDE_CODE_OAUTH_TOKEN が設定されていることを手動で確認してください」と伝え、実行をブロックしたり失敗させたりしてはいけません。確認できないことは、存在しないことを意味しません。

   App 自身のトークンがなければ、App のインストール状況を確実に調べることはできません。そのため、シークレットの有無を信頼できる代替指標とします。/install-github-app を案内することで、App のインストールとシークレットの設定をまとめて行えます。

7. 複数バンドルのリポジトリ — 手動の手順が 1 つあります。 このリポジトリ自体が、個別にバージョン管理される複数のスキルバンドルを提供している場合、send-it の bundleVersioning は自動では書き込まれません（send-it の config.example.json のキー一覧に含まれていないため、検出時に設定できません）。バンドルごとのバージョン更新チェックを有効にするには、手動で send-it/config.json に { "root": "<bundle-dir>", "manifest": "package.json", "skillFile": "SKILL.md" } を追加します。単一パッケージのリポジトリでは、この手順は不要です。

既存の設定を確認する

リポジトリのスキルに現在どのような設定が適用されているかを、調整や書き込みをせずに確認するには、読み取り専用のレビューを実行します。

node <skills-dir>/initialise-skills/scripts/initialise.mjs --review

インストール済みの各スキルについて、完全な config.json が出力されます。各キーの現在の値、分類（inferred／unchanged／drift／manual-kept／ needs-manual-input／unknown-kept — 上の表を参照）、キーの内容と値の取得元を説明する 1 行の説明が表示されます。説明は references/detectable-keys.md に基づいています。利用側で設定され、スキルテンプレートが認識しないキーは unknown-kept（そのまま保持され、説明はありません）として表示されます。また、まだ config.json にないテンプレートのキーは — not set と表示されるため、このレビューではドライランで表示される未適用の差分だけでなく、全体を確認できます。人向けのテキストには、各キーの used by … — <detection source> 行が表示されます。また、未設定のキーについては、設定されるまで適用される fallback: の既定値も表示されます（設定済みのキーでは、現在の値で適用内容がわかるため省略されます）。--json を追加すると、機械可読形式（skills[] 配列に { key, value, isSet, status, usedBy, detectionSource, fallback } の各エントリと totals を含む形式）で出力されます。ディスクへの書き込みは行わず、.gitignore の手順もスキップします。

後から設定を変更する

利用者の config.json が作成された後は、手動で編集して設定を変更する方法もサポートされています。変更のたびにこのスキルを使う必要はありません。skills/<name>/config.json（またはバンドルをベンダーとして配置した場所）を開き、値を変更して保存してください。これは利用者が所有する実ファイルであり、共有スキルは実行時にその内容を読み込みます。

このような手動編集は、今後の initialise-skills の再実行後も保持されます。次回の実行時、調整処理はその値を drift、つまり検出で得られる値とは異なる実際の値として分類し、保持したうえで、保持された値と検出された値の両方を報告します（上記のステータス表を参照）。値が黙って上書きされることはありません。drift が置き換えられるのは、キーごとの acceptDrift ゲートを手順 3 で明示的に有効にした場合だけです。つまり、意図的な手動編集と検出された事実は共存します。このツールは、手動で設定した値を上書きせずに、検出可能な事実を調整します。

同じ変更をツール経由で行いたい場合は、以下の --set <skill>.<key>=<value> をおすすめします。スキルの config.example.json に照らしてキーを検証し、キーの順序と書式を維持します。ただし、ファイルを直接編集する方法も同様に有効で安全です。

任意の値を設定する

検出、標準入力の facts、および acceptDrift を組み合わせれば、スクリプトが導出または受け入れられる値はすべて扱えます。ただし、単に自分で_選びたい_値（デフォルト以外のベースブランチ、独自の変更履歴ディレクトリ、ブール値の切り替えなど）は対象外です。そのような場合は、--set <skill>.<key>=<value> を使うと、指定したスキルの config.json に任意の値を直接書き込めます。

# dry-run first (default) — preview the change, write nothing
node <skills-dir>/initialise-skills/scripts/initialise.mjs \
  --set changelog.baseBranch=develop \
  --set changelog.affectedPackages=false

# re-run with --write to apply
node <skills-dir>/initialise-skills/scripts/initialise.mjs \
  --set changelog.baseBranch=develop --write

このフラグは繰り返し指定可能で、指定先は <skill>.<key> です。スキルのバンドルディレクトリ名に続けて、トップレベルのキーを指定します。値は JSON として解析され（true、42、["A"] などは正しい型で処理されます）、有効な JSON でない場合はプレーンな文字列として扱われます（そのため、develop は "develop" のままになります）。書き込みを始める前に、値はあらかじめ検証されます。スキルがインストール済みであること、キーがそのスキルの config.example.json に存在すること（未知のキーは拒否され、黙って作成されることはありません）、値の型がそのキーの例のプレースホルダーと一致すること（文字列をブール値フィールドに設定することはできません）が必要です。いずれかの条件を満たさない場合は、終了コードがゼロ以外となり、何も変更されません。

--set は通常の調整処理に組み込まれます。検出は引き続き実行され、指定した値はその上に重ねられるため、同じキーについて検出器が生成する値より優先されます。また、同じマージ／シリアライズ処理を通るため、キーの順序と書式が維持され、同じ値で再実行しても変更はありません。これは書き込みモードなので、読み取り専用の --review と併用できません。レポートでは、設定したキーは set to <value> (was <old>) と表示されます。

フラグ

• --dry-run（デフォルト）— 検出、マージ、報告を行います。書き込みは行いません。
• --write — 各スキルの config.json に調整を適用します。
• --review — 読み取り専用です。 インストール済みの各スキルについて、現在の設定全体を出力します。 各キーの現在値、分類（同じ6つのステータス）、および references/detectable-keys.md を参照した簡単な説明を表示します。dry-runとは異なり、テンプレートが把握していない unknown-kept キーも含め、すべてのキーの現在値を表示するため、保留中の差分だけでなく、全体像を確認できます。書き込みは行わず、.gitignore の処理もスキップします。 既存の設定を確認するを参照してください。
• --set <skill>.<key>=<value> — 繰り返し指定できます。 指定したスキルの config.json に任意の値（検出では生成されない値）を書き込みます。キーはそのスキルの config.example.json に存在する必要があり、値の型はプレースホルダーと一致していなければなりません。そうでない場合は拒否されます。通常の調整処理（最初にdry-runを行い、適用するには --write を指定）に組み込まれ、該当キーの検出結果を上書きします。--review とは併用できません。任意の値を設定するを参照してください。
• --json — 機械可読なレポートを出力します（ステップ2～3の実行や、--review のスナップショットの取得に使用します）。それ以外の場合は人間向けのテキストを出力します。
• --repo-root <path> — 検出処理がスキャンするホストリポジトリ（デフォルト：cwd）。
• --skills-dir <path> — 同階層のバンドルが配置されている場所（デフォルト：このスクリプトからの相対位置を自動検出）。
• stdin JSON — { "facts": { … }, "acceptDrift": { "<skill>": ["<key>"] } }。stdinがパイプで渡された場合（TTYではない場合）に読み取ります。acceptDrift のキーには、スキル名（"changelog"）またはリポジトリ相対の設定パス （"skills/changelog/config.json"）を指定できます。値はキー名の配列です。facts にはロックの由来情報 lockSource / lockRef も含まれます（ステップ2を参照）。

更新の確認

インストール済みスキルのうち、ソースリポジトリより古いものを確認するには、ソースのチェックアウトに対してバンドルされている check-updates.mjs を実行します（利用側には古いベンダーコピーのみがあるため、対象バージョンはソースから取得します）。

node <skills-dir>/initialise-skills/scripts/check-updates.mjs \
  --source <path-to-agent-skills-checkout> [--ref <tag-or-sha>] [--json]

利用側の .claude/skills.lock とソースのバンドルバージョンを比較します。--ref が指定されている場合は（git show を介して）その参照先と比較し、指定されていない場合はソースの作業ツリーと比較します。スキルごとの更新一覧として、updates（古いもの — 対応が必要な一覧）、added（上流で新しく追加されたスキル）、removed、downgrades（利用側のほうが新しい）、upToDate を出力します。 --lock <path> を指定すると、特定の利用側ロックファイルを対象にできます（デフォルト：<cwd>/.claude/skills.lock）。これにより、フリートオーケストレーターはディレクトリを変更せずに任意のリポジトリを確認できます。ロックスキーマについては、references/skills-lock.md を参照してください。

安全性

• まずドライランを行い、確認後にのみ書き込みます。 ユーザーの許可を得たうえで、明示的な --write パスを実行しない限り、何も書き込まれません。
• 意図的な編集を上書きしません。 キーごとに明示的に許可しない限り、差分は保持されます。
• 削除も並べ替えもしません。 既存のキーは順序を維持し、変更されたキーのみを更新します。利用者が追加したキーには手を加えません。既存の config.json の形式が不正な場合はスキップされます（報告されますが、上書きはされません）。
• .gitignore の編集範囲は限定されています。 スキルの config.json 以外では、このスキルはリポジトリのルートにある .gitignore を操作して、（1）.preflight-summary.json がなければ追記します（A-569 — この項目の既存行を並べ替えたり削除したりすることはありません）。（2）解決済みの config.json を利用者がコミットできなくなる、誤った .claude／.agents のスキル設定用 ignore パターンを取り除きます（A-812）。 エージェントスキルのソースルールである skills/*/config.json には手を加えません。
• skills.lock の書き込みは決定的で、バイト単位で安定しています。 config.json 以外で操作するもう一つのファイルは .claude/skills.lock です。キーをソートし、タイムスタンプを含めずに全体を再生成するため、バージョンが実際に変わった場合にのみ書き換えられ、変更のない実行ではバイト単位で同一のままです。既存のロックファイルの source／ref は保持し、捏造することはありません。
• GitHub App／トークンの確認は読み取り専用です。 gh secret list が返すのはシークレットの名前のみで、値は返しません。また、このスキルは GitHub への書き込みを一切行いません。シークレットが存在しない場合、または確認できない場合は、リマインダーを表示するだけです。

前提条件

• 設定を入力したいスキルが、このスキルと同じ場所にインストールされていること。
• ベースブランチ／Issue キーを完全に検出するには、origin リモートを持つ Git リポジトリが必要です（ない場合も、どちらも適切な代替手段に切り替わります）。
• チーム名／ワークスペースのスラッグを取得するには Linear MCP サーバーが必要です（任意 — これがない場合、この2つのキーは手動入力が必要な項目としてマークされます）。
• repo-admin スコープで認証された gh CLI があれば、GitHub App／トークンの確認（手順6）が可能です。そのスコープがない場合（または gh 自体がない場合）、シークレット一覧を読み取れないため、「確認できませんでした — CLAUDE_CODE_OAUTH_TOKEN を手動で確認してください」というメモに切り替わります。これは確認できない状態であり、失敗ではありません。テキスト形式の /install-github-app リマインダーは別の不在時の結果であり、確認に成功してシークレットが実際に存在しないと判明した場合にのみ表示されます。いずれの場合も、スキルは引き続き完全に実行されます。