skills support_ja

Codex カスタムスキル対応

日付: 2026-08-04 追跡: Issue #119、sub-issue #120、#121、#122、#123、#124、#125、#126、#127 状態: 実装レビュー完了、2026-08-06 に修正計画を追加

呼び出し UI の置き換え: この履歴計画の呼び出し UI 部分は、組み込みコマンドとスキル呼び出しを Slash メニューへ統合 に置き換えます。Issue #140 で追跡します。

概要

doc/task.md Phase 3.2 に基づき Codex custom skills 対応を追加する: キャッシュ付きの skills/list 取得、$<skill-name> メンション解決と skill turn input item、 skills/config/write による有効/無効切替、skills/changed による invalidation。

本計画は GitHub Copilot が作成した草案を起点とし、実装着手前にこのリポジトリの Worker/Contracts/Remote UI のパターンおよびベンダリングされた app-server スキーマと 突き合わせてレビューした。レビューにより、そのまま実装すると壊れる、または安全でない 挙動になる複数のブロッカーを修正した（下記参照）。

プロトコルの前提

現在インストールされている codex-cli（0.145.0）からプロトコルスキーマを再生成し、 ベンダリング済み schemas/（2026-06-10 生成）と diff して確認した: skills/* の スキーマはすべて変更なし。主な事実:

• skills/list は { cwds, forceReload } を受け取る。cwds が空の場合はセッションの 作業ディレクトリに解決される。レスポンスは cwd ごとのエントリの配列で、各エントリが 自身の skills[] と errors[] を持つ — クライアント側でフラット化する際に SKILL.md のパース失敗を黙って捨ててはいけない。
• SkillMetadata に id フィールドは無い。同一性は (name, scope, path) タプルで 判定する。scope は user・repo・system・admin のいずれか。
• skills/list にはページングカーソルが無い（model/list や permissionProfile/list と異なる）。レスポンス配列は依然としてサーバ供給で無制限な ので、クライアント側で上限を設ける必要がある。
• skills/changed は空の params: {} を持つ（params なしではない）。汎用通知テールに 到達する前にこれを捕捉するハンドラが無いと、スキルファイルを保存するたびにチャット トランスクリプトへ Unknown の会話イベントが紛れ込む。
• skill turn input item は { type: "skill", name, path } で、mention と構造的に 対称。skills/* のいずれのメソッドもスキーマ上 experimental とはマークされていない。
• 同じスキーマ更新で app/read と app/installed が追加されたにもかかわらず、 AppUserInput に相当する turn input item はまだ存在しない — 他所で計画されている $<app-slug> メンションは、現時点ではプロトコル側の裏付けが無い。

修正したブロッカー

元の草案はコンパイルは通るが、複数の点で実行時に壊れる状態だった:

1. skills/changed がトランスクリプトに漏れる。 account/login/completed 等と 同様に、CodexSessionService の汎用通知テールに到達する前にこの通知を捕捉する 必要がある。
2. skill turn item はファイル添付パイプラインを再利用してはいけない。 同パイプ ラインには添付専用のワークスペースポリシーがある。一方、skill path は SKILL.md ファイルの絶対パスであり、仕様上ワークスペース外 （user/system/admin scope）にも存在できる。スキルには専用のリクエスト フィールドと、添付の包含ルールを適用せず構造的妥当性を検証する専用バリデータが必要。
3. 素の DTO は Remote UI で空行として描画される。 [DataContract]/[DataMember] 型のみが VS 側プロキシへ届く。ツールウィンドウに表示するスキル一覧には、ワイヤ DTO を直接ではなく専用のプレゼンテーション型が必要。
4. IWorkerBridge へのイベント追加はソース互換性を壊す。（メソッド追加とは異なり、 イベントには既定実装を持たせられない。）ViewModelTests.cs の手書きテストダブル は、SkillsChanged を追加する PR と同一 PR で明示的に更新する必要がある。
5. contract version の bump が必要。（13 → 14）StartTurnRequest と ICodexWorkerClient の変更と同じ PR で行わないと、古い Worker バイナリがチャット 上に理由の見えない接続失敗を起こす。

確定した決定事項

論点	決定
$ メンショントリガー	v1 では skills 専用に予約。他所で言及されている $<app-slug> メンションは、app 用 turn input type がプロトコルに追加されるまで延期。
skills/config/write の確認	確認ダイアログなし — ローカルかつ即時可逆な per-item トグルであるため。system/admin scope のスキルはクライアント側でトグル不可にし、UI は常にサーバの effectiveEnabled に状態を照合する（要求値ではなく）。
Experimental API ゲート	ExperimentalApiEnabled ではゲートしない。既存の -32601 capability probe のみに依拠する。プロトコル上 skills を experimental とする記載は無く、他所で使われているハードゲートのパターンはセッション中 sticky になってしまう。

Sub-issue 内訳（#120〜#127）

各 PR は前段の PR からブランチし、単体でビルド・テスト可能な 8 段の stacked PR:

#	範囲
#120	Worker セッションでの skills/list 取得（contract bump、capability probe、上限、Fake app-server のシードデータ）。
#121	カタログをチャットトランスクリプトに一覧表示する /skills スラッシュコマンド — 最初のユーザ可視機能、XAML 変更なし。
#122	skills/changed invalidation と Worker 初の正のキャッシュ。
#123	補完オーバーレイ抜きでの、キャッシュ済みカタログに対する $skill メンション解決と skill turn input item。
#124	コンポーザーのインライン $ スキル候補オーバーレイ。
#125	読み取り専用のスキルパネル（scope・状態・読み込みエラー）。
#126	skills/config/write による有効/無効切替 — スタック中唯一の mutation のため単独 PR に分離。
#127	ドキュメント（doc/skills.md + _ja、doc/task.md、doc/slash-commands.md）。

レビュー指摘の修正実行計画（2026-08-06）

PR #128〜#135 の実装レビューで、8 件の指摘を正当なものとして採用した。計画作成前に 2026-08-06 時点の app-server 公式ドキュメントを再確認した。推奨される skill turn item と path 指定の skills/config/write は、いずれも SKILL.md の絶対パスを使う。 skills/changed は引き続き invalidation signal であり、skill 名には github:yeet の ような namespace 付き名称も存在する。

stacked PR のため、スタックの親から子へ順番に更新する。各子ブランチを push 済みの 親へ rebase し、スタック由来の競合だけを解消して focused test を実行した後、 --force-with-lease で push する。rebase 前に remote head SHA を記録し、第三者の更新が あれば上書きせず停止する。

順序	Issue / PR	修正内容	focused verification	予定 commit
1	#120 / PR #128	Fake app-server の seed path を skill directory から SKILL.md の絶対パスへ変更し、protocol assertion も更新する。	Fake app-server request/response test、Worker skill-list test、git diff --check。	fix: align fake skill paths with app-server protocol
2	#121 / PR #129	/skills は引数なしまたは reload だけを受け付け、不明な引数は turn を送らずローカルで usage error にする。	空、reload、不明、過剰引数の slash-command parsing/transcript test。	fix: validate skills command arguments
3	#122 / PR #130	skill cache generation を追加する。skills/list 前に generation を取得し、skills/changed、reconnect、その他の invalidation 後には古い結果を cache に公開しない。	制御可能な in-flight request で古い response が invalidated cache を再生成できないこと、および cache hit/reload test。	fix: prevent stale skill cache repopulation
4	#123 / PR #131	$skill token を文末記号で終了し、hyphen と namespace colon を含む対応済み名称文字は維持する。ADR も path が directory ではなく SKILL.md file であるよう修正する。	comma/period/parenthesis 境界、github:yeet、hyphenated name、escape、重複、turn item の parser test。	fix: parse punctuated skill mentions
5	#124 / PR #132	suggestion refresh の error path では、失敗した request が現在の refresh token を所有するときだけ overlay を閉じる。	request A が request B の成功後に失敗しても、B の suggestion を閉じたり置換したりしない test。	fix: preserve newer skill suggestions
6	#125 / PR #133	panel refresh を connection generation と availability state で保護し、disconnect 前の request が panel を再生成できないようにする。半透明の scope/description foreground を不透明な Visual Studio theme resource に置き換えて High Contrast を保つ。	disconnect/reconnect race、panel 排他、XAML resource/opacity assertion、および Light/Dark/Blue/High Contrast の手動確認。	fix: prevent stale skills panel updates
7	#126 / PR #134	config writer を generation-aware cache の上へ rebase し、write 成功時に共通 invalidation helper を通す。この PR 単独の新規指摘はないが、#130 統合時に直接 cache assignment を復活させない。	toggle success/failure/reconciliation test と write-during-list race test。	fix: invalidate skill cache after config writes
8	#127 / PR #135	英語・日本語ドキュメントを SKILL.md の絶対ファイルパスとワークスペース外 scope を正しく説明する内容へ修正し、protocol example を現行 app-server ドキュメントと再照合する。	ドキュメントの link/path review、英日 parity、git diff --check、最終 stack validation。	fix: correct skill path documentation

各 push 後に当該 PR の required GitHub checks を待ち、更新済み base に対する diff がその issue の範囲だけであることを確認する。PR #135 の更新後、warnings-as-errors の clean Release build を 1 回行い、Core/UI の skill-focused test と、--no-build で全 test project を実行する。既存 failure を unrelated と判定する場合は、変更前 baseline でも 再現することを必須とする。最後に Fake app-server で skills/list、skills/changed、 skills/config/write、および出力される skill turn item を smoke test する。

検証

1. 最初の PR に着手する前に、固定した Codex CLI バージョンからスキーマを再生成し、 skills/* ファイルをベンダリング済みコピーと diff する。
2. warnings-as-errors での決定的なソリューションビルド 1 回、その後 --no-build で 両テストプロジェクトを実行。
3. CodexSessionServiceTests/WorkerRpcServiceTests で capability-probe のフォール バック、キャッシュのヒット/invalidation、不正/切り詰められたペイロード、redaction をカバーする。
4. ViewModelTests/XAML 回帰テストで、トランスクリプト出力、パネルの排他制御、 コンポーザー候補のキーボード操作、Remote UI サニタイズをカバーする。
5. 手動確認: Codex.AppServer.Fake に skills/list/skills/changed/turn/start リクエストを流し込み、シードカタログ、skills/changed でトランスクリプトに 余分なイベントが出ないこと、skill turn item が出力されることを確認する。