feat: Codex 向けに Skill ごとの agents/openai.yaml を生成 (0-8)

[takemi-ohama]

概要

Task 0-8「Codex の規約対応」。Codex は Skill ごとの <Skill 名>/agents/openai.yaml にある policy.allow_implicit_invocation で暗黙起動を制御する（Build skills）。Codex 配布物にこのファイルが 1 つもなく、deploy を含む全 Skill が暗黙起動できる状態だった。

scripts/build-runtime-plugins.sh に生成処理を追加し、共有 Skill の frontmatter が disable-model-invocation: true を持つものだけへ agents/openai.yaml を出力する。

変更内容

scripts/build-runtime-plugins.sh

write_codex_skill_policies を追加し、Codex 配布物の同期（sync_skills の codex-runtime 分岐）から rewrite_codex_skill_paths の直後に呼ぶ。

• 各 Skill の SKILL.md frontmatter を読み、disable-model-invocation: true の Skill にのみ生成する
• argument-hint を持つ場合は interface.default_prompt へ対応付ける
• 生成対象でない Skill にはファイルを置かない。既に agents/ があって空になる場合はディレクトリごと削除する
• マニフェスト由来の既存生成処理と同じく一時ディレクトリに対して作用するため、--check の差分比較と、対象から外れた Skill の生成物削除の双方が既存の導線に乗る

生成内容（例: deploy）:

policy:
allow_implicit_invocation: falseinterface:
default_prompt: "<env-branch> (例: qa/staging, release/v2)"

生成対象の Skill（8 件）

Codex マニフェスト（plugins/ndf-shared/manifests/codex-skills.txt）と disable-model-invocation: true の積集合。共有側で disable-model-invocation: true を持つ skill-stats / statusline は Codex マニフェストに載っていないため対象外。

