skill-sync: Sync Installed Skills

# skill-sync: 導入済みスキルの一覧と更新 > **skill version**: 1.5.0 セッション内で初めて本スキルを使用するときは「skill-sync スキル v1.5.0 を使用します」と宣言する。 同じスキルを複数のコーディングエージェントへ配っていると、どこにどの版が入っているかが分からなくなり、 一部だけ古いまま放置される。本スキルは**導入済みスキルの版を一覧し、配布元の最新版と突き合わせ、 ユーザーが選んだ対象だけを更新する**ための手順書である。 **このスキルは利用者のホームディレクトリ配下に書き込む。**したがって **更新の適用はユーザーの承認を得てから行う**。承認なしにファイルを置き換えてはならない。 ## 書き込みの範囲（最優先の制約） **本スキルが書き込むのは、本スキルを実行しているエージェント自身のコンフィグディレクトリ配下に限る。** それ以外の場所への書き込みは、**ユーザーが明示的にその場所を指示した場合を除き、行ってはならない。** 本スキルが使う**必要・不要の設定ファイル**（後述の `skill-sync.json`）も、自エージェントのコンフィグディレクトリ直下に置く。 したがって設定の読み書きもこの範囲の内側で行う。 他のエージェントのスキルが古いと分かっても、**こちらから書き換えない**。 別のエージェントの設定を勝手に触ることは、利用者が本スキルに委ねた範囲を超える。 更新が必要なら、**そのエージェント上で本スキルを実行してもらう**。 自分がどのエージェントとして動いているかが判別できない場合は、**書き込まない**。 判別できない旨を伝え、以降の適用はユーザーの指示を待つ。 ## 前提と一般化ルール - **エージェントの種類をハードコードしない。** 後述の「既知のエージェント」表は*データ*であり、 手順そのものは表に無いエージェントにも通用する形で書いてある。表に載っていないエージェントを 使っている場合は、汎用探索（手順2）で拾う。 - スキルの版は `SKILL.md` の frontmatter の `metadata.version` に入っている。 **これが無いスキルは「版不明」として扱い、エラーにしない**。古い配布物には版が入っていない （外部由来スキルは除く。手順3の「外部由来スキルの照合」で判定する）。 - 収録スキル（配布元の `index.json` に載るスキル）の配布元は `index.json` という1ファイルで表現される。**どの URL を使うかは手順1で決める。** 下記は**既定値**であり、**利用者の設定があればそちらが優先する**。 ``` https://raw.githubusercontent.com/xhighhongo41/agent-skills/main/skills/index.json ``` - **外部由来スキル**（他者のリポジトリから `register-external-skill` で取り込んだもの）は、`SKILL.md` の frontmatter の `metadata` にある `origin` 系のキー（`origin` / `origin-path` / `origin-ref` / `origin-commit` / `origin-digest` / `origin-fetched`）が 導入元を表す。**配布元の `index.json` には載らず、版も無いことがある**ので、本スキルは導入元から直接取得し、 本文の要約値で更新を判定する（手順3の「外部由来スキルの照合」）。由来キーは register-external-skill が書き、本スキルは読んで更新する。 - **スキルには対象エージェントが決まっているものがある。** `SKILL.md` の frontmatter の `compatibility` に対象が列挙されており、**このキーが無いスキルは全エージェント向け**である。 対象外のスキルを入れても多くのエージェントは黙って読み込んでしまうため、 **気づかないまま使えないスキルが混ざる**。これを防ぐのも本スキルの役目である。 - **判定と適用を混ぜない。** まず全体を一覧して見せ、対象を選ばせ、承認を取ってから書き込む。 - **版が一致していても内容が違うことがある**（手元で改造した、配布元が版を上げずに直した）。 本スキルは版に加えて**内容も照合する**（手順3の「内容の照合」）。 - **必要・不要の設定はエージェントごとに持つ。** 実行中のエージェントの設定ファイルだけを読み書きし（手順2の末尾）、 どのスキルを導入候補に出すか・更新候補から外すかに使う（手順3・4）。**設定は本スキルの提案にだけ効く。** 配布経路の機構（例: OpenCode の `skills.urls` による自動取得）が取ってくるものは止められないので、 不要と設定したスキルが配布キャッシュに現れても異常ではない。 ## 手順 ### 1. 配布元を決めて最新版を取得する **まず、配布元の URL を利用者の設定から読む。** リモートから自動でスキルを取得する仕組みを持つ エージェントは、**その取得元を自分の設定ファイルに書いている**（表の下の「配布元の設定の在処」）。 **そこに URL があればそれが正であり、既定値より優先する。** 設定を持たないエージェント、 または設定が見つからない場合は既定値を使う。 **どちらの URL と比較したかを一覧に明示する。** ここを取り違えると、**比較の基準が実際の配布元とずれる**。 機構が取得したキャッシュは利用者の設定した配布元から来ているので、既定値と突き合わせると 「ローカルが新しい」「配布元に無い」といった**誤った状態が一覧に並ぶ**。 どちらを見たかが書いてあれば、利用者はその食い違いに気づける。 決まった URL の `index.json` を取得し、`skills[]` の各要素から `name` / `version` / `files` / `compatibility` を読む。 `files` はスキルフォルダ内の全ファイルの相対パスであり、**更新時に取得すべきファイルの一覧そのもの**である。 各ファイルの取得先は `{index.json を置いている URL のディレクトリ}/{name}/{files の各パス}` で決まる。 **`compatibility` があれば、そのスキルは列挙されたエージェント専用**である。無ければ全エージェント向けとして扱う。 配布元によってはこの値を持たないことがある（古い配布物や、別の生成規則を採る配布元）。 その場合は**手順5で取得する `SKILL.md` の frontmatter から読む**ので、ここで欠けていてもエラーにしない。 取得に失敗した場合（オフライン、URL 誤り、配布元の障害）は**そこで止めない**。 「配布元に接続できなかった」と明示したうえで、手順2〜3のローカル一覧までを実行して報告する。 その状態では更新の要否は判定できないので、**更新の適用には進まない**。 **外部由来スキルの取得は手順3で導入元ごとに行う**（`index.json` には載らないため、ここでは扱わない）。 ### 2. 導入済みスキルを走査する **まず、本スキルを実行しているエージェント自身のコンフィグディレクトリを走査する。** これは更新の対象になりうる唯一の場所であり、ここを見ないと本スキルは目的を果たせない。 あるエージェントのスキルの置き場所は、次の順で決める。 1. **環境変数による上書きを最優先する。** 表の「環境変数による上書き」欄の変数が設定されていればそちらを使う。 2. 「既知のエージェント」表のパスを引く。 3. **表に無いエージェント、または表のパスが存在しない場合は汎用則で探す。** ほとんどのエージェントはスキルを `<そのエージェントの設定ディレクトリ>/skills/<スキル名>/SKILL.md` に置く（`skills` が単数形 `skill` の実装もある）。設定ディレクトリの場所は そのエージェントの文書か、ホーム直下のドットディレクトリから判断する。 見つけた各ディレクトリの直下を1階層だけ列挙し、`<スキル名>/SKILL.md` があるものをスキルとみなす。 `SKILL.md` から frontmatter の `name` と `metadata.version` と `compatibility`、および `metadata` の `origin` 系のキーを読む。 **`origin` があれば「外部由来」の印を付け、配布元の一覧と同名でも収録スキルとしては扱わない**（外部由来を優先する）。 同名の収録スキルは「未導入」にせず「外部由来が同名で導入済み」として候補に出さない（入れ替えたいときは `remove-skill` で消してから導入する）。 **互換読み込みで見えるディレクトリも走査する。** エージェントによっては、自分の置き場に加えて **他のエージェントの置き場も読む**（「既知のエージェント」表の下の「互換読み込み」）。そこにあるスキルは **実行中のエージェントから既に使える**。ここを見ないと、**既に使えるスキルを「未導入」と表示して、 利用者に二重導入させてしまう。** - **一覧には出すが、書き込まない**（「書き込んではいけない場所」を参照）。実体の持ち主が別のエージェントだからである。 - **どのエージェントの持ち物かが分かるように示す。**「自分から見えているが、実体は別のエージェントの ディレクトリにある」と伝われば、利用者は二重に入れずに済む。 **配布経路で取得したスキルも走査する。** エージェントが配布元から自動で取得したスキルは、 利用者が自分で置くディレクトリとは**別のキャッシュ**に入ることがある（表の「配布キャッシュ」欄）。 ここを見ないと、**配布経路で入ったスキルが一覧から丸ごと抜ける**。 - **一覧には出すが、更新の対象にはしない**（「書き込んではいけない場所」を参照）。 この領域はエージェントの機構が管理しており、手で書き換えても次の取得で置き換わる。 - キャッシュには**取得時の版を記録したファイル**が置かれることがある。 **記録された版と `SKILL.md` の `metadata.version` の両方を読み、食い違えば「版不明」として扱う。** 機構が自分で作る状態ではないため、手で上書きされた可能性を知らせる価値がある。 - **同じスキルがユーザースコープとキャッシュの両方にあれば、別行として両方出す。** 実体が別のファイルなので名寄せしない。どちらがエージェントに読まれるかは機構が決めるため、 **本スキルは「二重に存在する」ことを知らせるに留める。** 走査で守ること: - **エージェント本体が管理する領域は走査から除外する**（「書き込んではいけない場所」を参照）。 利用者のスキルではないため、一覧に出す意味がない。 - **同じ実体を二重に数えない。** 複数のエージェントが同じディレクトリを読む構成があるため （表の「互換読み込み」欄を参照）、実パスで名寄せする。 - プロジェクトスコープのスキル（作業中のリポジトリ配下）は、**ユーザースコープとは別行**として扱う。 リポジトリの持ち物なので、勝手に更新しない。 **必要・不要の設定を読む。** 走査が終わったら、**実行中のエージェントの設定ファイルを読む。** 置き場は「既知のエージェントのスキルディレクトリ」の節の**「必要・不要の設定ファイルの在処」の表で引く** （表に無いエージェントは、そのエージェントの設定ディレクトリ直下の `skill-sync.json`。環境変数による置き場の上書きに従う）。 **自分がどのエージェントとして動いているか判別できない場合は読まない**（「書き込みの範囲」と同じ理由。尋ねも書きもしない。 一覧の「設定」列は — になる）。設定ディレクトリそのものが無い場合も同じく読まず、置き場の判定を疑って知らせる（作らない）。 配布元に接続できなかったとき（手順1）は、設定を読んで示すだけにし、各スキルの判定も手順4の初期化・解消も行わない （配布元の一覧が無いと、どの名前が配布元に無いかも決められない）。 ファイルの形は次のとおり。厳格な JSON（コメント・末尾カンマ無し）で、`format` は常に `1`、 `skills` はスキル名（配布元の `name`）→ `true`（必要）／`false`（不要）の対応表である。 ```json { "format": 1, "skills": { "council": false, "python-coding": true } } ``` 読んだ結果を次の4つに区別し、手順3・4で使う。 - **設定なし**: ファイルが無い。手順4の冒頭で初期化する。 - **設定が読めない**: JSON として壊れている、`skills` が対応表でない、`format` が `1` 以外。**上書きしない。** ファイルのパスを添えて「設定が読めない」と知らせ、直すよう案内する。 その実行では設定なしと同様に一覧を出すが、**初期化の書き込みはしない**。 - **各スキルの設定値**: 配布元の一覧にある各スキルと外部由来スキルについて、**必要**（`true`）／**不要**（`false`）／ **未設定**（キーが無い、または真偽値でない）。未設定は手順4の冒頭で解消する。 - **配布元に無い設定**: 設定にはあるが配布元の一覧に無い名前。「配布元に無い設定」として知らせ、**消さない** （配布元の変更か綴りの違い。判断は利用者に委ねる）。**外部由来スキルの名前はここに含めない**（導入元があり、設定は同じ意味で効く）。 `format` と `skills` 以外のキーがあっても異常ではない。**読んだものは書き戻すときに保持する。** ### 3. 比較して一覧を提示する まず版を比べ、版が一致した行については**内容も照合する**（下の「内容の照合」）。 エージェント × スキルの表にして、状態を次の8種で示す。表には**「由来」列（収録／外部）**を置き、 外部由来の行は下の「外部由来スキルの照合」で判定する（状態語は同じ8種を使い、「備考」列で区別する。9番目の状態は作らない）。 | 状態 | 意味 | 既定の扱い | |---|---|---| | 最新 | ローカルと配布元の版が一致し、**内容も一致** | 何もしない | | 更新あり | 配布元の版が違う | **更新候補** | | 未導入 | 配布元にあり、**実行中のエージェントからはどこにも見えない**（自分の置き場・互換読み込み・配布キャッシュのいずれにも無い） | **導入候補**（設定が必要なら手順4で導入するかを確認する。不要なら候補に出さない。設定が無ければ従来どおりユーザーが望む場合のみ） | | 対象外 | `compatibility` に、実行中のエージェントが含まれない | **導入・更新の候補から外す。**理由を添えて一覧には出す | | 版不明 | ローカルに `metadata.version` が無い、または配布キャッシュの記録と食い違う | **更新候補**（古い配布物か、手で上書きされた可能性） | | ローカルが新しい | ローカルの版が配布元より進んでいる | **更新しない。** 手元で改造した可能性があるので必ず知らせる | | 内容が違う | 版は一致するが、`files` のいずれかの内容が配布元と違う、または欠けている | **既定では候補に入れない。** 違うファイル名と差分の規模を示し、含めるかを個別に確認する | | 配布元に無い | ローカル固有のスキル | 触らない | 配布元の版は**文字列として比較する**。大小関係の判定に頼らず、「一致しない＝更新候補」とする。 「ローカルが新しい」の判定だけは版番号を数値として読み、判断がつかなければ「版が食い違う」と報告する。 **設定の列。** 一覧に「設定」の列を置き、手順2の末尾で読んだ値を 必要／不要／未設定／— （設定なし・設定が読めない・自エージェントを判別できない・配布元に無いローカル固有のスキル）で示す。 - **不要かつ未導入**の行は本表から外し、表の下に「設定で不要: `a`, `b`, `c`（3件）」と1行でまとめる。**議論しない。** 名前は出すので、見直したいときに気づける。 - **不要かつ導入済み**の行は本表に出す。状態（最新・更新あり・内容が違う等）は従来どおり付ける。既定の扱いは手順4。 - **「対象外」は設定より優先する。** 設定が必要でも、対象外なら対象外として扱う（下の「対象エージェントの判定」）。 - 設定は状態ではない。8種の状態の意味は設定によって変わらない。 **内容の照合。** 版が配布元と一致した行すべて（自分の置き場・互換読み込みで見える場所・配布キャッシュ・プロジェクトスコープ）が対象である。 それ以外の行は照合しない（既に別の状態が付いており、「更新あり」は取り直しで解消する）。 候補にできない場所の行（「書き込みの範囲」）も照合するが、結果は知らせるに留める。 - 配布元から、そのスキルの `files` に挙がる**全ファイル**を取得する。**手順5と同じ取得手段を使う。** 内容をそのまま得られる手段でなければ比較にならない（要約や整形を挟む取得手段は使わない）。 配布元側の取得はスキルごとに1回でよい（同じスキルが複数の行にあっても取り直さない）。 手元側は、その行のスキルフォルダから同じ相対パスのファイルを読む。 - ファイルごとに、**改行コードと末尾の改行の有無を揃えてから**、内容の要約値（ハッシュ）または全文で比べる。 それ以外の違いはすべて「違う」とする。 - **1ファイルでも違えば、または `files` にあるファイルが手元に無ければ「内容が違う」**。 手元にあって `files` に無いファイルは、ここでは見ない（手順5で消さずに報告する）。 - `files` を持たない配布元（古い配布物）は `SKILL.md` だけ比べ、その旨を添える。 - 配布元に接続できないときは照合しない（手順1のとおり、更新の要否は判定できない）。 一部のファイルだけ取得できなかったときは、その行を「最新」とせず、**版は一致するが内容は未照合**と示し、 取得できなかったファイル名を添える。 - 一覧には**違うファイル名と差分の規模**（違う行数の目安）を添える。 **外部由来スキルの照合。** `origin` を持つ行が対象（「由来」列は「外部」）。導入元ごとに一時ディレクトリへ浅く取得し （`git clone --depth 1 [--branch <origin-ref>] <origin> <一時ディレクトリ>`。一時ディレクトリは作業中のリポジトリの外に置き、終了時に削除する。 配置ではないので「書き込みの範囲」の対象外。`origin` と `origin-ref` の組が同じ導入元は1回でよい。ローカルパスも同じ）、`origin-path` の `SKILL.md` を読む。 配布元の `index.json` に接続できなくても、外部由来の照合は導入元ごとに行う。判定は上から順に当てる。 1. 取得できない、または取得できたが `origin-path` に `SKILL.md` が無い → 状態を付けず、備考に「未照合」（後者は「上流に無い」）と書く（更新の要否は判定できない。手順4の候補にも入れない）。 2. 上流の `metadata.version` があり、手元の版と違う → **更新あり**。 3. 本文の要約値を3つ比べる: 記録 S（`origin-digest`）、手元 L（手元の本文から計算）、上流 U（上流の本文から計算）。 本文は閉じ `---` の次の行以降（frontmatter が無ければ全文）、改行を LF に揃え、末尾の改行を1つにした UTF-8 の SHA-256（16進は小文字）で、`sha256:` を前に付けて表す。 **register-external-skill の「要約値の計算」と同じ規則であり、直すときは両方を同時に直す。** - L=S かつ U=S → **最新** - L=S かつ U≠S → **更新あり**（備考「本文差分」） - L≠S かつ U=S → **内容が違う**（備考「ローカル改変」。更新しない） - L≠S かつ U≠S → **内容が違う**（備考「競合」。更新しない。差分の規模を添える） `origin-digest` が無い行は S が無いので L と U だけを比べ、同じなら「最新」、違えば「内容が違う」（いずれも備考「記録なし」）とし、更新を1度適用して記録を補うよう案内する。 **frontmatter は比べない。** 手元の frontmatter は取り込み時に補われていることがあり、含めると常に「違う」になる。 「配布元に無い」は外部由来の行には付けない（導入元がある）。 **対象エージェントの判定。** `compatibility` に実行中のエージェントが含まれるかどうかで決める。 自分がどのエージェントとして動いているかは、「既知のエージェント」表の `compatibility` の値の列で引く。 外部由来スキルの `compatibility` が表の語彙に一致しない自由文なら、判定せず表示に留める（対象外と決めつけない）。 - **「対象外」は他の状態より優先する。** 版が古かろうと新しかろうと、対象でないなら更新も導入もしない。 - **対応付けができない場合は判定しない。** 表に無いエージェントで動いている、あるいは自分が どのエージェントか判別できない場合は、**対象外と決めつけず**、判定できない旨を示したうえで 導入候補から外し、判断を利用者に委ねる。誤って「対象外」と出すと、使えるはずのスキルを遠ざけてしまう。 - **既に導入済みのスキルが対象外だった場合は、勝手に消さずに知らせる。** 利用者が意図して置いた可能性がある。 ### 4. 導入・更新対象を選ぶ **黙って全件更新してはならない。** 一覧を見せたうえで、何を導入・更新するかを決めてもらう。 **設定の初期化と未設定の解消。** 候補を選ぶ前に、手順2の末尾で読んだ設定を整える。 **書き込み先は手順2で決めた設定ファイルのパス**で、必ず示す。 - **設定なし**（ファイルが無い）なら**初期化**する。配布元の一覧の各スキルと外部由来スキルについて提案値を決める: **対象外** → 不要（導入済みでも。対象外を優先する）、**導入済み**（手順2の3か所のいずれかに見える）→ 必要、**未導入** → 不要。 スキル名・根拠となる状態・提案値の表と書き込み先のパスを示し、**まとめて**修正と確認を受ける。 確認を得たら**1回で書く**（手順2の末尾の形式。`skills` のキーはアルファベット順、2スペースのインデント、末尾に改行）。 **表の確認が承認にあたる**ので、書く直前にもう一度は尋ねない。書く前に、書き込み先が自エージェントのコンフィグディレクトリ配下であることだけは確かめる（手順5と同じ確認）。 書いた後は、その設定に基づいて同じ実行の中で候補の選択に進む（既定の扱いは本手順の末尾の表）。 - **未設定のスキルがある**（キーが無い、または真偽値でない）なら、その件だけ同じ規則で提案し、確認して**書き足す** （真偽値でない値は、尋ねた答えの真偽値で正す）。他の項目と未知のキーは変えない。 - **設定が読めない**なら書かない（手順2の末尾）。**設定を読んでいない**（自エージェントを判別できない・配布元に接続できない）ときも書かない。 **更新の候補にできるのは、自エージェントのコンフィグディレクトリ配下にあるものだけ**である （「書き込みの範囲」を参照）。それ以外は一覧に出ていても候補から外し、 **そのエージェント上で本スキルを実行するよう案内する**。 呼び出し時の引数でスキル名やエージェント名が指定されていればそれを対象とする。 指定が無ければ候補を提示して選択を促す。選択の粒度は次の3つを受け付ける。 - **スキル単位**（例: あるスキルだけを全エージェントで更新する） - **エージェント単位**（例: あるエージェントだけを最新に揃える） - **その組み合わせ**、および「更新候補すべて」 「ローカルが新しい」ものは既定で対象から外す。**上書きするとユーザーの改造が消える**ため、 含めるかどうかを個別に確認する。 **「内容が違う」ものも既定で対象から外す**（「ローカルが新しい」と同じ）。含めるかは1件ずつ確認し、 確認のときに差分（または規模）を示す。上書きすると手元の変更が消える。 手元の改造を残したいなら、その改造を配布元へ反映して版を上げるよう案内する。 外部由来の「内容が違う」（ローカル改変・競合）も同じ扱いで、改造を残すなら導入元へ反映するよう案内する。 **「対象外」のものも既定で対象から外す。** 利用者が明示的に含めたいと言った場合は、 **そのエージェントでは動かない見込みであること**を伝えたうえで判断に従う。 配布側が対象を宣言しているだけで、実行を妨げる仕組みがあるわけではないため、 入れること自体は可能である。 **設定に基づく既定の扱い。** 引数または対話で名指しされたスキルは、設定にかかわらず対象にする（上の引数の規定のとおり）。 設定を直す（必要↔不要）のは、利用者がそう答えたときだけで、手順4のうちに書く（初期化・追記と同じ扱い）。 | 設定 | 未導入 | 導入済み | |---|---|---| | 必要 | **導入候補として「導入するか」を確認する。** 断られたら、設定を不要に直すかを尋ねる（直さなければ次回も確認が出る） | 従来どおり（更新あり等なら更新候補） | | 不要 | 候補に出さない（手順3の要約行のみ）。名指しされたら含め、設定を必要に直すかを尋ねる | **既定で候補から外す**（「対象外」と同じ扱い）。**削除しない**（削除は `remove-skill` で）。名指しされたら含める | | 未設定 | まず必要・不要を尋ねて書く（上記）。その答えで上の行へ | 同左 | ### 5. 更新を適用する **書き込む前に、書き込み先が自エージェントのコンフィグディレクトリ配下であることを確認する。** 範囲外のものが混じっていたら、**ユーザーがその場所を明示的に指示していない限り書き込まない**。 指示が無ければ、その1件を適用せずに「どこへ書けなかったか」を報告する。 この確認は、手順4で必要・不要の設定ファイル（`skill-sync.json`）を書くときにも同じように行う。 ただし下の「承認」はスキルの配置についてのものであり、設定の書き込みの承認は手順4の表の確認が担う（二重には求めない）。 **承認は、書き込みを始める直前に1度だけ求める。** 何をどこへ書くかを一覧で示してから尋ねる。 承認が得られたら、選ばれた対象の範囲内では**1件ずつ聞き直さずに最後まで実行してよい**。 対象1件ごとに次を行う。 1. 配布元から、そのスキルの `files` に挙がっている**全ファイル**を取得する。 `SKILL.md` だけでなく、付属のメタデータファイルや参照文書も含めて取得する。 **内容をそのまま得られる手段で取得する**（要約や整形を挟む取得手段は使わない。手順3の照合も同じ手段で行う）。 2. 取得がすべて成功してから配置する。**部分的に取得できた状態で書き始めない** （途中で失敗すると、中途半端に混ざったスキルフォルダが残る）。 3. **取得した `SKILL.md` の `compatibility` を、配布元の一覧の値と突き合わせる。** - **食い違っていたら、その1件は配置しない。** 両方の値を示してユーザーに確認を求める。 一覧は生成物であり、再生成漏れや配布元のブランチ違いで実体とずれることがある。 **ずれたまま書き込むと、対象外のスキルを入れてしまう。** - 一覧に `compatibility` が無かった場合は、**ここで読んだ値で判定する**。 その結果それが対象外と分かったら、**配置せずに知らせる**。 - **残りの対象は続けてよい。** 取得の失敗と違い、これは配置前に分かる食い違いである。 4. 配置先のスキルフォルダへ上書きする。 5. **配布元に無いファイルがフォルダに残っている場合は、消さずに報告する。** 利用者が意図して置いたファイルかもしれない。削除は別途確認を取る。 6. 配置後に `SKILL.md` を読み直し、`metadata.version` が配布元の版と一致することを確認する。 「内容が違う」で適用した件は版が元から一致しているので、手順3の照合をやり直して内容が一致することを確認する。 **外部由来スキルへの適用**（「由来」が外部の行）は、上の1〜6の代わりに次を行う。 1. 導入元から `origin-path` のディレクトリ全体を取得する（手順3と同じ取得手段。`.git` と `__pycache__` は除く）。すべて取得できてから配置する（上の 2 と同じ）。 2. 手元の `SKILL.md` の frontmatter から、取り込み時に補われたキー（`name` / `description` と `metadata` の全キー）を控える。 3. 本文を上流の本文に置き換える。frontmatter は、上流に frontmatter があればそれを基に、無ければ手元のものを基にして、 **`metadata` の `origin` 系キーを重ねる**。`name` は手元のもの（ディレクトリ名）を保つ。`description` は上流にあれば上流を採り、無ければ手元の補いを残す。 4. `origin-commit`（取得した HEAD）・`origin-digest`（上流本文の要約値）・`origin-fetched`（当日の日付。`YYYY-MM-DD`）を更新する。`origin` / `origin-path` / `origin-ref` は変えない。 5. 他のファイルは上流のもので置き換え、手元にだけあるファイルは消さずに報告する（上の 5 と同じ）。 6. 適用後に手順3の照合をやり直し、「最新」になることを確かめる。 **途中で失敗したら、そこで残りを止める。**「どこまで適用したか」「どれが未適用か」を必ず報告する。 部分的に適用された状態を隠してはならない。 ### 6. 結果を報告する 適用したもの・スキップしたもの・失敗したものを分けて示し、それぞれに由来（収録／外部）を添える。 「内容が違う」で見送ったものは、違うファイル名を添えて示す。 失敗があれば原因と、次に取るべき手段（再実行、手動コピー、配布元の確認）を添える。 設定については、書いた内容（初期化・追記・変更でそれぞれ何件と、書き込み先のパス）、設定で不要として省いた件数と名前、 「配布元に無い設定」を示す。 ## 既知のエージェントのスキルディレクトリ **この表はデータである。**内容は古くなりうるので、表のパスが存在しなければ手順2の汎用則へ落とす。 | エージェント | ユーザースコープ | 配布キャッシュ | `compatibility` の値 | 環境変数による上書き | |---|---|---|---|---| | Claude Code | `~/.claude/skills/` | プラグイン機構が管理（下記） | `claude-code` | `CLAUDE_CONFIG_DIR` | | OpenAI Codex | `~/.codex/skills/` | 未調査 | `codex` | `CODEX_HOME` | | OpenCode | `~/.config/opencode/skills/` | `~/.cache/opencode/skills/` | `opencode` | `XDG_CONFIG_HOME` / `OPENCODE_CONFIG_DIR`（キャッシュは `XDG_CACHE_HOME`） | **確認の根拠**: ユーザースコープの3件はいずれも実機で確認した。Codex の公式文書はベンダ中立の `~/.agents/skills/` も挙げるが、実機には未生成だった。OpenCode は単数形の `skill/` も受理する。 OpenCode の配布キャッシュには、取得時の版を記録した `.opencode-version` がスキルごとに置かれる。 **`compatibility` の値の列**は、配布側がスキルの対象を宣言するときに使う語である。 **この対応付けができないエージェントで動いている場合は、対象かどうかを判定しない**（手順3）。 **配布元の設定の在処**（手順1で読む）: | エージェント | 設定ファイル | キー | 値の形 | |---|---|---|---| | OpenCode | `~/.config/opencode/opencode.json` または `opencode.jsonc` | `skills.urls` | `index.json` を**含むディレクトリ**の URL（配列）。末尾のスラッシュは有っても無くてもよい | | Claude Code | 未調査 | — | — | | OpenAI Codex | 未調査 | — | — | **未調査の欄を推測で埋めない。** 設定が見つからないエージェントでは既定値を使い、そう明示すればよい。 設定ファイルはコメントや末尾カンマを含むことがあるので、**厳格な JSON パーサで読めなくても異常ではない**。 **必要・不要の設定ファイルの在処**（手順2の末尾で読み、手順4で書く）: | エージェント | 設定ファイル | |---|---| | Claude Code | `~/.claude/skill-sync.json` | | OpenAI Codex | `~/.codex/skill-sync.json` | | OpenCode | `~/.config/opencode/skill-sync.json` | 表に無いエージェントは、そのエージェントの設定ディレクトリ直下の `skill-sync.json` とする（汎用則）。 上の表の「環境変数による上書き」で設定ディレクトリが動いていれば、それに従う。 **本スキル専用のファイルであり、エージェント本体は読まない。** エージェント本体が検証する既存の設定ファイルには書かない。 Windows では `~` をユーザープロファイル（`%USERPROFILE%`）に読み替える。 OpenCode は Windows でも `~/.config/opencode/` を使う点に注意する（確度は中程度なので、 無ければ汎用則で探す）。 **互換読み込み**: OpenCode は自分のディレクトリに加えて `~/.claude/skills/` と `~/.agents/skills/` も読む。したがって Claude Code 側へ入れたスキルは OpenCode からも見えており、 **両方へコピーすると二重に見える**。一覧では実パスで名寄せし、 「1か所にあり2つのエージェントから見えている」ことが分かるように示す。 **プロジェクトスコープ**: `.claude/skills/` / `.opencode/skill(s)/` / `.agents/skills/` を 作業中のリポジトリ配下に持つ構成がある。一覧には出すが、更新の既定対象にはしない。 ## 書き込んではいけない場所 - **自エージェントのコンフィグディレクトリの外側すべて**（「書き込みの範囲」）。 ユーザーがその場所を明示的に指示した場合のみ例外とする。 - **他のエージェントが所有するスキルディレクトリ。** 互換読み込みによって自分から見えていても、**実体の持ち主が自分でなければ書かない**。 例えば OpenCode は `~/.claude/skills/` を読むが、そこは Claude Code の持ち物である。 - **エージェント本体が管理する領域。** 例えば Codex は自身のシステムスキルを `~/.codex/skills/.system/` に置き、目印のマーカーファイルを持つ。 **走査対象からも外す**（利用者のスキルではないため一覧に出す意味がない）。 - **プラグイン機構の管理下。** Claude Code のプラグイン経由で入ったスキルは