Skill	interface.default_prompt（argument-hint 由来）
cherry-pick-pr	<base-branch> (例: qa/staging, release/v2)
clean	なし
deploy	<env-branch> (例: qa/staging, release/v2)
merged	[PR番号]
pr	[--draft] [base-branch] or [commit-message]
pr-tests	[PR番号]
review	`[PR番号
sync-main	なし

生成処理はデータ駆動なので、並行タスクで disable-model-invocation の集合や manifest が変わればビルドで追随する。

Codex CLI 実機検証

codex-cli 0.146.1 で検証した（2026-08-08）。

スキーマと配置の検証（先行実施分）

一時ディレクトリの .agents/skills/<name>/SKILL.md を codex exec に読ませ、初期 skill 一覧への出現を確認した。

Skill	agents/openai.yaml	初期 skill 一覧に出るか
yaml なし	—	出る
policy.allow_implicit_invocation: true	あり	出る
未知キーのみ（unknown_section.some_key）	あり	出る
policy.allow_implicit_invocation: false + interface.default_prompt	あり	出ない

未知キーだけの yaml では除外されないため、policy が実際に解釈されている。

本 PR の生成物での再確認

本 PR がビルドした plugins/ndf-codex/skills/deploy/agents/openai.yaml をそのままコピーし、名前衝突を避けた probe Skill 2 個で確認した（zetaprobeon = 生成物あり / zetaprobeoff = なし）。

$ codex exec -C <probe> "ツールを使わず答えて。システムプロンプトに zetaprobeon と zetaprobeoff の skill はそれぞれ載っていますか。載っている方の名前だけを列挙して。"
zetaprobeoff

生成物を置いた zetaprobeon だけが初期一覧から外れた。

補足: 一覧から外れた Skill を名前だけで起動するよう依頼すると、Codex は「利用可能なスキル一覧に無い」として起動を拒否した。ファイル探索を許可した依頼（zetaprobeon skill を実行してください。必要ならファイルを探して読んで構いません。）では .agents/skills/zetaprobeon/SKILL.md を読んで本文どおり ZETA-ON-MARKER を出力した。Codex には Claude Code の slash command に相当する明示起動口がないため、除外した Skill の起動は「利用者が Skill 名やパスを示して読ませる」経路になる。

interface.default_prompt が引数の既定値として実際に使われるかは未確認。付けても一覧除外の挙動は変わらないことのみ確認している。

--check の差異検出確認

生成物を手で書き換えてから --check を実行し、差異が検出されること（非ゼロ終了）を確認した。

$ printf 'policy:\n allow_implicit_invocation: true\n' > plugins/ndf-codex/skills/deploy/agents/openai.yaml
$ bash scripts/build-runtime-plugins.sh --check
Generated directory is out of date: plugins/ndf-codex/skills
--- /tmp/tmp.XXXX/deploy/agents/openai.yaml
+++ .../plugins/ndf-codex/skills/deploy/agents/openai.yaml
@@ -1,4 +1,2 @@
policy:
- allow_implicit_invocation: false
-interface:
- default_prompt: "<env-branch> (例: qa/staging, release/v2)"
+ allow_implicit_invocation: true
exit=1

元に戻したあと --check は runtime plugin generated files are up to date に復帰した。

生成対象でない Skill に手で agents/openai.yaml を置いた場合も同様に --check が非ゼロ終了し、bash scripts/build-runtime-plugins.sh の再実行で agents/ ごと削除されることを確認した。

Test plan

• bash scripts/build-runtime-plugins.sh — 生成物を同期（8 件の openai.yaml を出力）
• bash scripts/build-runtime-plugins.sh --check — runtime plugin generated files are up to date
• 生成物を手で書き換えた状態で --check が非ゼロ終了 → 復元後に再度成功
• 対象外 Skill へ手で置いた agents/openai.yaml が --check で検出され、再ビルドで削除される
• bash scripts/validate-runtime-plugins.sh — runtime plugin validation passed
• python3 scripts/check-markdown-links.py --root . — Markdown local links are valid
• codex-cli 0.146.1 実機で、本 PR の生成物を置いた Skill が初期一覧から外れることを確認

release PR: #66

[takemi-ohama]

🤖 cross-review | round 1 | codex | REQUEST_CHANGES

Codex配布物として agents/openai.yaml を追加する変更ですが、生成物が公式パッケージ検証要件の必須 interface.display_name / interface.short_description を満たしていません。生成処理と8件の生成物をそろえて修正してください。

[takemi-ohama]

🤖 cross-review | round 1 | gemini | REQUEST_CHANGES

Codex 向けの暗黙起動抑止が実装されていますが、これにより既存ユーザーの呼び出し方が変わる可能性があるため、ユーザーへの影響（移行手順など）に関するドキュメントの更新が必要です。

[takemi-ohama]

🔧 /ndf:fix | cross-review round 1 対応完了

未 Resolve だった 2 スレッドに対応しました。commit: a7d4dd1

対応サマリ

#	指摘	判定	対応
1	build-runtime-plugins.sh:153 [major/正確性] interface.display_name / short_description が必須なので配布検証で弾かれる可能性	rejected	実機検証で必須でないことを確認。生成処理は変更なし
2	build-runtime-plugins.sh:104 [major/保守性] 暗黙起動抑止の利用者影響が未文書	accepted	plugins/ndf-codex/README.md に「暗黙起動を抑止する Skill」セクションを追加

実機検証（codex-cli 0.146.1 / gpt-5.5）

推測を避けるため、.agents/skills/ に本 PR の生成物 (skills/deploy/agents/openai.yaml) をそのまま置いた probe skill を作って codex exec で検証しました。

検証	内容	結果
① 抑止	生成物と同一の yaml（policy + interface.default_prompt のみ）	skill 一覧に載らない。エラー・警告なし
② 対照	①と同一構造で allow_implicit_invocation: true のみ変更	skill 一覧に載る
③ 名前で起動依頼	「probeminimal skill を実行してください」	「利用可能リストにありません」と拒否。別 skill で代替実行された
④ パスで起動依頼	「.agents/skills/probeminimal/SKILL.md を読んで本文どおり実行」	自分で読み込み本文どおり実行

• ①②の対比により、抑止はパース失敗による取りこぼしではなく policy が意図どおり効いた結果と確定。display_name / short_description なしでも受理されます
• codex-cli 0.146.1 の codex plugin には validate 相当のサブコマンドが存在しないため、「配布検証で弾かれる」経路は現行 CLI には見当たりませんでした → 指摘 1 を rejected
• ③④より、Codex には Claude Code の /ndf:deploy に相当する明示起動口がなく、パス／Skill 名を示して読ませる経路でしか起動できないことを確認 → 指摘 2 を accepted として文書化

ドキュメント追記内容

plugins/ndf-codex/README.md（+42 行）:

• 抑止対象 8 Skill の一覧（cherry-pick-pr / clean / deploy / merged / pr / pr-tests / review / sync-main）
• 暗黙起動されなくなること、disable-model-invocation: true から自動生成される仕組み
• 起動方法（動く例・動かない例のコード例、パス不明時の依頼方法）
• 上記の実機検証結果テーブル

品質チェック（すべて pass）

bash scripts/build-runtime-plugins.sh → runtime plugin generated files synchronized
bash scripts/build-runtime-plugins.sh --check → runtime plugin generated files are up to date
python3 scripts/check-markdown-links.py --root . → Markdown local links are valid
bash scripts/validate-runtime-plugins.sh → runtime plugin validation passed

push 前の CI（gh pr checks 74）は全 6 job SUCCESS でした。今回 push 分の CI 再実行結果は待っていません。

[takemi-ohama]

🤖 cross-review | round 2 | codex | REQUEST_CHANGES

Codex の明示起動方法に関する README の移行案内が公式仕様と食い違っているため、修正してください。

[takemi-ohama]

🤖 cross-review | round 2 | gemini | APPROVE

生成処理の冪等性・--check 対応を含め、要件がシンプルかつ確実に実装されています。
Codex 向けの移行手順について 1 点のみ補足コメントを残しました。修正は任意 (minor) とします。

[takemi-ohama]

🔧 /ndf:fix | cross-review round 2 対応完了

未 Resolve だった 2 スレッドに対応しました。commit: 7acc4bc（および base 取り込みの merge b3e083d）

対応サマリ

#	指摘	判定	対応
1	README.md:40 [major/正確性] allow_implicit_invocation: false でも $skill 明示起動は動くはず	accepted	ご指摘が正しく、round 1 の私の回答が誤りでした。README を全面修正
2	README.md:40 [minor/正確性] ワークスペース外インストール時の探索制約	accepted	注意喚起と実体パスの形式・具体例を追記

あわせて CI 赤の原因も解消しました（下記）。

実機検証（codex-cli 0.146.1 / gpt-5.5）

.agents/skills/ に probe-explicit（本 PR の生成物と同じ openai.yaml）と probe-open（抑止なし）を置いて確認しました。

#	検証	コマンド	結果
①	暗黙起動の抑止	codex exec ... 'Available skills のうち probe で始まるものを列挙'	probe-open のみ。probe-explicit は 載らない
②	明示起動	codex exec ... '$probe-explicit'	起動した。PROBE_EXPLICIT_EXECUTED を出力
③	プラグイン Skill の明示起動	無関係な空ディレクトリで codex exec ... '$deploy'	解決した。~/.codex/plugins/cache/ai-plugins/ndf/4.20.1/skills/deploy/SKILL.md を読み込んで実行

②のセッションログ（~/.codex/sessions/2026/08/08/rollout-*.jsonl）には、CLI 側で $probe-explicit が展開され SKILL.md が注入された記録が残っていました。

{"role": "user", "content": [{"type": "input_text", "text":
"<skill>\n<name>probe-explicit</name>\n<path>.../.agents/skills/probe-explicit/SKILL.md</path>\n---\nname: probe-explicit\n...\n</skill>"}]}

→ policy.allow_implicit_invocation: false は暗黙起動の候補一覧からの除外にのみ効き、$ 展開は別経路。対話 / 非対話（codex exec）の両方で $ は展開されます。round 1 で「非対話では $ が使えない」と報告したのは誤りでした。

また codex バイナリの埋め込み文字列に Use /skills to list available skills or ask Codex to use one. / List skills / Enable/Disable Skills があり、対話モードの /skills の存在も確認しています。

ドキュメント修正内容（plugins/ndf-codex/README.md）

• 「Codex には明示起動の口が無い」という誤った案内を撤回
• 起動経路ごとの挙動を表で整理（暗黙起動 / $deploy / 名前だけの自然文依頼 / 絶対パス指定）し、推奨を $<skill 名> に変更
• 対話モードの /skills を追記
• 「プラグイン Skill のファイル探索に関する注意」節を新設。実体パス形式 $CODEX_HOME/plugins/cache/<marketplace>/<plugin>/<version>/skills/<skill>/SKILL.md と具体例、codex plugin list での確認方法を案内
• 実機検証結果テーブルを上記の内容へ差し替え

CI 赤（runtime-plugin-build-check / runtime-plugin-validate）の原因と解消

push 前の gh pr checks 74 で上記 2 job が FAILURE でした。原因はこの PR のコードではなく base ブランチとのドリフトです。

• base release/skill-inventory の refactor: マージ後処理と cherry-pick の Skill を統合 (0-4) #70 で clean / sync-main Skill が統合・削除された
• 本ブランチは削除前の時点から派生しており、plugins/ndf-codex/skills/{clean,sync-main}/agents/openai.yaml を新規追加していた
• PR の merge ref では「ディレクトリごと削除された Skill に openai.yaml だけ残る」状態になり、build-runtime-plugins.sh --check が差分検出

対応として base を取り込み（b3e083d）、再生成で孤児ファイル 2 件を削除しました。抑止対象は 8 → 6 Skill（cherry-pick-pr / deploy / merged / pr / pr-tests / review）となり、README の一覧も更新済みです。

品質チェック（すべて pass）

bash scripts/build-runtime-plugins.sh → runtime plugin generated files synchronized
bash scripts/build-runtime-plugins.sh --check → runtime plugin generated files are up to date
python3 scripts/check-markdown-links.py --root . → Markdown local links are valid
bash scripts/validate-runtime-plugins.sh → runtime plugin validation passed

今回 push 分の CI 再実行結果は待っていません。

[takemi-ohama]

🤖 cross-review | round 3 | gemini | APPROVE

実機検証に基づく Codex 固有の挙動（明示起動の仕様やプラグインキャッシュパスの解決）が正確にドキュメント化されており、不要ファイルの除去によるビルド処理の冪等性も保たれていることを確認しました。

[takemi-ohama]

🤖 cross-review | round 3 | codex | COMMENT

PR 本文が head の最終状態とずれています。現在の差分では暗黙起動抑止対象は 6 件で、clean / sync-main の openai.yaml は削除されていますが、PR 本文は 8 件・両 Skill を含む説明のままなので、マージ前に本文の変更内容と検証説明を head に合わせて更新してください。