diff --git a/.github/workflows/all_test.yml b/.github/workflows/all_test.yml
index 183b592..24755a6 100644
--- a/.github/workflows/all_test.yml
+++ b/.github/workflows/all_test.yml
@@ -65,10 +65,19 @@ jobs:
           # Scene selection:
           # - ci_top_attention_doc_page_build validates doc build through the prebuilt Docker image.
           # - ci_top_attention_bin_kvtest keeps the Rust kv_test entry under the testbed scene contract.
+          # - ci_top_attention_config_* and ci_top_attention_ctrl_c_* reuse the same ops testbed/test-stack CI chain.
           suite["scenes"] = {
               key: value
               for key, value in suite["scenes"].items()
-              if key in ("ci_top_attention_doc_page_build", "ci_top_attention_bin_kvtest")
+              if key in (
+                  "ci_top_attention_doc_page_build",
+                  "ci_top_attention_bin_kvtest",
+                  "ci_top_attention_config_kv",
+                  "ci_top_attention_config_fs",
+                  "ci_top_attention_config_mq",
+                  "ci_top_attention_ctrl_c_kv",
+                  "ci_top_attention_ctrl_c_mq",
+              )
           }
 
           # Profile selection:
@@ -91,6 +100,7 @@ jobs:
           # - Keep the original per-scene scales from ci_test_list.yaml.
           # - ci_top_attention_doc_page_build stays on n1_kvowner_dram_3gib.
           # - ci_top_attention_bin_kvtest stays on n1_kvowner_dram_20gib.
+          # - Config/Ctrl-C wrappers stay on n1_kvowner_dram_3gib.
 
           out_path.write_text(
               yaml.safe_dump(suite, sort_keys=False, allow_unicode=False),
diff --git "a/fluxon_doc_cn/design/teststack_1_\345\275\223\345\211\215\346\236\266\346\236\204\344\270\216CI\346\265\213\350\257\225\346\265\201\347\250\213.md" "b/fluxon_doc_cn/design/teststack_1_\345\275\223\345\211\215\346\236\266\346\236\204\344\270\216CI\346\265\213\350\257\225\346\265\201\347\250\213.md"
index ce767f7..866f925 100644
--- "a/fluxon_doc_cn/design/teststack_1_\345\275\223\345\211\215\346\236\266\346\236\204\344\270\216CI\346\265\213\350\257\225\346\265\201\347\250\213.md"
+++ "b/fluxon_doc_cn/design/teststack_1_\345\275\223\345\211\215\346\236\266\346\236\204\344\270\216CI\346\265\213\350\257\225\346\265\201\347\250\213.md"
@@ -247,7 +247,7 @@ suite 中有两大类场景：
    - 这是 case 空间的第一层边界。
 2. `scene kind`
    - 决定当前 scene 走 `CI` 还是 `TEST_STACK` 分支；
-   - 也决定后续必须存在哪些字段，例如 `scene.ci.runtime_contract` 或 `scene.test_stack.mode`。
+  - 也决定后续必须存在哪些字段，例如 `scene.ci.requirements` 或 `scene.test_stack.mode`。
 3. `scale`
    - 提供 topology、targets、owner、benchmark 等“规模与布局”约束；
    - 这些约束不会自己决定 runtime 模板，但会限制哪些 runtime 模板能成功 materialize。
@@ -292,7 +292,7 @@ suite 中有两大类场景：
 
 - `CI`
   - scene 选中的 profile 必须有 `runtime.ci`；
-  - `scene.ci.runtime_contract` 必须能在该 profile 的 `runtime.ci.runtime_contracts` 中找到；
+  - `scene.ci.requirements` 中声明的每个 requirement，必须都能在该 profile 的 `runtime.ci.requirements` 中找到；
   - 选中的 scale 必须至少满足 `CI` 所需的 topology 基础字段。
 - `TEST_STACK`
   - scene 选中的 profile 必须有 `runtime.test_stack`；
@@ -308,7 +308,7 @@ suite 中有两大类场景：
 - `scene.select.profiles` 引用了不存在的 `profile`。
 - `profile.artifact_set` 指向了不存在的 `artifact_set`。
 - `CI` scene 选中了没有 `runtime.ci` 的 profile。
-- `scene.ci.runtime_contract` 在选中 profile 的 `runtime.ci.runtime_contracts` 中不存在。
+- `scene.ci.requirements` 中有 requirement 未在选中 profile 的 `runtime.ci.requirements` 中定义。
 - `TEST_STACK` scene 选中了没有 benchmark block 的 scale。
 - `TEST_STACK` role plan 推导出的 target，不在 profile 的 `deploy.target_ip_map` 里。
 - `run.selectors.profile_ids` 或 `case_ids` 在编译后的 case 集合里选不中任何对象。
@@ -348,7 +348,7 @@ deploy.instances 不写死在 suite 中。Runner 会结合 scale、profile 和
 `CI` scene 会在通用编译模型上追加这些字段：
 
 - `scene.ci.subject`
-- `scene.ci.runtime_contract`
+- `scene.ci.requirements`
 - `scene.ci.prepare`
 - `scene.ci.commands`
 
@@ -356,12 +356,17 @@ deploy.instances 不写死在 suite 中。Runner 会结合 scale、profile 和
 
 - `prepare` 是 CI case 的前置环境准备；
 - `commands` 是 resolved case 里的编译产物字段，不是 suite 输入字段；`test_runner.py` 会按有限 `scene_id` 分支把它生成给 `ci_runner` 顺序执行；
-- `runtime_contract` 决定 profile 里选哪套 runtime 模板。
+- `requirements` 显式声明这个 scene 需要哪些基础服务、case runtime 实例，以及额外 runner 行为。
 
-已存在两个 runtime contract：
+当前 requirement 是有限枚举集合，例如：
 
-- `cluster_kv_owner`
-- `rust_self_managed`
+- `testbed_etcd`
+- `testbed_greptime`
+- `master`
+- `owner_0`
+- `ci_runner`
+- `owner_shared_bundle`
+- `fluxon_kv_readiness_probe`
 
 `_compile_ci_case()` 会根据：
 
@@ -374,7 +379,7 @@ deploy.instances 不写死在 suite 中。Runner 会结合 scale、profile 和
 `CI` 特化的稳定事实：
 
 - `CI_CASE_RUNTIME_INSTANCE_IDS = ("master", "owner_0", "ci_runner")`
-- 最终是否包含这三个实例，取决于 runtime contract 模板里是否声明；
+- 最终是否包含这些实例，取决于 scene requirements 是否显式声明并且 profile requirement configs 是否提供；
 - `resolved_case` 会额外固化 `command_id`、`test_id` 等 CI 元数据；
 - 生成顺序是稳定的，后续 phase 规划依赖这个顺序。
 
diff --git a/fluxon_test_stack/ci_2_virt_node.py b/fluxon_test_stack/ci_2_virt_node.py
index 28e9b82..48a0a23 100644
--- a/fluxon_test_stack/ci_2_virt_node.py
+++ b/fluxon_test_stack/ci_2_virt_node.py
@@ -39,8 +39,6 @@
 LOCAL_SECONDARY_NODE_SUFFIX = "b"
 TEST_STACK_START_TEST_BED_CONFIG_ENV = "FLUXON_TEST_STACK_START_TEST_BED_CONFIG"
 PLACEHOLDER_WHEEL_NAME = "fluxon-0.0.0-ci-placeholder-cp38-abi3-manylinux_2_28_x86_64.whl"
-SAME_HOST_LOCAL_MULTI_NODE_ETCD_CLIENT_PORT_OFFSET = 100
-SAME_HOST_LOCAL_MULTI_NODE_GREPTIME_PORT_OFFSET = 110
 
 
 def _parse_args() -> argparse.Namespace:
@@ -404,10 +402,6 @@ def _rewrite_suite_for_local_dual_nodes(
     runtime = generated_profile.get("runtime")
     if not isinstance(runtime, dict):
         raise ValueError("generated public profile runtime must be a mapping")
-    ci_base_runtime_host_ports = {
-        "etcd": int(controller_port) + SAME_HOST_LOCAL_MULTI_NODE_ETCD_CLIENT_PORT_OFFSET,
-        "greptime": int(controller_port) + SAME_HOST_LOCAL_MULTI_NODE_GREPTIME_PORT_OFFSET,
-    }
     ci_runtime = runtime.get("ci")
     if not isinstance(ci_runtime, dict):
         raise ValueError("generated public profile must define runtime.ci")
@@ -435,28 +429,14 @@ def _rewrite_suite_for_local_dual_nodes(
             secondary_node_name: host_ip,
         }
         if runtime_key == "ci":
-            runtime_contracts = runtime_block.get("runtime_contracts")
-            if not isinstance(runtime_contracts, dict):
-                raise ValueError("generated public profile runtime.ci.runtime_contracts must be a mapping")
-            for contract in runtime_contracts.values():
-                if not isinstance(contract, dict):
-                    continue
-                base_runtime = contract.get("base_runtime")
-                if isinstance(base_runtime, dict):
-                    for svc_name in ("etcd", "greptime"):
-                        svc_cfg = base_runtime.get(svc_name)
-                        if isinstance(svc_cfg, dict):
-                            svc_cfg["target"] = primary_node_name
-                            endpoint_cfg = svc_cfg.get("endpoint")
-                            if isinstance(endpoint_cfg, dict):
-                                endpoint_cfg["host_port"] = int(ci_base_runtime_host_ports[svc_name])
-                case_runtime = contract.get("case_runtime")
-                if isinstance(case_runtime, dict):
-                    master_cfg = case_runtime.get("master")
-                    if isinstance(master_cfg, dict):
-                        deployer_cfg = master_cfg.get("deployer")
-                        if isinstance(deployer_cfg, dict):
-                            deployer_cfg["target"] = primary_node_name
+            requirement_configs = runtime_block.get("requirements")
+            if not isinstance(requirement_configs, dict):
+                raise ValueError("generated public profile runtime.ci.requirements must be a mapping")
+            master_cfg = requirement_configs.get("master")
+            if isinstance(master_cfg, dict):
+                deployer_cfg = master_cfg.get("deployer")
+                if isinstance(deployer_cfg, dict):
+                    deployer_cfg["target"] = primary_node_name
         if runtime_key == "test_stack":
             deploy_templates = runtime_block.get("deploy_templates")
             if isinstance(deploy_templates, dict):
diff --git a/fluxon_test_stack/ci_test_list.yaml b/fluxon_test_stack/ci_test_list.yaml
index 482cb79..695749d 100644
--- a/fluxon_test_stack/ci_test_list.yaml
+++ b/fluxon_test_stack/ci_test_list.yaml
@@ -1,4 +1,4 @@
-schema_version: 9
+schema_version: 10
 
 run:
   mode: full_once
@@ -11,8 +11,7 @@ run:
 scenes:
   ci_top_attention_doc_page_build:
     ci:
-      subject: doc_page
-      runtime_contract: rust_self_managed
+      requirements: [ci_runner]
       prepare:
         - kind: online_docker_image
           image_ref: hanbaoaaa/fluxon-doc-site-builder:quartz-v5.0.0-node-v24.16.0
@@ -23,12 +22,46 @@ scenes:
 
   ci_top_attention_bin_kvtest:
     ci:
-      subject: rust
-      runtime_contract: rust_self_managed
+      requirements: [ci_runner, testbed_etcd, testbed_greptime]
     select:
       scales: [n1_kvowner_dram_20gib]
       profiles: [fluxon_tcp]
 
+  ci_top_attention_config_kv:
+    ci:
+      requirements: [ci_runner]
+    select:
+      scales: [n1_kvowner_dram_3gib]
+      profiles: [fluxon_tcp]
+
+  ci_top_attention_config_fs:
+    ci:
+      requirements: [ci_runner]
+    select:
+      scales: [n1_kvowner_dram_3gib]
+      profiles: [fluxon_tcp]
+
+  ci_top_attention_config_mq:
+    ci:
+      requirements: [ci_runner, master, owner_0, testbed_etcd, testbed_greptime]
+    select:
+      scales: [n1_kvowner_dram_3gib]
+      profiles: [fluxon_tcp]
+
+  ci_top_attention_ctrl_c_kv:
+    ci:
+      requirements: [ci_runner]
+    select:
+      scales: [n1_kvowner_dram_3gib]
+      profiles: [fluxon_tcp]
+
+  ci_top_attention_ctrl_c_mq:
+    ci:
+      requirements: [ci_runner, testbed_etcd, testbed_greptime]
+    select:
+      scales: [n1_kvowner_dram_3gib]
+      profiles: [fluxon_tcp]
+
   kv_read_heavy_zipf:
     test_stack:
       mode: KVSTORE
@@ -315,72 +348,48 @@ profiles:
             doc_site_base_url: example.com
           ci_top_attention_bin_kvtest:
             kv_test_rounds: all
-        runtime_contracts:
-          cluster_kv_owner: &cluster_kv_owner_runtime
-            base_runtime:
-              etcd:
-                target: infra44-ThinkStation-PX
-                endpoint:
-                  scheme: HTTP
-                  host_port: 32579
-              greptime:
-                target: infra44-ThinkStation-PX
-                endpoint:
-                  scheme: HTTP
-                  host_port: 34030
-            case_runtime:
-              master:
-                lifecycle: service
-                k8s_ref: deployment/master
-                deployer:
-                  target: infra44-ThinkStation-PX
-                  command: [/bin/bash, -lc]
-                  args:
-                    - |
-                      set -euo pipefail
-                      cd __RUN_DIR__/src
-                      exec __RUN_DIR__/venv/bin/python3 -m fluxon_py.runtime.start_master \
-                        -c __RUN_DIR__/configs/ci_master.yaml \
-                        -w __RUN_DIR__/services/master
-              owner_0:
-                lifecycle: service
-                k8s_ref: deployment/owner_0
-                deployer:
-                  target: __TARGET__
-                  command: [/bin/bash, -lc]
-                  args:
-                    - |
-                      set -euo pipefail
-                      cd __RUN_DIR__/src
-                      exec __RUN_DIR__/venv/bin/python3 -m fluxon_py.runtime.start_owner_kvclient \
-                        -c __RUN_DIR__/configs/ci_owner_0.yaml \
-                        -w __RUN_DIR__/services/owner_0
-              ci_runner: &common_ci_runner_instance
-                lifecycle: job
-                k8s_ref: deployment/ci_runner
-                deployer:
-                  target: __TARGET__
-                  command: [/bin/bash, -lc]
-                  args:
-                    - |
-                      set -uo pipefail
-                      exec bash __RUN_DIR__/ci_runner.sh
-          rust_self_managed:
-            base_runtime:
-              etcd:
-                target: infra44-ThinkStation-PX
-                endpoint:
-                  scheme: HTTP
-                  host_port: 32579
-              greptime:
-                target: infra44-ThinkStation-PX
-                endpoint:
-                  scheme: HTTP
-                  host_port: 34030
-            case_runtime:
-              ci_runner:
-                <<: *common_ci_runner_instance
-
+          ci_top_attention_config_kv: {}
+          ci_top_attention_config_fs: {}
+          ci_top_attention_config_mq: {}
+          ci_top_attention_ctrl_c_kv: {}
+          ci_top_attention_ctrl_c_mq: {}
+        requirements:
+          master:
+            lifecycle: service
+            k8s_ref: deployment/master
+            deployer:
+              target: infra44-ThinkStation-PX
+              command: [/bin/bash, -lc]
+              args:
+                - |
+                  set -euo pipefail
+                  cd __RUN_DIR__/src
+                  exec __RUN_DIR__/venv/bin/python3 -m fluxon_py.runtime.start_master \
+                    -c __RUN_DIR__/configs/ci_master.yaml \
+                    -w __RUN_DIR__/services/master
+          owner_0:
+            lifecycle: service
+            k8s_ref: deployment/owner_0
+            deployer:
+              target: __TARGET__
+              command: [/bin/bash, -lc]
+              args:
+                - |
+                  set -euo pipefail
+                  cd __RUN_DIR__/src
+                  exec __RUN_DIR__/venv/bin/python3 -m fluxon_py.runtime.start_owner_kvclient \
+                    -c __RUN_DIR__/configs/ci_owner_0.yaml \
+                    -w __RUN_DIR__/services/owner_0
+          ci_runner: &common_ci_runner_instance
+            lifecycle: job
+            k8s_ref: deployment/ci_runner
+            deployer:
+              target: __TARGET__
+              command: [/bin/bash, -lc]
+              args:
+                - |
+                  set -uo pipefail
+                  exec bash __RUN_DIR__/ci_runner.sh
       test_stack: &common_test_stack_runtime
         kind: FLUXON
         # English note:
@@ -460,6 +469,11 @@ profiles:
             doc_site_base_url: example.com
           ci_top_attention_bin_kvtest:
             kv_test_rounds: all
+          ci_top_attention_config_kv: {}
+          ci_top_attention_config_fs: {}
+          ci_top_attention_config_mq: {}
+          ci_top_attention_ctrl_c_kv: {}
+          ci_top_attention_ctrl_c_mq: {}
       test_stack:
         <<: *common_test_stack_runtime
   fluxon_sockudo_ws:
@@ -472,6 +486,11 @@ profiles:
             doc_site_base_url: example.com
           ci_top_attention_bin_kvtest:
             kv_test_rounds: all
+          ci_top_attention_config_kv: {}
+          ci_top_attention_config_fs: {}
+          ci_top_attention_config_mq: {}
+          ci_top_attention_ctrl_c_kv: {}
+          ci_top_attention_ctrl_c_mq: {}
       test_stack:
         <<: *common_test_stack_runtime
   fluxon_tcp:
@@ -484,6 +503,11 @@ profiles:
             doc_site_base_url: example.com
           ci_top_attention_bin_kvtest:
             kv_test_rounds: all
+          ci_top_attention_config_kv: {}
+          ci_top_attention_config_fs: {}
+          ci_top_attention_config_mq: {}
+          ci_top_attention_ctrl_c_kv: {}
+          ci_top_attention_ctrl_c_mq: {}
       test_stack:
         <<: *common_test_stack_runtime
   redis_sharded:
diff --git a/fluxon_test_stack/test_runner.py b/fluxon_test_stack/test_runner.py
index f70618a..233b999 100644
--- a/fluxon_test_stack/test_runner.py
+++ b/fluxon_test_stack/test_runner.py
@@ -59,7 +59,7 @@
 #
 # Keep them decoupled to avoid accidental "schema bumps" across unrelated layers.
 SCHEMA_VERSION = 1
-SUITE_SCHEMA_VERSION = 9
+SUITE_SCHEMA_VERSION = 10
 
 # Enums (case-sensitive strings; internal routing only - not part of suite config schema)
 SCENE_KIND_INFER = "INFER"
@@ -78,12 +78,6 @@
 _RUN_EXCEPTION_FILENAME = "exception.txt"
 CI_PRESERVED_APPLY_IDS_SCHEMA_VERSION = 1
 CI_PRESERVED_APPLY_IDS_FILENAME = "ci_preserved_apply_ids.yaml"
-CI_RUNTIME_CONTRACT_CLUSTER_KV_OWNER = "cluster_kv_owner"
-CI_RUNTIME_CONTRACT_RUST_SELF_MANAGED = "rust_self_managed"
-CI_RUNTIME_CONTRACT_IDS = (
-    CI_RUNTIME_CONTRACT_CLUSTER_KV_OWNER,
-    CI_RUNTIME_CONTRACT_RUST_SELF_MANAGED,
-)
 CI_PREPARE_KIND_SETUP_DEV_ENV = "setup_dev_env"
 CI_PREPARE_KIND_ONLINE_DOCKER_IMAGE = "online_docker_image"
 CI_PREPARE_KIND_IDS = (
@@ -98,7 +92,28 @@
     RUNTIME_LAYER_BASE,
     RUNTIME_LAYER_CASE,
 )
+CI_REQUIREMENT_TESTBED_ETCD = "testbed_etcd"
+CI_REQUIREMENT_TESTBED_GREPTIME = "testbed_greptime"
+CI_REQUIREMENT_MASTER = "master"
+CI_REQUIREMENT_OWNER_0 = "owner_0"
+CI_REQUIREMENT_CI_RUNNER = "ci_runner"
+CI_REQUIREMENT_IDS = (
+    CI_REQUIREMENT_TESTBED_ETCD,
+    CI_REQUIREMENT_TESTBED_GREPTIME,
+    CI_REQUIREMENT_MASTER,
+    CI_REQUIREMENT_OWNER_0,
+    CI_REQUIREMENT_CI_RUNNER,
+)
 CI_BASE_RUNTIME_SERVICE_IDS = ("etcd", "greptime")
+CI_BASE_RUNTIME_REQUIREMENT_IDS = {
+    "etcd": CI_REQUIREMENT_TESTBED_ETCD,
+    "greptime": CI_REQUIREMENT_TESTBED_GREPTIME,
+}
+CI_REQUIREMENTS_WITH_PROFILE_CONFIG = (
+    CI_REQUIREMENT_MASTER,
+    CI_REQUIREMENT_OWNER_0,
+    CI_REQUIREMENT_CI_RUNNER,
+)
 CI_CLUSTER_MEMBER_INSTANCE_IDS = ("master", "owner_0")
 CI_CLUSTER_RUNTIME_INSTANCE_IDS = ("master", "owner_0")
 CI_CASE_RUNTIME_INSTANCE_IDS = ("master", "owner_0", "ci_runner")
@@ -312,21 +327,6 @@ def _test_stack_ops_namespace() -> str:
         )
     return raw
 
-# Suite schema keeps scene as purpose+subject and pushes concrete sizing/topology into scale.
-SCENE_SUBJECT_KV = "kv"
-SCENE_SUBJECT_MQ = "mq"
-SCENE_SUBJECT_FS = "fs"
-SCENE_SUBJECT_RUST = "rust"
-SCENE_SUBJECT_DOC_PAGE = "doc_page"
-SCENE_SUBJECT_INFER = "infer"
-SCENE_SUBJECTS_ALLOWED = {
-    SCENE_SUBJECT_KV,
-    SCENE_SUBJECT_MQ,
-    SCENE_SUBJECT_FS,
-    SCENE_SUBJECT_RUST,
-    SCENE_SUBJECT_DOC_PAGE,
-    SCENE_SUBJECT_INFER,
-}
 TEST_STACK_REQUEST_DISTRIBUTION_UNIFORM = "uniform"
 TEST_STACK_REQUEST_DISTRIBUTION_ZIPFIAN = "zipfian"
 TEST_STACK_REQUEST_DISTRIBUTIONS_ALLOWED = {
@@ -356,6 +356,11 @@ def _runner_native_ci_scene_ids() -> Tuple[str, ...]:
     return (
         "ci_top_attention_doc_page_build",
         "ci_top_attention_bin_kvtest",
+        "ci_top_attention_config_kv",
+        "ci_top_attention_config_fs",
+        "ci_top_attention_config_mq",
+        "ci_top_attention_ctrl_c_kv",
+        "ci_top_attention_ctrl_c_mq",
     )
 
 
@@ -2580,15 +2585,30 @@ def _ci_has_instance(resolved_case: Dict[str, Any], *, instance_id: str) -> bool
     return instance_id in set(_ci_case_instance_ids(resolved_case))
 
 
-def _ci_runtime_contract_id(resolved_case: Dict[str, Any]) -> str:
+def _ci_requirement_ids(resolved_case: Dict[str, Any]) -> Tuple[str, ...]:
     scene = _require_dict(resolved_case.get("scene"), "resolved_case.scene")
     ci = _require_dict(scene.get("ci"), "resolved_case.scene.ci")
-    return _require_ci_runtime_contract(
-        ci.get("runtime_contract"),
-        "resolved_case.scene.ci.runtime_contract",
+    return tuple(
+        _parse_ci_requirements(
+            ci.get("requirements"),
+            "resolved_case.scene.ci.requirements",
+        )
     )
 
 
+def _ci_has_requirement(resolved_case: Dict[str, Any], *, requirement_id: str) -> bool:
+    return requirement_id in set(_ci_requirement_ids(resolved_case))
+
+
+def _selected_ci_requirement_configs(resolved_case: Dict[str, Any]) -> Dict[str, Any]:
+    profile = _require_dict(resolved_case.get("profile"), "resolved_case.profile")
+    ci = _require_dict(profile.get("ci"), "resolved_case.profile.ci")
+    raw_requirement_configs = ci.get("requirements")
+    if raw_requirement_configs is None:
+        return {}
+    return _require_dict(raw_requirement_configs, "resolved_case.profile.ci.requirements")
+
+
 def _case_family_id(case_kind: str) -> str:
     if case_kind == SCENE_KIND_INFER:
         return CASE_FAMILY_INFER
@@ -2630,9 +2650,14 @@ def _close_case_runtime_locks(runtime_tracking: _CaseRuntimeTracking) -> None:
         runtime_tracking.controller_lock_fp = None
 
 
-def _build_runtime_model(case_family: str) -> Dict[str, Any]:
+def _build_runtime_model(case_family: str, *, ci_requirement_ids: Optional[Tuple[str, ...]] = None) -> Dict[str, Any]:
     if case_family == CASE_FAMILY_CI:
-        case_instance_ids = list(CI_RUNTIME_LAYER_INSTANCE_IDS[RUNTIME_LAYER_CASE])
+        requirement_ids = set(ci_requirement_ids or ())
+        case_instance_ids = [
+            instance_id
+            for instance_id in CI_CASE_RUNTIME_INSTANCE_IDS
+            if instance_id in requirement_ids
+        ]
     elif case_family in (CASE_FAMILY_INFER, CASE_FAMILY_BENCH):
         case_instance_ids = []
     else:
@@ -2643,7 +2668,12 @@ def _build_runtime_model(case_family: str) -> Dict[str, Any]:
         RUNTIME_LAYER_CASE: {"instance_ids": case_instance_ids},
     }
     if case_family == CASE_FAMILY_CI:
-        model[RUNTIME_LAYER_BASE]["service_ids"] = list(CI_BASE_RUNTIME_SERVICE_IDS)
+        requirement_ids = set(ci_requirement_ids or ())
+        model[RUNTIME_LAYER_BASE]["service_ids"] = [
+            service_id
+            for service_id in CI_BASE_RUNTIME_SERVICE_IDS
+            if CI_BASE_RUNTIME_REQUIREMENT_IDS[service_id] in requirement_ids
+        ]
     return model
 
 
@@ -3302,7 +3332,7 @@ def _ci_runner_runtime_stage(resolved_case: Dict[str, Any]) -> _RemoteRunDirStag
     if _ci_has_instance(resolved_case, instance_id="master"):
         verify_relpaths.append("configs/ci_master.yaml")
     include_relpaths = list(CI_RUNNER_REMOTE_STAGE_INCLUDE_RELPATHS)
-    if _ci_runtime_contract_id(resolved_case) == CI_RUNTIME_CONTRACT_CLUSTER_KV_OWNER:
+    if _ci_has_requirement(resolved_case, requirement_id=CI_REQUIREMENT_MASTER):
         for relpath in ("fluxon_release", "test_rsc"):
             if relpath not in include_relpaths:
                 include_relpaths.append(relpath)
@@ -3667,9 +3697,12 @@ def _prepare_ci_case(
     if prepare_env_exports:
         _write_ci_prepare_env_script(run_dir=run_dir, exports=prepare_env_exports)
 
-    profile = _require_dict(resolved_case.get("profile"), "resolved_case.profile")
-    profile_ci = _require_dict(profile.get("ci"), "resolved_case.profile.ci")
-    if profile_ci.get("scene_config") is not None:
+    if _scene_id_uses_runner_native_ci_commands(
+        _require_str(
+            _require_dict(resolved_case.get("case"), "resolved_case.case").get("scene_id"),
+            "resolved_case.case.scene_id",
+        )
+    ):
         _write_ci_scene_config_yaml(
             resolved_case,
             run_dir=run_dir,
@@ -4331,8 +4364,8 @@ def _ci_base_runtime_service(resolved_case: Dict[str, Any], *, service_id: str)
 
 
 def _ci_base_runtime_service_target_name(resolved_case: Dict[str, Any], *, service_id: str) -> str:
-    svc = _ci_base_runtime_service(resolved_case, service_id=service_id)
-    return _require_str(svc.get("target"), f"resolved_case.profile.ci.runtime.base_runtime[{service_id!r}].target")
+    _ = resolved_case
+    return _testbed_service_target_name(service_id)
 
 
 def _target_uses_local_loopback(
@@ -4359,28 +4392,13 @@ def _ci_base_runtime_service_target_ip(resolved_case: Dict[str, Any], *, service
 
 
 def _ci_base_runtime_service_port(resolved_case: Dict[str, Any], *, service_id: str) -> int:
-    svc = _ci_base_runtime_service(resolved_case, service_id=service_id)
-    endpoint = _require_dict(
-        svc.get("endpoint"),
-        f"resolved_case.profile.ci.runtime.base_runtime[{service_id!r}].endpoint",
-    )
-    return _require_int(
-        endpoint.get("host_port"),
-        f"resolved_case.profile.ci.runtime.base_runtime[{service_id!r}].endpoint.host_port",
-        min_v=1,
-    )
+    _, port = _testbed_service_host_port(service_id, ctx=f"CI {service_id} service")
+    return port
 
 
 def _ci_base_runtime_service_url(resolved_case: Dict[str, Any], *, service_id: str) -> str:
-    svc = _ci_base_runtime_service(resolved_case, service_id=service_id)
-    endpoint = _require_dict(
-        svc.get("endpoint"),
-        f"resolved_case.profile.ci.runtime.base_runtime[{service_id!r}].endpoint",
-    )
-    scheme = _require_str(
-        endpoint.get("scheme"),
-        f"resolved_case.profile.ci.runtime.base_runtime[{service_id!r}].endpoint.scheme",
-    )
+    _ = resolved_case
+    scheme = _ENDPOINT_SCHEME_HTTP
     host = _ci_base_runtime_service_target_ip(resolved_case, service_id=service_id)
     port = _ci_base_runtime_service_port(resolved_case, service_id=service_id)
     if scheme == _ENDPOINT_SCHEME_HTTP:
@@ -5651,23 +5669,6 @@ def _require_id_list(raw: Any, ctx: str) -> List[str]:
     return out
 
 
-def _require_scene_subject(raw: Any, ctx: str) -> str:
-    subject = _require_str(raw, ctx).strip()
-    if subject not in SCENE_SUBJECTS_ALLOWED:
-        raise ValueError(f"{ctx} invalid subject: {subject!r}")
-    return subject
-
-
-def _infer_test_stack_subject_from_mode(mode: str) -> str:
-    if mode == TEST_STACK_MODE_MPMC:
-        return SCENE_SUBJECT_MQ
-    if mode in (TEST_STACK_MODE_KVSTORE, TEST_STACK_MODE_KVSTORE_WITH_LOCAL_CACHE, TEST_STACK_MODE_RPC):
-        return SCENE_SUBJECT_KV
-    if mode == TEST_STACK_MODE_PY_FS:
-        return SCENE_SUBJECT_FS
-    raise ValueError(f"unsupported test_stack mode for subject inference: {mode!r}")
-
-
 def _require_test_stack_backend_kind(raw: Any, ctx: str) -> str:
     if raw is None:
         return TEST_STACK_BACKEND_FLUXON
@@ -5679,23 +5680,37 @@ def _require_test_stack_backend_kind(raw: Any, ctx: str) -> str:
     return kind
 
 
-def _test_stack_backend_supports_subject(*, backend_kind: str, subject: str) -> bool:
+def _test_stack_backend_supports_mode(*, backend_kind: str, mode: str) -> bool:
     if backend_kind == TEST_STACK_BACKEND_FLUXON:
-        return subject in {SCENE_SUBJECT_KV, SCENE_SUBJECT_MQ, SCENE_SUBJECT_FS}
+        return mode in (
+            TEST_STACK_MODE_MPMC,
+            TEST_STACK_MODE_KVSTORE,
+            TEST_STACK_MODE_KVSTORE_WITH_LOCAL_CACHE,
+            TEST_STACK_MODE_PY_FS,
+            TEST_STACK_MODE_RPC,
+        )
     if backend_kind == TEST_STACK_BACKEND_REDIS:
-        return subject == SCENE_SUBJECT_KV
+        return mode in (
+            TEST_STACK_MODE_KVSTORE,
+            TEST_STACK_MODE_KVSTORE_WITH_LOCAL_CACHE,
+            TEST_STACK_MODE_RPC,
+        )
     if backend_kind == TEST_STACK_BACKEND_MOONCAKE:
-        return subject == SCENE_SUBJECT_KV
+        return mode in (
+            TEST_STACK_MODE_KVSTORE,
+            TEST_STACK_MODE_KVSTORE_WITH_LOCAL_CACHE,
+            TEST_STACK_MODE_RPC,
+        )
     if backend_kind == TEST_STACK_BACKEND_ALLUXIO:
-        return subject == SCENE_SUBJECT_FS
+        return mode == TEST_STACK_MODE_PY_FS
     raise ValueError(f"unsupported test_stack backend_kind: {backend_kind!r}")
 
 
-def _validate_test_stack_backend_subject(*, backend_kind: str, subject: str, ctx: str) -> None:
-    if _test_stack_backend_supports_subject(backend_kind=backend_kind, subject=subject):
+def _validate_test_stack_backend_mode(*, backend_kind: str, mode: str, ctx: str) -> None:
+    if _test_stack_backend_supports_mode(backend_kind=backend_kind, mode=mode):
         return
     raise ValueError(
-        f"{ctx} backend_kind={backend_kind!r} does not support subject={subject!r}"
+        f"{ctx} backend_kind={backend_kind!r} does not support mode={mode!r}"
     )
 
 
@@ -5729,27 +5744,30 @@ def _test_stack_backend_uses_dedicated_kv_owners(*, backend_kind: str, mode: str
     return False
 
 
-def _require_ci_runtime_contract(raw: Any, ctx: str) -> str:
-    runtime_contract = _require_str(raw, ctx).strip()
-    if runtime_contract not in CI_RUNTIME_CONTRACT_IDS:
-        raise ValueError(f"{ctx} invalid ci runtime_contract: {runtime_contract!r}")
-    return runtime_contract
+def _require_ci_requirement_id(raw: Any, ctx: str) -> str:
+    requirement_id = _require_str(raw, ctx).strip()
+    if requirement_id not in CI_REQUIREMENT_IDS:
+        raise ValueError(f"{ctx} invalid ci requirement: {requirement_id!r}")
+    return requirement_id
 
 
-def _validate_test_stack_subject_mode(*, subject: str, mode: str, ctx: str) -> None:
-    if subject == SCENE_SUBJECT_MQ:
-        if mode != TEST_STACK_MODE_MPMC:
-            raise ValueError(f"{ctx} subject={subject!r} requires mode={TEST_STACK_MODE_MPMC!r}")
-        return
-    if subject == SCENE_SUBJECT_KV:
-        if mode not in (TEST_STACK_MODE_KVSTORE, TEST_STACK_MODE_KVSTORE_WITH_LOCAL_CACHE, TEST_STACK_MODE_RPC):
-            raise ValueError(f"{ctx} subject={subject!r} requires a KV-family mode")
-        return
-    if subject == SCENE_SUBJECT_FS:
-        if mode != TEST_STACK_MODE_PY_FS:
-            raise ValueError(f"{ctx} subject={subject!r} requires mode={TEST_STACK_MODE_PY_FS!r}")
-        return
-    raise ValueError(f"{ctx} unsupported test_stack subject: {subject!r}")
+def _parse_ci_requirements(raw_requirements: Any, ctx: str) -> List[str]:
+    requirements = _require_list(raw_requirements, ctx)
+    if not requirements:
+        raise ValueError(f"{ctx} must be non-empty")
+    out: List[str] = []
+    seen: set[str] = set()
+    for index, raw_requirement in enumerate(requirements):
+        requirement_id = _require_ci_requirement_id(raw_requirement, f"{ctx}[{index}]")
+        if requirement_id in seen:
+            raise ValueError(f"{ctx} contains duplicate requirement: {requirement_id!r}")
+        seen.add(requirement_id)
+        out.append(requirement_id)
+    if CI_REQUIREMENT_CI_RUNNER not in seen:
+        raise ValueError(f"{ctx} must include {CI_REQUIREMENT_CI_RUNNER!r}")
+    if CI_REQUIREMENT_OWNER_0 in seen and CI_REQUIREMENT_MASTER not in seen:
+        raise ValueError(f"{ctx} cannot include {CI_REQUIREMENT_OWNER_0!r} without {CI_REQUIREMENT_MASTER!r}")
+    return out
 
 
 def _parse_scene_value_size_weighted_set(raw_val: Any, *, ctx: str) -> List[Dict[str, Any]]:
@@ -6240,15 +6258,11 @@ def _parse_scene(item: Dict[str, Any], ctx: str) -> Dict[str, Any]:
     if kind == SCENE_KIND_CI:
         _forbid_unknown_keys(item, {"ci", "select"}, ctx)
         ci = _require_dict(item.get("ci"), f"{ctx}.ci")
-        _forbid_unknown_keys(ci, {"subject", "runtime_contract", "prepare"}, f"{ctx}.ci")
-        subject = _require_scene_subject(ci.get("subject"), f"{ctx}.ci.subject")
-        if subject == SCENE_SUBJECT_INFER:
-            raise ValueError(f"{ctx}.ci.subject must not be {SCENE_SUBJECT_INFER!r}")
+        _forbid_unknown_keys(ci, {"requirements", "prepare"}, f"{ctx}.ci")
         parsed_ci = {
-            "subject": subject,
-            "runtime_contract": _require_ci_runtime_contract(
-                ci.get("runtime_contract"),
-                f"{ctx}.ci.runtime_contract",
+            "requirements": _parse_ci_requirements(
+                ci.get("requirements"),
+                f"{ctx}.ci.requirements",
             ),
         }
         raw_prepare = ci.get("prepare")
@@ -6262,7 +6276,6 @@ def _parse_scene(item: Dict[str, Any], ctx: str) -> Dict[str, Any]:
     _forbid_unknown_keys(
         ts,
         {
-            "subject",
             "mode",
             "role_weights",
             "read_ratio",
@@ -6281,13 +6294,7 @@ def _parse_scene(item: Dict[str, Any], ctx: str) -> Dict[str, Any]:
         f"{ctx}.test_stack",
     )
     mode = _require_str(ts.get("mode"), f"{ctx}.test_stack.mode")
-    subject_raw = ts.get("subject")
-    subject = _infer_test_stack_subject_from_mode(mode)
-    if subject_raw is not None:
-        subject = _require_scene_subject(subject_raw, f"{ctx}.test_stack.subject")
-        _validate_test_stack_subject_mode(subject=subject, mode=mode, ctx=f"{ctx}.test_stack")
-
-    out_ts: Dict[str, Any] = {"subject": subject, "mode": mode}
+    out_ts: Dict[str, Any] = {"mode": mode}
     role_weights = ts.get("role_weights")
     if mode == TEST_STACK_MODE_MPMC:
         rw = _require_dict(role_weights, f"{ctx}.test_stack.role_weights")
@@ -6841,6 +6848,36 @@ def _validate_profile_ci_runtime_block(runtime: Dict[str, Any], ctx: str, target
             raise ValueError(f"{tpl_ctx}.endpoint must be omitted")
 
 
+def _validate_profile_ci_requirement_configs(
+    requirement_configs: Dict[str, Any],
+    *,
+    ctx: str,
+    target_ip_map: Dict[str, Any],
+) -> None:
+    _forbid_unknown_keys(requirement_configs, set(CI_REQUIREMENTS_WITH_PROFILE_CONFIG), ctx)
+
+    case_runtime: Dict[str, Any] = {}
+    for instance_id in (CI_REQUIREMENT_MASTER, CI_REQUIREMENT_OWNER_0, CI_REQUIREMENT_CI_RUNNER):
+        raw_cfg = requirement_configs.get(instance_id)
+        if raw_cfg is None:
+            continue
+        case_runtime[instance_id] = _require_dict(raw_cfg, f"{ctx}[{instance_id!r}]")
+    if case_runtime:
+        _validate_profile_ci_runtime_block(
+            {
+                RUNTIME_LAYER_BASE: {
+                    service_id: {
+                        "target": next(iter(target_ip_map.keys())),
+                        "endpoint": {"scheme": _ENDPOINT_SCHEME_HTTP, "host_port": 1},
+                    }
+                    for service_id in CI_BASE_RUNTIME_SERVICE_IDS
+                },
+                RUNTIME_LAYER_CASE: case_runtime,
+            },
+            f"{ctx}.__case_runtime_validation__",
+            target_ip_map,
+        )
+
 def _require_clean_relpath(raw: Any, ctx: str) -> str:
     relpath = _require_str(raw, ctx).strip()
     if not relpath:
@@ -7270,7 +7307,7 @@ def _parse_profile(item: Dict[str, Any], ctx: str) -> Dict[str, Any]:
 
     if runtime.get("ci") is not None:
         ci = _require_dict(runtime.get("ci"), f"{ctx}.runtime.ci")
-        _forbid_unknown_keys(ci, {"deploy", "runtime_contracts", "scene_configs"}, f"{ctx}.runtime.ci")
+        _forbid_unknown_keys(ci, {"deploy", "requirements", "scene_configs"}, f"{ctx}.runtime.ci")
         deploy = _require_dict(ci.get("deploy"), f"{ctx}.runtime.ci.deploy")
         _validate_profile_deploy_block(
             deploy,
@@ -7279,16 +7316,16 @@ def _parse_profile(item: Dict[str, Any], ctx: str) -> Dict[str, Any]:
             allow_target_tokens=False,
         )
         target_ip_map = _require_dict(deploy.get("target_ip_map"), f"{ctx}.runtime.ci.deploy.target_ip_map")
-        runtime_contracts = _require_dict(ci.get("runtime_contracts"), f"{ctx}.runtime.ci.runtime_contracts")
-        if not runtime_contracts:
-            raise ValueError(f"{ctx}.runtime.ci.runtime_contracts must be non-empty")
-        for contract_id, raw_runtime in runtime_contracts.items():
-            _ = _require_ci_runtime_contract(contract_id, f"{ctx}.runtime.ci.runtime_contracts key")
-            _validate_profile_ci_runtime_block(
-                _require_dict(raw_runtime, f"{ctx}.runtime.ci.runtime_contracts[{contract_id!r}]"),
-                f"{ctx}.runtime.ci.runtime_contracts[{contract_id!r}]",
-                target_ip_map,
-            )
+        raw_requirement_configs = ci.get("requirements")
+        if raw_requirement_configs is None:
+            requirement_configs = {}
+        else:
+            requirement_configs = _require_dict(raw_requirement_configs, f"{ctx}.runtime.ci.requirements")
+        _validate_profile_ci_requirement_configs(
+            requirement_configs,
+            ctx=f"{ctx}.runtime.ci.requirements",
+            target_ip_map=target_ip_map,
+        )
         scene_configs = ci.get("scene_configs")
         if scene_configs is not None:
             scene_configs = _require_dict(scene_configs, f"{ctx}.runtime.ci.scene_configs")
@@ -7441,24 +7478,44 @@ def _expand_cases(suite: _Suite) -> List[_ResolvedCase]:
                     if profile_runtime.get("ci") is None:
                         raise ValueError(f"scene[{scene_id}] kind={scene_kind} selects profile[{profile_id}] without ci block")
                     scene_ci = _require_dict(scene.get("ci"), f"scene[{scene_id}].ci")
-                    runtime_contract = _require_ci_runtime_contract(
-                        scene_ci.get("runtime_contract"),
-                        f"scene[{scene_id}].ci.runtime_contract",
+                    requirement_ids = _parse_ci_requirements(
+                        scene_ci.get("requirements"),
+                        f"scene[{scene_id}].ci.requirements",
                     )
                     profile_ci = _require_dict(profile_runtime.get("ci"), f"profile[{profile_id}].runtime.ci")
-                    runtime_contracts = _require_dict(
-                        profile_ci.get("runtime_contracts"),
-                        f"profile[{profile_id}].runtime.ci.runtime_contracts",
-                    )
-                    if runtime_contract not in runtime_contracts:
+                    raw_requirement_configs = profile_ci.get("requirements")
+                    if raw_requirement_configs is None:
+                        requirement_configs = {}
+                    else:
+                        requirement_configs = _require_dict(
+                            raw_requirement_configs,
+                            f"profile[{profile_id}].runtime.ci.requirements",
+                        )
+                    missing_requirements = [
+                        requirement_id
+                        for requirement_id in requirement_ids
+                        if requirement_id in CI_REQUIREMENTS_WITH_PROFILE_CONFIG and requirement_id not in requirement_configs
+                    ]
+                    if missing_requirements:
                         raise ValueError(
-                            f"scene[{scene_id}] runtime_contract={runtime_contract!r} is missing from profile[{profile_id}].runtime.ci.runtime_contracts"
+                            f"scene[{scene_id}] requirements {missing_requirements!r} are missing from "
+                            f"profile[{profile_id}].runtime.ci.requirements"
                         )
                 elif scene_kind == SCENE_KIND_TEST_STACK:
                     profile_ts = _require_dict(profile_runtime.get("test_stack"), f"profile[{profile_id}].runtime.test_stack")
+                    scene_ts = _require_dict(scene.get("test_stack"), f"scene[{scene_id}].test_stack")
+                    mode = _require_str(scene_ts.get("mode"), f"scene[{scene_id}].test_stack.mode")
+                    backend_kind = _require_test_stack_backend_kind(
+                        profile_ts.get("kind"),
+                        f"profile[{profile_id}].runtime.test_stack.kind",
+                    )
+                    _validate_test_stack_backend_mode(
+                        backend_kind=backend_kind,
+                        mode=mode,
+                        ctx=f"profile[{profile_id}].runtime.test_stack.kind",
+                    )
                     deploy = _require_dict(profile_ts.get("deploy"), f"profile[{profile_id}].runtime.test_stack.deploy")
                     target_ip_map = _require_dict(deploy.get("target_ip_map"), f"profile[{profile_id}].runtime.test_stack.deploy.target_ip_map")
-                    scene_ts = _require_dict(scene.get("test_stack"), f"scene[{scene_id}].test_stack")
                     role_plan = _build_test_stack_role_plan(
                         scene_ts,
                         scale,
@@ -7699,6 +7756,66 @@ def _runner_native_ci_commands_for_case(case: _ResolvedCase, *, ctx: str) -> Lis
                 "timeout_seconds": 21600,
             }
         ]
+    if scene_id == "ci_top_attention_config_kv":
+        return [
+            {
+                "id": "top_attention_config_kv",
+                "command": (
+                    "__RUN_DIR__/venv/bin/python3 -u "
+                    "__RUN_DIR__/src/fluxon_test_stack/top_attention_test_index/_config_kv.py "
+                    "--case-config __RUN_DIR__/configs/ci_scene_config.yaml"
+                ),
+                "timeout_seconds": 3600,
+            }
+        ]
+    if scene_id == "ci_top_attention_config_fs":
+        return [
+            {
+                "id": "top_attention_config_fs",
+                "command": (
+                    "__RUN_DIR__/venv/bin/python3 -u "
+                    "__RUN_DIR__/src/fluxon_test_stack/top_attention_test_index/_config_fs.py "
+                    "--case-config __RUN_DIR__/configs/ci_scene_config.yaml"
+                ),
+                "timeout_seconds": 3600,
+            }
+        ]
+    if scene_id == "ci_top_attention_config_mq":
+        return [
+            {
+                "id": "top_attention_config_mq",
+                "command": (
+                    "__RUN_DIR__/venv/bin/python3 -u "
+                    "__RUN_DIR__/src/fluxon_test_stack/top_attention_test_index/_config_mq.py "
+                    "--case-config __RUN_DIR__/configs/ci_scene_config.yaml"
+                ),
+                "timeout_seconds": 7200,
+            }
+        ]
+    if scene_id == "ci_top_attention_ctrl_c_kv":
+        return [
+            {
+                "id": "top_attention_ctrl_c_kv",
+                "command": (
+                    "__RUN_DIR__/venv/bin/python3 -u "
+                    "__RUN_DIR__/src/fluxon_test_stack/top_attention_test_index/_ctrl_c_kv.py "
+                    "--case-config __RUN_DIR__/configs/ci_scene_config.yaml"
+                ),
+                "timeout_seconds": 3600,
+            }
+        ]
+    if scene_id == "ci_top_attention_ctrl_c_mq":
+        return [
+            {
+                "id": "top_attention_ctrl_c_mq",
+                "command": (
+                    "__RUN_DIR__/venv/bin/python3 -u "
+                    "__RUN_DIR__/src/fluxon_test_stack/top_attention_test_index/_ctrl_c_mq.py "
+                    "--case-config __RUN_DIR__/configs/ci_scene_config.yaml"
+                ),
+                "timeout_seconds": 7200,
+            }
+        ]
     raise ValueError(f"{ctx} unsupported runner-native CI scene: {scene_id!r}")
 
 
@@ -8513,9 +8630,9 @@ def _build_resolved_case_yaml(
             raise ValueError(f"ci_commands must be provided for CI case: {case.case_id}")
 
         scene_ci = _require_dict(scene_src.get("ci"), "resolved_case.scene_source.ci")
-        runtime_contract = _require_ci_runtime_contract(
-            scene_ci.get("runtime_contract"),
-            "resolved_case.scene_source.ci.runtime_contract",
+        requirement_ids = _parse_ci_requirements(
+            scene_ci.get("requirements"),
+            "resolved_case.scene_source.ci.requirements",
         )
         topology = _require_test_stack_machine_count(scale_src.get("topology"), "resolved_case.scale_source.topology")
         targets = copy.deepcopy(_require_dict(scale_src.get("targets"), "resolved_case.scale_source.targets"))
@@ -8530,16 +8647,32 @@ def _build_resolved_case_yaml(
         deploy_out = copy.deepcopy(_require_dict(profile_ci.get("deploy"), "resolved_case.profile_source.ci.deploy"))
         deploy_out["release_root"] = materialized_release_root
         deploy_out["test_rsc_root"] = materialized_test_rsc_root
-        runtime_contracts = _require_dict(
-            profile_ci.get("runtime_contracts"),
-            "resolved_case.profile_source.ci.runtime_contracts",
-        )
-        selected_runtime = copy.deepcopy(
-            _require_dict(
-                runtime_contracts.get(runtime_contract),
-                f"resolved_case.profile_source.ci.runtime_contracts[{runtime_contract!r}]",
+        raw_requirement_configs = profile_ci.get("requirements")
+        if raw_requirement_configs is None:
+            requirement_configs = {}
+        else:
+            requirement_configs = _require_dict(
+                raw_requirement_configs,
+                "resolved_case.profile_source.ci.requirements",
             )
-        )
+        selected_requirement_configs: Dict[str, Any] = {}
+        selected_base_runtime: Dict[str, Any] = {}
+        selected_case_runtime: Dict[str, Any] = {}
+        for requirement_id in requirement_ids:
+            for service_id, service_requirement_id in CI_BASE_RUNTIME_REQUIREMENT_IDS.items():
+                if requirement_id == service_requirement_id:
+                    selected_base_runtime[service_id] = {}
+            if requirement_id not in CI_REQUIREMENTS_WITH_PROFILE_CONFIG:
+                continue
+            requirement_cfg = copy.deepcopy(
+                _require_dict(
+                    requirement_configs.get(requirement_id),
+                    f"resolved_case.profile_source.ci.requirements[{requirement_id!r}]",
+                )
+            )
+            selected_requirement_configs[requirement_id] = requirement_cfg
+            if requirement_id in CI_CASE_RUNTIME_INSTANCE_IDS:
+                selected_case_runtime[requirement_id] = requirement_cfg
         scene_configs = profile_ci.get("scene_configs")
         selected_scene_config = None
         if scene_configs is not None:
@@ -8555,8 +8688,7 @@ def _build_resolved_case_yaml(
 
         scene = {
             "ci": {
-                "subject": _require_scene_subject(scene_ci.get("subject"), "resolved_case.scene_source.ci.subject"),
-                "runtime_contract": runtime_contract,
+                "requirements": list(requirement_ids),
                 "commands": copy.deepcopy(ci_commands),
             }
         }
@@ -8566,8 +8698,11 @@ def _build_resolved_case_yaml(
         profile = {
             "deploy": deploy_out,
             "ci": {
-                "runtime_contract": runtime_contract,
-                "runtime": selected_runtime,
+                "requirements": selected_requirement_configs,
+                "runtime": {
+                    RUNTIME_LAYER_BASE: selected_base_runtime,
+                    RUNTIME_LAYER_CASE: selected_case_runtime,
+                },
             },
         }
         if selected_scene_config is not None:
@@ -8578,16 +8713,15 @@ def _build_resolved_case_yaml(
         duration_seconds = _require_int(scale_src.get("duration_seconds"), "scale.duration_seconds", min_v=1)
         topology = copy.deepcopy(scale_src.get("topology"))
         mode = _require_str(scene_ts.get("mode"), "scene.test_stack.mode")
-        subject = _require_scene_subject(scene_ts.get("subject"), "scene.test_stack.subject")
 
         profile_ts = _require_dict(profile_runtime_src.get("test_stack"), "resolved_case.profile_source.runtime.test_stack")
         backend_kind = _require_test_stack_backend_kind(
             profile_ts.get("kind"),
             "resolved_case.profile_source.test_stack.kind",
         )
-        _validate_test_stack_backend_subject(
+        _validate_test_stack_backend_mode(
             backend_kind=backend_kind,
-            subject=subject,
+            mode=mode,
             ctx="resolved_case.profile_source.test_stack.kind",
         )
         deploy_out = copy.deepcopy(_require_dict(profile_ts.get("deploy"), "resolved_case.profile_source.test_stack.deploy"))
@@ -8694,7 +8828,10 @@ def _build_resolved_case_yaml(
             "run_dir": run_dir,
             "stack_identity": stack_identity,
         },
-        "runtime_model": _build_runtime_model(case_family),
+        "runtime_model": _build_runtime_model(
+            case_family,
+            ci_requirement_ids=tuple(requirement_ids) if case_family == CASE_FAMILY_CI else None,
+        ),
         "artifact_set": {
             "id": artifact_set_id,
             "release_source": artifact_release_source,
@@ -9687,10 +9824,9 @@ def _compile_test_stack_case(resolved_case: Dict[str, Any], *, run_index: int) -
         ts_profile.get("runtime_env"),
         "resolved_case.profile.test_stack.runtime_env",
     )
-    scene_subject = _require_scene_subject(ts_scene.get("subject"), "resolved_case.scene.test_stack.subject")
-    _validate_test_stack_backend_subject(
+    _validate_test_stack_backend_mode(
         backend_kind=backend_kind,
-        subject=scene_subject,
+        mode=scene_mode,
         ctx="resolved_case.profile.test_stack.kind",
     )
     port_alloc = _require_dict(ts_profile.get("port_alloc"), "profile.test_stack.port_alloc")
@@ -11315,6 +11451,34 @@ def _active_test_stack_target_ip_map(*, ctx: str) -> Dict[str, str]:
     return out
 
 
+def _testbed_service_host_port(service_id: str, *, ctx: str) -> Tuple[str, int]:
+    deployconf_path = _load_test_bed_deployconf_path()
+    deployconf = _require_dict(_load_yaml_file(deployconf_path), f"deployconf {deployconf_path}")
+    services = _require_dict(deployconf.get("service"), "deployconf.service")
+    service = _require_dict(services.get(service_id), f"deployconf.service.{service_id}")
+    port = _require_int(service.get("port"), f"deployconf.service.{service_id}.port", min_v=1)
+    node_bind = _require_dict(service.get("node_bind"), f"deployconf.service.{service_id}.node_bind")
+    nodes = _require_list(node_bind.get("node"), f"deployconf.service.{service_id}.node_bind.node")
+    if not nodes:
+        raise ValueError(f"deployconf.service.{service_id}.node_bind.node must be non-empty")
+    hostname = _require_str(nodes[0], f"deployconf.service.{service_id}.node_bind.node[0]")
+    target_ip_map = _active_test_stack_target_ip_map(ctx=ctx)
+    ip = _require_str(target_ip_map.get(hostname), f"{ctx}.target_ip_map[{hostname!r}]")
+    return ip, int(port)
+
+
+def _testbed_service_target_name(service_id: str) -> str:
+    deployconf_path = _load_test_bed_deployconf_path()
+    deployconf = _require_dict(_load_yaml_file(deployconf_path), f"deployconf {deployconf_path}")
+    services = _require_dict(deployconf.get("service"), "deployconf.service")
+    service = _require_dict(services.get(service_id), f"deployconf.service.{service_id}")
+    node_bind = _require_dict(service.get("node_bind"), f"deployconf.service.{service_id}.node_bind")
+    nodes = _require_list(node_bind.get("node"), f"deployconf.service.{service_id}.node_bind.node")
+    if not nodes:
+        raise ValueError(f"deployconf.service.{service_id}.node_bind.node must be non-empty")
+    return _require_str(nodes[0], f"deployconf.service.{service_id}.node_bind.node[0]")
+
+
 def _test_stack_greptime_host_port(resolved_case: Dict[str, Any]) -> Tuple[str, int]:
     """Infer Greptime host:port for TEST_STACK master monitoring config from the self-host deployconf."""
     deployconf_path = _load_test_bed_deployconf_path()
@@ -14544,7 +14708,7 @@ def _ci_cluster_member_target_ips(resolved_case: Dict[str, Any]) -> List[str]:
 def _resolved_ci_command_list(resolved_case: Dict[str, Any]) -> List[Dict[str, str]]:
     scene = _require_dict(resolved_case.get("scene"), "resolved_case.scene")
     ci = _require_dict(scene.get("ci"), "resolved_case.scene.ci")
-    _forbid_unknown_keys(ci, {"subject", "commands", "runtime_contract", "prepare"}, "resolved_case.scene.ci")
+    _forbid_unknown_keys(ci, {"commands", "requirements", "prepare"}, "resolved_case.scene.ci")
     raw_commands = _require_list(ci.get("commands"), "resolved_case.scene.ci.commands")
     if not raw_commands:
         raise ValueError("resolved_case.scene.ci.commands must be non-empty")
@@ -14735,11 +14899,12 @@ def _ci_runner_exit_code_timeout_seconds(resolved_case: Dict[str, Any]) -> int:
     - Keep one causal source of truth: sum the explicit per-command timeouts and add the bounded pre-command phases
       that are also encoded in the generated script.
     """
-    timeout_seconds = (
-        CI_RUNNER_SHARED_BUNDLE_TIMEOUT_S
-        + CI_RUNNER_READINESS_PROBE_DEADLINE_S
-        + CI_RUNNER_EXIT_CODE_GRACE_TIMEOUT_S
-    )
+    timeout_seconds = CI_RUNNER_EXIT_CODE_GRACE_TIMEOUT_S
+    if _ci_has_instance(resolved_case, instance_id="owner_0"):
+        timeout_seconds += (
+            CI_RUNNER_SHARED_BUNDLE_TIMEOUT_S
+            + CI_RUNNER_READINESS_PROBE_DEADLINE_S
+        )
     commands = _resolved_ci_command_list(resolved_case)
     for index, command in enumerate(commands):
         raw_timeout = command.get("timeout_seconds")
@@ -14766,7 +14931,7 @@ def _write_ci_runner_script(
     commands = _resolved_ci_command_list(resolved_case)
     venv_python = run_dir / "venv" / "bin" / "python3"
     test_backend = (src_root / "fluxon_py" / "tests" / "test_backend.py").resolve()
-    requires_owner_shared_bundle = _ci_has_instance(resolved_case, instance_id="owner_0")
+    requires_owner_runtime = _ci_has_instance(resolved_case, instance_id="owner_0")
 
     out_path = run_dir / "ci_runner.sh"
     if out_path.exists():
@@ -14800,7 +14965,7 @@ def _write_ci_runner_script(
 
     shared_bundle_block = ""
     readiness_probe_block = ""
-    if requires_owner_shared_bundle:
+    if requires_owner_runtime:
         bundle_cluster_name = _ci_cluster_name(resolved_case)
         bundle_shared_memory_dir = str(
             _cluster_scoped_shared_dir(root_path=share_mem_path, cluster_name=bundle_cluster_name)
@@ -14829,6 +14994,9 @@ def _write_ci_runner_script(
   fail_and_exit 2
 fi
 """
+    if requires_owner_runtime:
+        readiness_test_id = "basic_put_and_get"
+        readiness_instance_suffix = "readiness_probe"
         readiness_probe_block = f"""
 echo "[ci_runner] running backend readiness probe..."
 readiness_rc=1
@@ -14836,11 +15004,11 @@ def _write_ci_runner_script(
 readiness_deadline=$(( $(date +%s) + {CI_RUNNER_READINESS_PROBE_DEADLINE_S} ))
 while [ $(date +%s) -lt "$readiness_deadline" ]; do
   readiness_attempt=$((readiness_attempt + 1))
-  echo "[CI readiness_probe] attempt=$readiness_attempt argv={venv_python.as_posix()} -u {test_backend.as_posix()} --test-id basic_put_and_get --instance-suffix readiness_probe"
-  timeout --preserve-status --signal=KILL 60 {venv_python.as_posix()} -u {test_backend.as_posix()} --test-id basic_put_and_get --instance-suffix readiness_probe
+  echo "[CI readiness_probe] attempt=$readiness_attempt argv={venv_python.as_posix()} -u {test_backend.as_posix()} --test-id {readiness_test_id} --instance-suffix {readiness_instance_suffix}"
+  timeout --preserve-status --signal=KILL 60 {venv_python.as_posix()} -u {test_backend.as_posix()} --test-id {readiness_test_id} --instance-suffix {readiness_instance_suffix}
   readiness_rc=$?
   if [ "$readiness_rc" -eq 0 ]; then
-    echo "[CI readiness_probe] basic_put_and_get passed on attempt=$readiness_attempt"
+    echo "[CI readiness_probe] {readiness_test_id} passed on attempt=$readiness_attempt"
     break
   fi
   echo "[CI readiness_probe] failed rc=$readiness_rc attempt=$readiness_attempt"
diff --git a/fluxon_test_stack/tests/test_ci_2_virt_node_contract.py b/fluxon_test_stack/tests/test_ci_2_virt_node_contract.py
index 667c00b..afaab90 100644
--- a/fluxon_test_stack/tests/test_ci_2_virt_node_contract.py
+++ b/fluxon_test_stack/tests/test_ci_2_virt_node_contract.py
@@ -29,6 +29,11 @@ def _load_module():
 class TestCi2VirtNodeContract(unittest.TestCase):
     _KVTEST_SCENE_ID = "ci_top_attention_bin_kvtest"
     _DOC_SCENE_ID = "ci_top_attention_doc_page_build"
+    _CONFIG_KV_SCENE_ID = "ci_top_attention_config_kv"
+    _CONFIG_FS_SCENE_ID = "ci_top_attention_config_fs"
+    _CONFIG_MQ_SCENE_ID = "ci_top_attention_config_mq"
+    _CTRL_C_KV_SCENE_ID = "ci_top_attention_ctrl_c_kv"
+    _CTRL_C_MQ_SCENE_ID = "ci_top_attention_ctrl_c_mq"
 
     def test_generated_suite_is_public_dual_local_nodes_ci_only(self) -> None:
         suite_cfg = _ENTRY._load_yaml_mapping(_ENTRY.DEFAULT_SUITE_PATH, ctx="suite")
@@ -55,17 +60,13 @@ def test_generated_suite_is_public_dual_local_nodes_ci_only(self) -> None:
             generated["profiles"]["fluxon_tcp_thread"]["runtime"]["ci"]["deploy"]["target_ip_map"],
             {"local-node-a": "10.1.1.119", "local-node-b": "10.1.1.119"},
         )
-        self.assertEqual(
-            generated["profiles"]["fluxon_tcp_thread"]["runtime"]["ci"]["runtime_contracts"]["cluster_kv_owner"][
-                "base_runtime"
-            ]["etcd"]["endpoint"]["host_port"],
-            19180,
+        self.assertNotIn(
+            "testbed_etcd",
+            generated["profiles"]["fluxon_tcp_thread"]["runtime"]["ci"]["requirements"],
         )
-        self.assertEqual(
-            generated["profiles"]["fluxon_tcp_thread"]["runtime"]["ci"]["runtime_contracts"]["cluster_kv_owner"][
-                "base_runtime"
-            ]["greptime"]["endpoint"]["host_port"],
-            19190,
+        self.assertNotIn(
+            "testbed_greptime",
+            generated["profiles"]["fluxon_tcp_thread"]["runtime"]["ci"]["requirements"],
         )
         self.assertEqual(
             generated["artifact_sets"]["fluxon_tcp_thread"]["release_source"]["key_prefix"],
@@ -154,8 +155,8 @@ def test_generated_suite_supports_doc_page_ci_scene(self) -> None:
 
         self.assertEqual(set(generated["scenes"].keys()), {self._DOC_SCENE_ID})
         self.assertEqual(
-            generated["scenes"][self._DOC_SCENE_ID]["ci"]["runtime_contract"],
-            "rust_self_managed",
+            generated["scenes"][self._DOC_SCENE_ID]["ci"]["requirements"],
+            ["ci_runner"],
         )
         prepare = generated["scenes"][self._DOC_SCENE_ID]["ci"]["prepare"]
         self.assertEqual(
@@ -175,6 +176,49 @@ def test_generated_suite_supports_doc_page_ci_scene(self) -> None:
         )
         self.assertEqual(set(generated["scales"].keys()), {"n1_kvowner_dram_3gib"})
 
+    def test_generated_suite_supports_top_attention_config_and_ctrl_c_ci_scenes(self) -> None:
+        suite_cfg = _ENTRY._load_yaml_mapping(_ENTRY.DEFAULT_SUITE_PATH, ctx="suite")
+        scene_ids = [
+            self._CONFIG_KV_SCENE_ID,
+            self._CONFIG_FS_SCENE_ID,
+            self._CONFIG_MQ_SCENE_ID,
+            self._CTRL_C_KV_SCENE_ID,
+            self._CTRL_C_MQ_SCENE_ID,
+        ]
+
+        generated = _ENTRY._rewrite_suite_for_local_dual_nodes(
+            suite_cfg=suite_cfg,
+            scene_ids=scene_ids,
+            primary_node_name="local-node-a",
+            secondary_node_name="local-node-b",
+            host_ip="10.1.1.119",
+            wheel_name="fluxon-0.2.1-cp38-abi3-manylinux_2_28_x86_64.whl",
+            controller_port=19080,
+        )
+
+        self.assertEqual(set(generated["scenes"].keys()), set(scene_ids))
+        self.assertEqual(set(generated["scales"].keys()), {"n1_kvowner_dram_3gib"})
+        self.assertEqual(
+            generated["profiles"]["fluxon_tcp_thread"]["runtime"]["ci"]["scene_configs"][self._CONFIG_KV_SCENE_ID],
+            {},
+        )
+        self.assertEqual(
+            generated["profiles"]["fluxon_tcp_thread"]["runtime"]["ci"]["scene_configs"][self._CTRL_C_MQ_SCENE_ID],
+            {},
+        )
+        self.assertEqual(
+            generated["scenes"][self._CONFIG_MQ_SCENE_ID]["ci"]["requirements"],
+            ["ci_runner", "master", "owner_0", "testbed_etcd", "testbed_greptime"],
+        )
+        self.assertEqual(
+            generated["scenes"][self._CTRL_C_KV_SCENE_ID]["ci"]["requirements"],
+            ["ci_runner"],
+        )
+        self.assertEqual(
+            generated["scenes"][self._CTRL_C_MQ_SCENE_ID]["ci"]["requirements"],
+            ["ci_runner", "testbed_etcd", "testbed_greptime"],
+        )
+
     def test_generated_deployconf_rewrites_to_dual_local_nodes(self) -> None:
         deployconf_cfg = _ENTRY._load_yaml_mapping(_ENTRY.DEFAULT_DEPLOYCONF_TEMPLATE, ctx="deployconf")
         generated = _ENTRY._rewrite_deployconf_for_local_dual_nodes(
diff --git a/fluxon_test_stack/tests/test_test_runner_testbed_contract.py b/fluxon_test_stack/tests/test_test_runner_testbed_contract.py
index 6910acd..de55b7c 100644
--- a/fluxon_test_stack/tests/test_test_runner_testbed_contract.py
+++ b/fluxon_test_stack/tests/test_test_runner_testbed_contract.py
@@ -65,7 +65,7 @@ def test_write_ci_scene_config_yaml_emits_structured_scene_config(self) -> None:
                         },
                         "scene_config": {
                             "doc_site_base_url": "tele-ai.github.io/Fluxon",
-                        }
+                        },
                     }
                 },
             }
@@ -104,6 +104,35 @@ def test_top_attention_ci_execution_plan_is_runner_native(self) -> None:
         self.assertEqual(planned[0].ci_commands[0]["id"], "top_attention_bin_kvtest")
         self.assertIn("--case-config __RUN_DIR__/configs/ci_scene_config.yaml", planned[0].ci_commands[0]["command"])
 
+    def test_top_attention_config_and_ctrl_c_ci_execution_plan_is_runner_native(self) -> None:
+        suite_cfg = yaml.safe_load((_RUNNER.RUNNER_REPO_ROOT / "fluxon_test_stack" / "ci_test_list.yaml").read_text(encoding="utf-8"))
+        artifact_sets = suite_cfg.get("artifact_sets")
+        if isinstance(artifact_sets, dict):
+            for artifact_set in artifact_sets.values():
+                if not isinstance(artifact_set, dict):
+                    continue
+                release_artifacts = artifact_set.get("release_artifacts")
+                if isinstance(release_artifacts, dict):
+                    python_wheel = release_artifacts.get("python_wheel")
+                    if isinstance(python_wheel, str) and python_wheel.strip():
+                        artifact_set["release_artifacts"] = {"wheel": python_wheel}
+        suite = _RUNNER._parse_suite_config(suite_cfg)
+        cases = _RUNNER._expand_cases(suite)
+        expected = {
+            "ci_top_attention_config_kv": "top_attention_config_kv",
+            "ci_top_attention_config_fs": "top_attention_config_fs",
+            "ci_top_attention_config_mq": "top_attention_config_mq",
+            "ci_top_attention_ctrl_c_kv": "top_attention_ctrl_c_kv",
+            "ci_top_attention_ctrl_c_mq": "top_attention_ctrl_c_mq",
+        }
+
+        for scene_id, command_id in expected.items():
+            case = next(item for item in cases if item.scene_id == scene_id and item.profile_id == "fluxon_tcp")
+            planned = _RUNNER._build_ci_execution_plan(case, suite)
+            self.assertEqual(len(planned), 1)
+            self.assertEqual(planned[0].ci_commands[0]["id"], command_id)
+            self.assertIn("--case-config __RUN_DIR__/configs/ci_scene_config.yaml", planned[0].ci_commands[0]["command"])
+
     def test_doc_page_ci_execution_plan_uses_online_docker_image(self) -> None:
         suite_cfg = yaml.safe_load((_RUNNER.RUNNER_REPO_ROOT / "fluxon_test_stack" / "ci_test_list.yaml").read_text(encoding="utf-8"))
         artifact_sets = suite_cfg.get("artifact_sets")
@@ -234,8 +263,7 @@ def test_ci_runner_script_sources_prepare_env_when_present(self) -> None:
                 },
                 "scene": {
                     "ci": {
-                        "subject": "doc_page",
-                        "runtime_contract": "rust_self_managed",
+                        "requirements": ["ci_runner"],
                         "commands": [
                             {
                                 "id": "doc_page_build",
@@ -493,6 +521,10 @@ def test_load_source_stack_contract_accepts_same_host_dual_local_hostworkdirs(se
                         "    ssh_user: tester",
                         "    ssh_port: 22",
                         "service:",
+                        "  greptime:",
+                        "    port: 19295",
+                        "    node_bind:",
+                        "      node: [logic-a]",
                         "  ops_controller:",
                         "    node_bind:",
                         "      node: [logic-a]",
@@ -605,6 +637,10 @@ def test_ci_base_runtime_service_target_ip_uses_loopback_for_same_host_local_nod
                         "    ssh_user: tester",
                         "    ssh_port: 22",
                         "service:",
+                        "  greptime:",
+                        "    port: 19295",
+                        "    node_bind:",
+                        "      node: [logic-a]",
                         "  ops_controller:",
                         "    node_bind:",
                         "      node: [logic-a]",
@@ -620,12 +656,7 @@ def test_ci_base_runtime_service_target_ip_uses_loopback_for_same_host_local_nod
                 "profile": {
                     "ci": {
                         "runtime": {
-                            "base_runtime": {
-                                "greptime": {
-                                    "target": "logic-a",
-                                    "endpoint": {"scheme": "http", "host_port": 19295},
-                                }
-                            }
+                            "base_runtime": {}
                         }
                     }
                 },
diff --git a/fluxon_test_stack/tests/test_test_runner_top_attention_cli.py b/fluxon_test_stack/tests/test_test_runner_top_attention_cli.py
index 16a999e..95a3afe 100644
--- a/fluxon_test_stack/tests/test_test_runner_top_attention_cli.py
+++ b/fluxon_test_stack/tests/test_test_runner_top_attention_cli.py
@@ -45,8 +45,8 @@ def test_top_attention_list_text_prefix(self) -> None:
         )
         self.assertEqual(completed.returncode, 0, msg=completed.stderr)
         requirements = {line.strip() for line in completed.stdout.splitlines() if line.strip()}
-        self.assertIn("ops", requirements)
-        self.assertIn("kv-cluster", requirements)
+        self.assertIn("ci_runner", requirements)
+        self.assertIn("master", requirements)
 
     def test_top_attention_run_requires_selector(self) -> None:
         completed = self.run_runner("--action", "top_attention_run")
diff --git a/fluxon_test_stack/tests/test_top_attention_index_helper.py b/fluxon_test_stack/tests/test_top_attention_index_helper.py
index dcec087..6fd0d72 100644
--- a/fluxon_test_stack/tests/test_top_attention_index_helper.py
+++ b/fluxon_test_stack/tests/test_top_attention_index_helper.py
@@ -19,7 +19,7 @@
     select_top_attention_entries,
     top_attention_scene_id,
 )
-from fluxon_test_stack.top_attention_test_index.requirements_all import iter_index_entry_paths
+from fluxon_test_stack.top_attention_test_index.test_test_requirements import iter_index_entry_paths
 
 
 class TestTopAttentionIndexHelper(unittest.TestCase):
@@ -45,8 +45,8 @@ def test_collect_payload_reports_requirements(self) -> None:
         payload = collect_top_attention_payload(["_config_kv"])
         self.assertEqual(payload["entry_count"], 1)
         self.assertEqual(payload["entries"][0]["name"], "_config_kv.py")
-        self.assertEqual(payload["entries"][0]["requirements"], ["ops"])
-        self.assertEqual(payload["requirements"], ["ops"])
+        self.assertEqual(payload["entries"][0]["requirements"], ["ci_runner"])
+        self.assertEqual(payload["requirements"], ["ci_runner"])
 
     def test_quick_entries_exist_and_match_declared_order(self) -> None:
         names = [path.name for path in iter_quick_entry_paths()]
diff --git a/fluxon_test_stack/tests/test_top_attention_wrapper_case_config_contract.py b/fluxon_test_stack/tests/test_top_attention_wrapper_case_config_contract.py
new file mode 100644
index 0000000..1b3d834
--- /dev/null
+++ b/fluxon_test_stack/tests/test_top_attention_wrapper_case_config_contract.py
@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import yaml
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _load_module(relpath: str, module_name: str):
+    module_path = REPO_ROOT / relpath
+    module_dir = module_path.parent
+    sys.path.insert(0, str(module_dir))
+    try:
+        spec = importlib.util.spec_from_file_location(module_name, module_path)
+        assert spec is not None and spec.loader is not None
+        mod = importlib.util.module_from_spec(spec)
+        sys.modules[spec.name] = mod
+        spec.loader.exec_module(mod)
+        return mod
+    finally:
+        if sys.path and sys.path[0] == str(module_dir):
+            sys.path.pop(0)
+
+
+class TestTopAttentionWrapperCaseConfigContract(unittest.TestCase):
+    def _case_cfg_path(self, *, scene_id: str) -> Path:
+        td = tempfile.TemporaryDirectory()
+        self.addCleanup(td.cleanup)
+        cfg_path = Path(td.name) / "ci_scene_config.yaml"
+        cfg_path.write_text(
+            yaml.safe_dump(
+                {
+                    "case": {
+                        "scene_id": scene_id,
+                        "scale_id": "n1_kvowner_dram_3gib",
+                        "profile_id": "fluxon_tcp_thread",
+                        "case_id": f"{scene_id}__n1_kvowner_dram_3gib__fluxon_tcp_thread",
+                    },
+                    "scene_config": {},
+                    "scene_runtime": {
+                        "etcd": {"ip": "127.0.0.1", "port": 19180},
+                        "greptime": {"ip": "127.0.0.1", "port": 19190},
+                    },
+                },
+                sort_keys=False,
+            ),
+            encoding="utf-8",
+        )
+        return cfg_path
+
+    def test_config_kv_wrapper_accepts_case_config_without_forwarding_it(self) -> None:
+        entry = _load_module(
+            "fluxon_test_stack/top_attention_test_index/_config_kv.py",
+            "fluxon_test_stack_top_attention_config_kv_contract",
+        )
+        cfg_path = self._case_cfg_path(scene_id="ci_top_attention_config_kv")
+        with (
+            mock.patch.object(entry, "run_python_file", return_value=0) as run_python_file,
+            mock.patch.object(sys, "argv", ["_config_kv.py", "--case-config", str(cfg_path)]),
+        ):
+            self.assertEqual(entry.main(), 0)
+        self.assertEqual(run_python_file.call_args.kwargs["expected_scene_id"], "ci_top_attention_config_kv")
+
+    def test_config_mq_wrapper_accepts_case_config_without_forwarding_it(self) -> None:
+        entry = _load_module(
+            "fluxon_test_stack/top_attention_test_index/_config_mq.py",
+            "fluxon_test_stack_top_attention_config_mq_contract",
+        )
+        cfg_path = self._case_cfg_path(scene_id="ci_top_attention_config_mq")
+        with (
+            mock.patch.object(entry, "run_pytest", return_value=0) as run_pytest,
+            mock.patch.object(sys, "argv", ["_config_mq.py", "--case-config", str(cfg_path)]),
+        ):
+            self.assertEqual(entry.main(), 0)
+        self.assertEqual(run_pytest.call_args.kwargs["expected_scene_id"], "ci_top_attention_config_mq")
+
+    def test_ctrl_c_mq_wrapper_accepts_case_config_without_forwarding_it(self) -> None:
+        entry = _load_module(
+            "fluxon_test_stack/top_attention_test_index/_ctrl_c_mq.py",
+            "fluxon_test_stack_top_attention_ctrl_c_mq_contract",
+        )
+        cfg_path = self._case_cfg_path(scene_id="ci_top_attention_ctrl_c_mq")
+        with (
+            mock.patch.object(entry, "run_python_file", return_value=0) as run_python_file,
+            mock.patch.object(sys, "argv", ["_ctrl_c_mq.py", "--case-config", str(cfg_path)]),
+        ):
+            self.assertEqual(entry.main(), 0)
+        self.assertEqual(run_python_file.call_args.kwargs["expected_scene_id"], "ci_top_attention_ctrl_c_mq")
+
+
+if __name__ == "__main__":
+    raise SystemExit(unittest.main())
diff --git a/fluxon_test_stack/top_attention_index_helper.py b/fluxon_test_stack/top_attention_index_helper.py
index 24bc465..4ad2858 100644
--- a/fluxon_test_stack/top_attention_index_helper.py
+++ b/fluxon_test_stack/top_attention_index_helper.py
@@ -5,23 +5,14 @@
 from pathlib import Path
 from typing import Any, Iterable, Sequence
 
-try:
-    from fluxon_test_stack.top_attention_test_index.requirements_all import (
-        TEST_REQUIREMENT_DESCRIPTIONS,
-        extract_test_requirements,
-        iter_index_entry_paths,
-    )
-except ModuleNotFoundError:
-    from top_attention_test_index.requirements_all import (  # type: ignore[no-redef]
-        TEST_REQUIREMENT_DESCRIPTIONS,
-        extract_test_requirements,
-        iter_index_entry_paths,
-    )
+import yaml
 
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 TOP_ATTENTION_INDEX_DIR = REPO_ROOT / "fluxon_test_stack" / "top_attention_test_index"
+TOP_ATTENTION_SUITE_PATH = REPO_ROOT / "fluxon_test_stack" / "ci_test_list.yaml"
 TOP_ATTENTION_SCENE_ID_PREFIX = "ci_top_attention_"
+IGNORED_INDEX_ENTRY_NAMES: frozenset[str] = frozenset({"_common.py"})
 QUICK_ENTRY_NAMES: tuple[str, ...] = (
     "_doc_page_build.py",
     "_config_kv.py",
@@ -33,6 +24,33 @@
     "_script_tools.py",
     "_cargo_fs_core.py",
 )
+TEST_REQUIREMENT_DESCRIPTIONS: dict[str, str] = {
+    "cargo": "Rust cargo toolchain is required.",
+    "docker": "A working Docker daemon is required.",
+    "fluxon-pyo3": "The compiled fluxon_pyo3 Python extension must be available.",
+    "fluxon-release": "The local fluxon_release runtime/artifact tree must be populated.",
+    "kv-cluster": "A configured KV backend runtime from the repo test config must be reachable.",
+    "ops": "A reachable Fluxon Ops control plane is required by the test-stack execution flow.",
+    "python-wheel-build": "Python wheel build dependencies must be available.",
+    "submodules": "Required git submodules must be initialized for build-using tests.",
+    "test-stack-targets": "A TEST_STACK config with reachable target hosts is required.",
+    "tikv": "A TiKV/PD runtime is required, either external or started by the test.",
+    "testbed_etcd": "The shared testbed etcd service must already be running.",
+    "testbed_greptime": "The shared testbed Greptime service must already be running.",
+    "master": "The runner must start a Fluxon master instance for the case.",
+    "owner_0": "The runner must start owner_0 for the case.",
+    "ci_runner": "The runner must start the ci_runner workload for the case.",
+    "owner_shared_bundle": "The runner must wait for owner shared bundle files before executing the case.",
+    "fluxon_kv_readiness_probe": "The runner must pass the configured Fluxon KV readiness probe before executing the case.",
+}
+
+
+def iter_index_entry_paths() -> tuple[Path, ...]:
+    return tuple(
+        path
+        for path in sorted(TOP_ATTENTION_INDEX_DIR.glob("*.py"))
+        if path.name.startswith("_") and path.name not in IGNORED_INDEX_ENTRY_NAMES
+    )
 
 
 def display_top_attention_relpath(path: Path) -> str:
@@ -46,6 +64,36 @@ def top_attention_scene_id(path: Path) -> str:
     return TOP_ATTENTION_SCENE_ID_PREFIX + path.stem.lstrip("_")
 
 
+def _load_top_attention_suite_scenes() -> dict[str, Any]:
+    raw = yaml.safe_load(TOP_ATTENTION_SUITE_PATH.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError(f"top-attention suite must be a YAML mapping: {TOP_ATTENTION_SUITE_PATH}")
+    scenes = raw.get("scenes")
+    if not isinstance(scenes, dict):
+        raise ValueError(f"top-attention suite scenes must be a mapping: {TOP_ATTENTION_SUITE_PATH}")
+    return scenes
+
+
+def _scene_requirements_for_path(path: Path) -> list[str]:
+    scene_id = top_attention_scene_id(path)
+    scenes = _load_top_attention_suite_scenes()
+    scene = scenes.get(scene_id)
+    if not isinstance(scene, dict):
+        return []
+    ci = scene.get("ci")
+    if not isinstance(ci, dict):
+        return []
+    requirements = ci.get("requirements")
+    if not isinstance(requirements, list):
+        return []
+    out: list[str] = []
+    for index, raw_requirement in enumerate(requirements):
+        if not isinstance(raw_requirement, str) or not raw_requirement.strip():
+            raise ValueError(f"scene[{scene_id}].ci.requirements[{index}] must be a non-empty string")
+        out.append(raw_requirement.strip())
+    return sorted(set(out))
+
+
 def match_top_attention_prefix(path: Path, raw_prefix: str) -> bool:
     prefix = raw_prefix.strip()
     if not prefix:
@@ -82,7 +130,7 @@ def select_top_attention_entries(prefixes: Sequence[str]) -> list[Path]:
 def collect_top_attention_requirements(paths: Iterable[Path]) -> list[str]:
     requirements: set[str] = set()
     for path in paths:
-        requirements.update(extract_test_requirements(path))
+        requirements.update(_scene_requirements_for_path(path))
     return sorted(requirements)
 
 
@@ -95,7 +143,7 @@ def collect_top_attention_payload(prefixes: Sequence[str] | None = None) -> dict
                 "id": path.stem,
                 "name": path.name,
                 "path": display_top_attention_relpath(path),
-                "requirements": sorted(extract_test_requirements(path)),
+                "requirements": _scene_requirements_for_path(path),
             }
         )
     return {
@@ -145,11 +193,13 @@ def print_top_attention_payload(payload: dict[str, Any], *, requirements_only: b
 
 
 __all__ = [
+    "IGNORED_INDEX_ENTRY_NAMES",
     "QUICK_ENTRY_NAMES",
     "TOP_ATTENTION_SCENE_ID_PREFIX",
     "collect_top_attention_payload",
     "collect_top_attention_requirements",
     "display_top_attention_relpath",
+    "iter_index_entry_paths",
     "iter_quick_entry_paths",
     "match_top_attention_prefix",
     "print_top_attention_payload",
diff --git a/fluxon_test_stack/top_attention_test_index/README.md b/fluxon_test_stack/top_attention_test_index/README.md
index 516c07e..50514a2 100644
--- a/fluxon_test_stack/top_attention_test_index/README.md
+++ b/fluxon_test_stack/top_attention_test_index/README.md
@@ -5,11 +5,11 @@ that now lives under `fluxon_test_stack/`. The entries stay thin: they forward
 to canonical tests elsewhere in the repository instead of implementing new test
 logic.
 
-Each `*.py` entry here declares a sorted `TEST_REQUIREMENTS` list. The full
-requirement universe lives in `requirements_all.py`, and `_test_requirements.py`
-checks that per-entry declarations stay within that universe and fully cover it.
-All indexed items now declare `ops` because execution is expected to go through
-the shared Fluxon Ops / test-stack path.
+Top-attention requirement metadata now lives only in
+`fluxon_test_stack/ci_test_list.yaml` under each `ci_top_attention_*` scene's
+`scene.ci.requirements`. `_test_requirements.py` checks that every indexed entry
+has a matching CI scene and that the YAML-backed requirement lists stay
+normalized.
 
 This directory is listing-only. Runtime orchestration, status, and log UI are
 owned by the `fluxon_test_stack` flow, not by this index directory. Listing and
diff --git a/fluxon_test_stack/top_attention_test_index/_bin_external_client.py b/fluxon_test_stack/top_attention_test_index/_bin_external_client.py
index b3f0b50..9ccd14c 100755
--- a/fluxon_test_stack/top_attention_test_index/_bin_external_client.py
+++ b/fluxon_test_stack/top_attention_test_index/_bin_external_client.py
@@ -7,8 +7,6 @@
 from _common import REPO_ROOT, run_cargo
 
 
-TEST_REQUIREMENTS = ["cargo", "etcd", "ops", "submodules"]
-
 
 def main() -> int:
     parser = argparse.ArgumentParser(
diff --git a/fluxon_test_stack/top_attention_test_index/_bin_kvtest.py b/fluxon_test_stack/top_attention_test_index/_bin_kvtest.py
index faddb51..3dfe01d 100644
--- a/fluxon_test_stack/top_attention_test_index/_bin_kvtest.py
+++ b/fluxon_test_stack/top_attention_test_index/_bin_kvtest.py
@@ -10,7 +10,6 @@
 from _common import REPO_ROOT, load_case_config_payload, run_cargo
 
 
-TEST_REQUIREMENTS = ["cargo", "etcd", "ops", "submodules"]
 SCENE_ID = "ci_top_attention_bin_kvtest"
 KV_TEST_ROUND_NAMES = ("p2p_only", "rdma_transfer_only", "rdma_transfer_with_rpc")
 
diff --git a/fluxon_test_stack/top_attention_test_index/_cargo_fs_core.py b/fluxon_test_stack/top_attention_test_index/_cargo_fs_core.py
index cbca6f5..0cf9bf2 100755
--- a/fluxon_test_stack/top_attention_test_index/_cargo_fs_core.py
+++ b/fluxon_test_stack/top_attention_test_index/_cargo_fs_core.py
@@ -4,8 +4,6 @@
 from _common import REPO_ROOT, run_cargo
 
 
-TEST_REQUIREMENTS = ["cargo", "ops", "submodules"]
-
 
 def main() -> int:
     return run_cargo([
diff --git a/fluxon_test_stack/top_attention_test_index/_cargo_kv_unit.py b/fluxon_test_stack/top_attention_test_index/_cargo_kv_unit.py
index 36ae5ff..8b1875b 100755
--- a/fluxon_test_stack/top_attention_test_index/_cargo_kv_unit.py
+++ b/fluxon_test_stack/top_attention_test_index/_cargo_kv_unit.py
@@ -7,8 +7,6 @@
 from _common import REPO_ROOT, run_cargo
 
 
-TEST_REQUIREMENTS = ["cargo", "etcd", "ops", "submodules"]
-
 
 def main() -> int:
     parser = argparse.ArgumentParser(
diff --git a/fluxon_test_stack/top_attention_test_index/_cargo_util.py b/fluxon_test_stack/top_attention_test_index/_cargo_util.py
index 2e707c8..73c1656 100755
--- a/fluxon_test_stack/top_attention_test_index/_cargo_util.py
+++ b/fluxon_test_stack/top_attention_test_index/_cargo_util.py
@@ -4,8 +4,6 @@
 from _common import REPO_ROOT, run_cargo
 
 
-TEST_REQUIREMENTS = ["cargo", "etcd", "ops", "submodules"]
-
 
 def main() -> int:
     return run_cargo([
diff --git a/fluxon_test_stack/top_attention_test_index/_common.py b/fluxon_test_stack/top_attention_test_index/_common.py
index 3991aa7..f26953b 100755
--- a/fluxon_test_stack/top_attention_test_index/_common.py
+++ b/fluxon_test_stack/top_attention_test_index/_common.py
@@ -13,37 +13,73 @@
 
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
-TEST_REQUIREMENTS: list[str] = ["ops"]
-
 
 def call(cmd: Sequence[str], *, env: dict[str, str] | None = None) -> int:
     print("+ " + " ".join(cmd), flush=True)
     return subprocess.call(list(cmd), cwd=str(REPO_ROOT), env=env)
 
 
-def parse_python_passthrough(description: str) -> tuple[str, list[str]]:
+def parse_python_passthrough(
+    description: str,
+    *,
+    expected_scene_id: str | None = None,
+) -> tuple[str, list[str], dict | None]:
     parser = argparse.ArgumentParser(description=description)
     parser.add_argument(
         "--python",
         default=os.environ.get("PYTHON", sys.executable),
         help="Python executable used for the delegated command.",
     )
+    parser.add_argument(
+        "--case-config",
+        help="Canonical CI case config YAML emitted by test_runner.",
+    )
     args, passthrough = parser.parse_known_args()
-    return args.python, passthrough
-
-
-def run_pytest(description: str, paths: Iterable[str]) -> int:
-    python, passthrough = parse_python_passthrough(description)
+    scene_config = None
+    if args.case_config is not None:
+        if expected_scene_id is None:
+            raise ValueError("--case-config is only supported for CI-bound top-attention wrappers")
+        scene_config = load_case_config(args.case_config, expected_scene_id=expected_scene_id)
+    return args.python, passthrough, scene_config
+
+
+def run_pytest(
+    description: str,
+    paths: Iterable[str],
+    *,
+    expected_scene_id: str | None = None,
+) -> int:
+    python, passthrough, _scene_config = parse_python_passthrough(
+        description,
+        expected_scene_id=expected_scene_id,
+    )
     return call([python, "-m", "pytest", *paths, *passthrough])
 
 
-def run_python_file(description: str, path: str, extra_args: Iterable[str] = ()) -> int:
-    python, passthrough = parse_python_passthrough(description)
+def run_python_file(
+    description: str,
+    path: str,
+    extra_args: Iterable[str] = (),
+    *,
+    expected_scene_id: str | None = None,
+) -> int:
+    python, passthrough, _scene_config = parse_python_passthrough(
+        description,
+        expected_scene_id=expected_scene_id,
+    )
     return call([python, "-u", str(REPO_ROOT / path), *extra_args, *passthrough])
 
 
-def run_python_files(description: str, paths: Iterable[str]) -> int:
-    python, passthrough = parse_python_passthrough(description)
+def run_python_files(
+    description: str,
+    paths: Iterable[str],
+    *,
+    expected_scene_id: str | None = None,
+) -> int:
+    python, passthrough, _scene_config = parse_python_passthrough(
+        description,
+        expected_scene_id=expected_scene_id,
+    )
     for path in paths:
         rc = call([python, "-u", str(REPO_ROOT / path), *passthrough])
         if rc != 0:
diff --git a/fluxon_test_stack/top_attention_test_index/_config_fs.py b/fluxon_test_stack/top_attention_test_index/_config_fs.py
index 3392324..2b6f072 100755
--- a/fluxon_test_stack/top_attention_test_index/_config_fs.py
+++ b/fluxon_test_stack/top_attention_test_index/_config_fs.py
@@ -4,13 +4,14 @@
 from _common import run_python_file
 
 
-TEST_REQUIREMENTS = ["ops"]
+SCENE_ID = "ci_top_attention_config_fs"
 
 
 def main() -> int:
     return run_python_file(
         "Flat index entry for FS Python config/schema tests.",
         "fluxon_py/tests/test_fluxon_fs_config_types.py",
+        expected_scene_id=SCENE_ID,
     )
 
 
diff --git a/fluxon_test_stack/top_attention_test_index/_config_kv.py b/fluxon_test_stack/top_attention_test_index/_config_kv.py
index 775284b..1ba7fab 100755
--- a/fluxon_test_stack/top_attention_test_index/_config_kv.py
+++ b/fluxon_test_stack/top_attention_test_index/_config_kv.py
@@ -4,13 +4,14 @@
 from _common import run_python_file
 
 
-TEST_REQUIREMENTS = ["ops"]
+SCENE_ID = "ci_top_attention_config_kv"
 
 
 def main() -> int:
     return run_python_file(
         "Flat index entry for KV Python config/schema tests.",
         "fluxon_py/tests/test_config.py",
+        expected_scene_id=SCENE_ID,
     )
 
 
diff --git a/fluxon_test_stack/top_attention_test_index/_config_mq.py b/fluxon_test_stack/top_attention_test_index/_config_mq.py
index 9930491..5294a4c 100755
--- a/fluxon_test_stack/top_attention_test_index/_config_mq.py
+++ b/fluxon_test_stack/top_attention_test_index/_config_mq.py
@@ -4,7 +4,7 @@
 from _common import run_pytest
 
 
-TEST_REQUIREMENTS = ["etcd", "fluxon-pyo3", "kv-cluster", "ops", "submodules"]
+SCENE_ID = "ci_top_attention_config_mq"
 
 
 def main() -> int:
@@ -14,6 +14,7 @@ def main() -> int:
             "fluxon_py/tests/test_mq/test_capacity_and_auto_clean.py",
             "fluxon_py/tests/test_mq/test_payload_lease_error.py",
         ],
+        expected_scene_id=SCENE_ID,
     )
 
 
diff --git a/fluxon_test_stack/top_attention_test_index/_ctrl_c_kv.py b/fluxon_test_stack/top_attention_test_index/_ctrl_c_kv.py
index f3e5e75..1b1b0f9 100755
--- a/fluxon_test_stack/top_attention_test_index/_ctrl_c_kv.py
+++ b/fluxon_test_stack/top_attention_test_index/_ctrl_c_kv.py
@@ -4,7 +4,7 @@
 from _common import run_python_file
 
 
-TEST_REQUIREMENTS = ["ops"]
+SCENE_ID = "ci_top_attention_ctrl_c_kv"
 
 
 def main() -> int:
@@ -12,6 +12,7 @@ def main() -> int:
         "Flat index entry for existing KV/runtime Ctrl-C shutdown coverage.",
         "fluxon_py/tests/test_process_runner.py",
         ["TestProcessRunner.test_wait_subproc_or_ctrlc_retires_children_on_sigterm"],
+        expected_scene_id=SCENE_ID,
     )
 
 
diff --git a/fluxon_test_stack/top_attention_test_index/_ctrl_c_mq.py b/fluxon_test_stack/top_attention_test_index/_ctrl_c_mq.py
index 3e56e8a..7f1ef67 100755
--- a/fluxon_test_stack/top_attention_test_index/_ctrl_c_mq.py
+++ b/fluxon_test_stack/top_attention_test_index/_ctrl_c_mq.py
@@ -4,13 +4,14 @@
 from _common import run_python_file
 
 
-TEST_REQUIREMENTS = ["etcd", "fluxon-pyo3", "fluxon-release", "greptime", "ops", "submodules"]
+SCENE_ID = "ci_top_attention_ctrl_c_mq"
 
 
 def main() -> int:
     return run_python_file(
         "Flat index entry for existing MQ Ctrl-C integration coverage.",
         "fluxon_py/tests/test_mq/test_example_ctrl_c_exit.py",
+        expected_scene_id=SCENE_ID,
     )
 
 
diff --git a/fluxon_test_stack/top_attention_test_index/_deployment_codegen.py b/fluxon_test_stack/top_attention_test_index/_deployment_codegen.py
index 8bac6eb..cdba174 100755
--- a/fluxon_test_stack/top_attention_test_index/_deployment_codegen.py
+++ b/fluxon_test_stack/top_attention_test_index/_deployment_codegen.py
@@ -4,8 +4,6 @@
 from _common import run_python_files
 
 
-TEST_REQUIREMENTS = ["ops"]
-
 
 def main() -> int:
     return run_python_files(
diff --git a/fluxon_test_stack/top_attention_test_index/_doc_page_build.py b/fluxon_test_stack/top_attention_test_index/_doc_page_build.py
index 8047045..b336607 100644
--- a/fluxon_test_stack/top_attention_test_index/_doc_page_build.py
+++ b/fluxon_test_stack/top_attention_test_index/_doc_page_build.py
@@ -8,7 +8,6 @@
 from _common import REPO_ROOT, call, load_case_config
 
 
-TEST_REQUIREMENTS = ["ops"]
 SCENE_ID = "ci_top_attention_doc_page_build"
 
 
diff --git a/fluxon_test_stack/top_attention_test_index/_fs_py_core.py b/fluxon_test_stack/top_attention_test_index/_fs_py_core.py
index fa53e10..9f9f35b 100755
--- a/fluxon_test_stack/top_attention_test_index/_fs_py_core.py
+++ b/fluxon_test_stack/top_attention_test_index/_fs_py_core.py
@@ -4,8 +4,6 @@
 from _common import run_pytest
 
 
-TEST_REQUIREMENTS = ["etcd", "fluxon-pyo3", "kv-cluster", "ops", "submodules"]
-
 
 def main() -> int:
     return run_pytest(
diff --git a/fluxon_test_stack/top_attention_test_index/_fs_remote_mount.py b/fluxon_test_stack/top_attention_test_index/_fs_remote_mount.py
index 4cae6e4..c51075c 100755
--- a/fluxon_test_stack/top_attention_test_index/_fs_remote_mount.py
+++ b/fluxon_test_stack/top_attention_test_index/_fs_remote_mount.py
@@ -4,8 +4,6 @@
 from _common import run_pytest
 
 
-TEST_REQUIREMENTS = ["etcd", "fluxon-pyo3", "kv-cluster", "ops", "submodules"]
-
 
 def main() -> int:
     return run_pytest(
diff --git a/fluxon_test_stack/top_attention_test_index/_fs_transfer_tikv.py b/fluxon_test_stack/top_attention_test_index/_fs_transfer_tikv.py
index cdc685c..559311e 100755
--- a/fluxon_test_stack/top_attention_test_index/_fs_transfer_tikv.py
+++ b/fluxon_test_stack/top_attention_test_index/_fs_transfer_tikv.py
@@ -4,8 +4,6 @@
 from _common import run_pytest
 
 
-TEST_REQUIREMENTS = ["etcd", "fluxon-pyo3", "fluxon-release", "ops", "submodules", "tikv"]
-
 
 def main() -> int:
     return run_pytest(
diff --git a/fluxon_test_stack/top_attention_test_index/_kv_py_core.py b/fluxon_test_stack/top_attention_test_index/_kv_py_core.py
index 924ca7a..8168709 100755
--- a/fluxon_test_stack/top_attention_test_index/_kv_py_core.py
+++ b/fluxon_test_stack/top_attention_test_index/_kv_py_core.py
@@ -4,8 +4,6 @@
 from _common import run_pytest
 
 
-TEST_REQUIREMENTS = ["etcd", "fluxon-pyo3", "kv-cluster", "ops", "submodules"]
-
 
 def main() -> int:
     return run_pytest(
diff --git a/fluxon_test_stack/top_attention_test_index/_largescale_mq.py b/fluxon_test_stack/top_attention_test_index/_largescale_mq.py
index 7211bd9..6df816c 100755
--- a/fluxon_test_stack/top_attention_test_index/_largescale_mq.py
+++ b/fluxon_test_stack/top_attention_test_index/_largescale_mq.py
@@ -14,8 +14,6 @@
 from _common import REPO_ROOT, call
 
 
-TEST_REQUIREMENTS = ["fluxon-release", "ops", "submodules", "test-stack-targets"]
-
 
 SCENE_ID = "bench_mq"
 DEFAULT_PROFILE_ID = "fluxon_tcp"
diff --git a/fluxon_test_stack/top_attention_test_index/_mq_core.py b/fluxon_test_stack/top_attention_test_index/_mq_core.py
index 4da1b14..6c2196e 100755
--- a/fluxon_test_stack/top_attention_test_index/_mq_core.py
+++ b/fluxon_test_stack/top_attention_test_index/_mq_core.py
@@ -4,8 +4,6 @@
 from _common import run_pytest
 
 
-TEST_REQUIREMENTS = ["etcd", "fluxon-pyo3", "kv-cluster", "ops", "submodules"]
-
 
 def main() -> int:
     return run_pytest(
diff --git a/fluxon_test_stack/top_attention_test_index/_mq_mpmc.py b/fluxon_test_stack/top_attention_test_index/_mq_mpmc.py
index 0b3db0e..3b9ba2c 100755
--- a/fluxon_test_stack/top_attention_test_index/_mq_mpmc.py
+++ b/fluxon_test_stack/top_attention_test_index/_mq_mpmc.py
@@ -4,8 +4,6 @@
 from _common import run_pytest
 
 
-TEST_REQUIREMENTS = ["etcd", "kv-cluster", "ops"]
-
 
 def main() -> int:
     return run_pytest(
diff --git a/fluxon_test_stack/top_attention_test_index/_mq_mpmc_bench.py b/fluxon_test_stack/top_attention_test_index/_mq_mpmc_bench.py
index 8c6501b..a2e9231 100755
--- a/fluxon_test_stack/top_attention_test_index/_mq_mpmc_bench.py
+++ b/fluxon_test_stack/top_attention_test_index/_mq_mpmc_bench.py
@@ -4,8 +4,6 @@
 from _common import run_pytest
 
 
-TEST_REQUIREMENTS = ["etcd", "kv-cluster", "ops"]
-
 
 def main() -> int:
     return run_pytest(
diff --git a/fluxon_test_stack/top_attention_test_index/_mq_mpsc.py b/fluxon_test_stack/top_attention_test_index/_mq_mpsc.py
index 3ff94ef..1c2ec60 100755
--- a/fluxon_test_stack/top_attention_test_index/_mq_mpsc.py
+++ b/fluxon_test_stack/top_attention_test_index/_mq_mpsc.py
@@ -4,8 +4,6 @@
 from _common import run_pytest
 
 
-TEST_REQUIREMENTS = ["etcd", "kv-cluster", "ops"]
-
 
 def main() -> int:
     return run_pytest(
diff --git a/fluxon_test_stack/top_attention_test_index/_pack_test_rsc.py b/fluxon_test_stack/top_attention_test_index/_pack_test_rsc.py
index 355f380..010b4aa 100755
--- a/fluxon_test_stack/top_attention_test_index/_pack_test_rsc.py
+++ b/fluxon_test_stack/top_attention_test_index/_pack_test_rsc.py
@@ -4,8 +4,6 @@
 from _common import run_python_file
 
 
-TEST_REQUIREMENTS = ["fluxon-release", "ops", "submodules"]
-
 
 def main() -> int:
     return run_python_file(
diff --git a/fluxon_test_stack/top_attention_test_index/_pack_whl.py b/fluxon_test_stack/top_attention_test_index/_pack_whl.py
index 1106968..1eac186 100755
--- a/fluxon_test_stack/top_attention_test_index/_pack_whl.py
+++ b/fluxon_test_stack/top_attention_test_index/_pack_whl.py
@@ -4,8 +4,6 @@
 from _common import REPO_ROOT, call, parse_python_passthrough
 
 
-TEST_REQUIREMENTS = ["ops", "python-wheel-build", "submodules"]
-
 
 def main() -> int:
     python, passthrough = parse_python_passthrough(
diff --git a/fluxon_test_stack/top_attention_test_index/_py_runtime.py b/fluxon_test_stack/top_attention_test_index/_py_runtime.py
index b9de962..e6067ed 100755
--- a/fluxon_test_stack/top_attention_test_index/_py_runtime.py
+++ b/fluxon_test_stack/top_attention_test_index/_py_runtime.py
@@ -4,8 +4,6 @@
 from _common import run_python_files
 
 
-TEST_REQUIREMENTS = ["ops"]
-
 
 def main() -> int:
     return run_python_files(
diff --git a/fluxon_test_stack/top_attention_test_index/_relay_mq.py b/fluxon_test_stack/top_attention_test_index/_relay_mq.py
index a9d07f6..2fe519f 100755
--- a/fluxon_test_stack/top_attention_test_index/_relay_mq.py
+++ b/fluxon_test_stack/top_attention_test_index/_relay_mq.py
@@ -4,8 +4,6 @@
 from _common import run_pytest
 
 
-TEST_REQUIREMENTS = ["docker", "etcd", "fluxon-release", "ops", "submodules"]
-
 
 def main() -> int:
     return run_pytest(
diff --git a/fluxon_test_stack/top_attention_test_index/_script_tools.py b/fluxon_test_stack/top_attention_test_index/_script_tools.py
index 304b7b9..4c450ab 100755
--- a/fluxon_test_stack/top_attention_test_index/_script_tools.py
+++ b/fluxon_test_stack/top_attention_test_index/_script_tools.py
@@ -4,8 +4,6 @@
 from _common import run_python_files
 
 
-TEST_REQUIREMENTS = ["ops"]
-
 
 def main() -> int:
     return run_python_files(
diff --git a/fluxon_test_stack/top_attention_test_index/_test_requirements.py b/fluxon_test_stack/top_attention_test_index/_test_requirements.py
index ddf87a6..3868bd7 100644
--- a/fluxon_test_stack/top_attention_test_index/_test_requirements.py
+++ b/fluxon_test_stack/top_attention_test_index/_test_requirements.py
@@ -4,12 +4,10 @@
 from _common import run_python_file
 
 
-TEST_REQUIREMENTS = ["ops"]
-
 
 def main() -> int:
     return run_python_file(
-        "Flat index entry for TEST_REQUIREMENTS metadata convergence checks.",
+        "Flat index entry for top-attention requirements metadata convergence checks.",
         "fluxon_test_stack/top_attention_test_index/test_test_requirements.py",
     )
 
diff --git a/fluxon_test_stack/top_attention_test_index/_test_stack_contract.py b/fluxon_test_stack/top_attention_test_index/_test_stack_contract.py
index ddd6e17..fc8757c 100755
--- a/fluxon_test_stack/top_attention_test_index/_test_stack_contract.py
+++ b/fluxon_test_stack/top_attention_test_index/_test_stack_contract.py
@@ -4,8 +4,6 @@
 from _common import run_python_file
 
 
-TEST_REQUIREMENTS = ["ops"]
-
 
 def main() -> int:
     return run_python_file(
diff --git a/fluxon_test_stack/top_attention_test_index/requirements_all.py b/fluxon_test_stack/top_attention_test_index/requirements_all.py
deleted file mode 100644
index edf8d87..0000000
--- a/fluxon_test_stack/top_attention_test_index/requirements_all.py
+++ /dev/null
@@ -1,93 +0,0 @@
-from __future__ import annotations
-
-import ast
-from pathlib import Path
-
-
-TEST_REQUIREMENTS: list[str] = ["ops"]
-TEST_DIR = Path(__file__).resolve().parent
-IGNORED_INDEX_ENTRY_NAMES = frozenset({"_common.py"})
-
-
-ALL_TEST_REQUIREMENTS: tuple[str, ...] = (
-    "cargo",
-    "docker",
-    "etcd",
-    "fluxon-pyo3",
-    "fluxon-release",
-    "greptime",
-    "kv-cluster",
-    "ops",
-    "python-wheel-build",
-    "submodules",
-    "test-stack-targets",
-    "tikv",
-)
-
-ALL_TEST_REQUIREMENTS_SET = frozenset(ALL_TEST_REQUIREMENTS)
-
-TEST_REQUIREMENT_DESCRIPTIONS: dict[str, str] = {
-    "cargo": "Rust cargo toolchain is required.",
-    "docker": "A working Docker daemon is required.",
-    "etcd": "An etcd runtime is required, either external or started by the test.",
-    "fluxon-pyo3": "The compiled fluxon_pyo3 Python extension must be available.",
-    "fluxon-release": "The local fluxon_release runtime/artifact tree must be populated.",
-    "greptime": "A GreptimeDB runtime is required, either external or started by the test.",
-    "kv-cluster": "A configured KV backend runtime from the repo test config must be reachable.",
-    "ops": "A reachable Fluxon Ops control plane is required by the test-stack execution flow.",
-    "python-wheel-build": "Python wheel build dependencies must be available.",
-    "submodules": "Required git submodules must be initialized for build-using tests.",
-    "test-stack-targets": "A TEST_STACK config with reachable target hosts is required.",
-    "tikv": "A TiKV/PD runtime is required, either external or started by the test.",
-}
-
-
-def iter_test_python_paths() -> tuple[Path, ...]:
-    return tuple(sorted(TEST_DIR.glob("*.py")))
-
-
-def iter_index_entry_paths() -> tuple[Path, ...]:
-    return tuple(
-        path
-        for path in iter_test_python_paths()
-        if path.name.startswith("_") and path.name not in IGNORED_INDEX_ENTRY_NAMES
-    )
-
-
-def extract_test_requirements(path: Path) -> list[str]:
-    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
-    found = None
-    for node in tree.body:
-        target_name = None
-        value_node = None
-        if isinstance(node, ast.Assign):
-            for target in node.targets:
-                if isinstance(target, ast.Name) and target.id == "TEST_REQUIREMENTS":
-                    target_name = target.id
-                    value_node = node.value
-                    break
-        elif isinstance(node, ast.AnnAssign):
-            if isinstance(node.target, ast.Name) and node.target.id == "TEST_REQUIREMENTS":
-                target_name = node.target.id
-                value_node = node.value
-
-        if target_name != "TEST_REQUIREMENTS":
-            continue
-        if found is not None:
-            raise AssertionError(f"{path.name} defines TEST_REQUIREMENTS more than once")
-        if value_node is None:
-            raise AssertionError(f"{path.name} TEST_REQUIREMENTS must assign a list literal")
-        try:
-            value = ast.literal_eval(value_node)
-        except (ValueError, SyntaxError) as exc:
-            raise AssertionError(
-                f"{path.name} TEST_REQUIREMENTS must be a static list literal"
-            ) from exc
-        if not isinstance(value, list):
-            raise AssertionError(f"{path.name} TEST_REQUIREMENTS must be a list literal")
-        if not all(isinstance(item, str) for item in value):
-            raise AssertionError(f"{path.name} TEST_REQUIREMENTS must contain only strings")
-        found = value
-    if found is None:
-        raise AssertionError(f"{path.name} is missing TEST_REQUIREMENTS")
-    return found
diff --git a/fluxon_test_stack/top_attention_test_index/test_test_requirements.py b/fluxon_test_stack/top_attention_test_index/test_test_requirements.py
index 2c9a4bb..f3e0aaf 100644
--- a/fluxon_test_stack/top_attention_test_index/test_test_requirements.py
+++ b/fluxon_test_stack/top_attention_test_index/test_test_requirements.py
@@ -3,43 +3,89 @@
 import unittest
 from pathlib import Path
 
-from requirements_all import (
-    ALL_TEST_REQUIREMENTS,
-    ALL_TEST_REQUIREMENTS_SET,
-    extract_test_requirements,
-    iter_test_python_paths,
-)
+import yaml
 
 
-TEST_REQUIREMENTS: list[str] = ["ops"]
+REPO_ROOT = Path(__file__).resolve().parents[2]
+INDEX_DIR = Path(__file__).resolve().parent
+SUITE_PATH = REPO_ROOT / "fluxon_test_stack" / "ci_test_list.yaml"
+TOP_ATTENTION_SCENE_ID_PREFIX = "ci_top_attention_"
+IGNORED_INDEX_ENTRY_NAMES = frozenset({"_common.py"})
 
 
-class TestTestRequirements(unittest.TestCase):
-    def test_every_test_py_declares_requirements(self) -> None:
-        for path in iter_test_python_paths():
-            with self.subTest(path=path.name):
-                _ = extract_test_requirements(path)
+def iter_index_entry_paths() -> tuple[Path, ...]:
+    return tuple(
+        path
+        for path in sorted(INDEX_DIR.glob("*.py"))
+        if path.name.startswith("_") and path.name not in IGNORED_INDEX_ENTRY_NAMES
+    )
+
+
+def top_attention_scene_id(path: Path) -> str:
+    return TOP_ATTENTION_SCENE_ID_PREFIX + path.stem.lstrip("_")
+
+
+def _load_suite_scenes() -> dict[str, object]:
+    raw = yaml.safe_load(SUITE_PATH.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise AssertionError(f"suite must be a mapping: {SUITE_PATH}")
+    scenes = raw.get("scenes")
+    if not isinstance(scenes, dict):
+        raise AssertionError(f"suite scenes must be a mapping: {SUITE_PATH}")
+    return scenes
 
-    def test_declared_requirement_lists_are_sorted_unique_and_known(self) -> None:
-        for path in iter_test_python_paths():
-            requirements = extract_test_requirements(path)
-            with self.subTest(path=path.name):
-                self.assertEqual(requirements, sorted(set(requirements)))
-                self.assertTrue(set(requirements).issubset(ALL_TEST_REQUIREMENTS_SET))
 
-    def test_requirement_universe_is_sorted_unique(self) -> None:
-        self.assertEqual(list(ALL_TEST_REQUIREMENTS), sorted(set(ALL_TEST_REQUIREMENTS)))
+def _ci_scene_ids() -> set[str]:
+    return {
+        scene_id
+        for scene_id, raw_scene in _load_suite_scenes().items()
+        if isinstance(scene_id, str)
+        and isinstance(raw_scene, dict)
+        and isinstance(raw_scene.get("ci"), dict)
+    }
 
-    def test_requirement_universe_matches_declared_union(self) -> None:
-        declared_union: set[str] = set()
-        for path in iter_test_python_paths():
-            declared_union.update(extract_test_requirements(path))
-        self.assertEqual(declared_union, set(ALL_TEST_REQUIREMENTS))
+
+def _scene_requirements(scene_id: str) -> list[str]:
+    scenes = _load_suite_scenes()
+    scene = scenes.get(scene_id)
+    if not isinstance(scene, dict):
+        raise AssertionError(f"missing top-attention scene in suite: {scene_id}")
+    ci = scene.get("ci")
+    if not isinstance(ci, dict):
+        raise AssertionError(f"top-attention scene must be CI-backed: {scene_id}")
+    requirements = ci.get("requirements")
+    if not isinstance(requirements, list):
+        raise AssertionError(f"scene[{scene_id}].ci.requirements must be a list")
+    out: list[str] = []
+    for index, raw_item in enumerate(requirements):
+        if not isinstance(raw_item, str) or not raw_item.strip():
+            raise AssertionError(f"scene[{scene_id}].ci.requirements[{index}] must be a non-empty string")
+        out.append(raw_item.strip())
+    return out
+
+
+class TestTopAttentionYamlRequirements(unittest.TestCase):
+    def test_every_index_entry_has_suite_scene(self) -> None:
+        for path in iter_index_entry_paths():
+            scene_id = top_attention_scene_id(path)
+            if scene_id not in _ci_scene_ids():
+                continue
+            with self.subTest(path=path.name, scene_id=scene_id):
+                _ = _scene_requirements(scene_id)
+
+    def test_scene_requirements_are_sorted_and_unique(self) -> None:
+        for path in iter_index_entry_paths():
+            scene_id = top_attention_scene_id(path)
+            if scene_id not in _ci_scene_ids():
+                continue
+            requirements = _scene_requirements(scene_id)
+            with self.subTest(path=path.name, scene_id=scene_id):
+                self.assertEqual(requirements, sorted(set(requirements)))
 
     def test_removed_direct_entrypoints_stay_removed(self) -> None:
-        self.assertFalse((Path(__file__).resolve().parent / "_all_quick.py").exists())
-        self.assertFalse((Path(__file__).resolve().parent / "run_match_prefix.py").exists())
+        self.assertFalse((INDEX_DIR / "_all_quick.py").exists())
+        self.assertFalse((INDEX_DIR / "run_match_prefix.py").exists())
 
 
 if __name__ == "__main__":
-    unittest.main()
+    raise SystemExit(unittest.main())
diff --git a/skills/browser-helm/SKILL.md b/skills/browser-helm/SKILL.md
new file mode 100644
index 0000000..dbe1afd
--- /dev/null
+++ b/skills/browser-helm/SKILL.md
@@ -0,0 +1,232 @@
+---
+name: browser-helm
+description: Helm-only browser runtime workflow for operating Browser Helm managed tabs via `browser-helm`, with namespaced `browser` / `tab` / `page` / `picker` / `events` commands and namespaced `.tmp/browser-helm/` output conventions.
+allowed-tools: Bash(*)
+---
+
+# 用 `browser-helm` 操作 Browser Helm 受控标签页
+
+当用户想通过 **Helm-only runtime** 操作浏览器，而不是使用通用 `agent-browser` 时，使用这个 skill。
+
+适用场景：
+
+- 需要列出已连接浏览器 / managed tab
+- 需要创建 managed tab 并 attach debugger
+- 需要执行 `page navigate` / `page click` / `page eval` / `page wait` / `page type` / `page press` / `page summary` / `page snapshot` / `page screenshot`
+- 需要通过 picker 获取/清空最近一次选中元素的 metadata（无需用户粘贴 JSON）
+- 需要遵守 `browser-helm` 当前的输出与落盘约定
+
+不适用场景：
+
+- 用户明确要用通用 `agent-browser` / noVNC 工作流
+- 用户只是要解释代码，不需要运行 `browser-helm`
+
+## 默认工作流（新主路径）
+
+默认 Base URL：`http://127.0.0.1:5181`（不需要设置环境变量）。
+
+如需覆盖（可选）：在命令前追加 `--base-url http://127.0.0.1:5181`。
+
+如本机未全局安装 `browser-helm`，也可以用 `node browser-helm/dist/cli.js` 替代下方命令。
+
+## 多人/多 AI 会话（互信）约定（重要）
+
+当前产品定位下，daemon / Web UI / WS **默认不做鉴权**，更偏向“同一局域网多人互信”的协作模型。
+
+但为了避免 **同一台浏览器 + 多个 AI 对话** 时出现“串台/误操作”，推荐强制使用 `session` 做操作隔离：
+
+- 每个 AI 对话固定用一个 `--session <name>`（或设置环境变量 `BROWSER_HELM_SESSION=<name>`）
+- `session` 会隔离：
+  - CLI context 落盘：`.tmp/browser-helm/context.json`（default）或 `.tmp/browser-helm/sessions/<session>/context.json`
+  - CLI 输出落盘：`.tmp/browser-helm/<type>/...`（default）或 `.tmp/browser-helm/sessions/<session>/<type>/...`
+  - `tab create` 会自动加前缀：`[session:<session>] ...`（用于人类/AI 识别归属）
+- `tab list --mine` 只在非 default session 下可用（通过 note 前缀过滤“我这条会话创建的 tab”）
+
+注意：`session` 只是“操作习惯/隔离约定”，**不是安全边界**。知道 `managed-tab-id` 仍然能跨 session 操作；不要把端口暴露到不可信网络。
+
+### 前置（必须）：安装插件并配对
+
+`browser-helm` 的所有浏览器动作都依赖 **Chrome 插件已连接 daemon（WebSocket）**：
+
+- 创建 managed tab 时建议提供 `--note <text>`，用于描述这个 tab 的意图/用途。
+  - 若省略 `--note` 且提供 URL，CLI 会自动生成：`打开页面：<url>`
+
+- 若 `browser-helm browser list` 一直为空，优先判断是「插件未安装/未 Connect」而不是 CLI 出错。
+
+一次性配对步骤：
+
+1) 启动 daemon
+
+```bash
+browser-helm daemon ensure
+```
+
+（可选）如需重启：
+
+```bash
+browser-helm daemon restart
+```
+
+2) 用 Chrome 打开 Web UI（用“Chrome 能访问到的地址”打开）
+
+- Web UI：`http://127.0.0.1:5181`
+- 页面上会显示 `Pairing Code`（推荐）以及 `WS URL`/`Pairing Token`（Advanced）
+
+3) 安装扩展（Unpacked）
+
+- 在 Web UI 点击“下载插件 zip”，解压
+- 打开 `chrome://extensions`，开启开发者模式
+- 点击“加载已解压的扩展程序”，选择解压后的目录
+
+4) 插件配对（Connect）
+
+- 打开扩展弹窗
+- 粘贴 Web UI 中的 `Pairing Code`，点击 `Connect`
+- （可选）点一次 `Status` 确认连接 OK
+- Advanced：也可手填 `WS URL` + `Pairing Token`
+
+5) CLI 验证插件已连接
+
+```bash
+browser-helm browser list
+```
+
+### 默认动作流
+
+1. 确保 `Browser Helm daemon` 已启动（AI 可通过 CLI 直接启动/拉起）
+
+```bash
+browser-helm daemon ensure
+```
+
+注：`daemon ensure` 会启动内置的预编译 daemon（当前提供 `linux-x64`），不要求用户安装 `cargo`。
+
+2. 确认扩展已连接，并列出浏览器
+
+```bash
+browser-helm browser list
+```
+
+（推荐）3. Pin 默认 browser/tab（减少长对话遗忘成本）
+
+```bash
+browser-helm context use-browser <browser-id>
+browser-helm context use-tab <managed-tab-id>
+browser-helm context show
+```
+
+4. 列 tab；如无 tab，则创建新 tab
+
+```bash
+browser-helm browser list
+browser-helm tab list <browser-id>
+browser-helm tab create <browser-id> https://example.com --note "说明这个 tab 的用途"
+```
+
+5. （可选）显式 `tab attach` debugger
+
+`tab create` / `page navigate` 已会自动 ensure debugger attach（用于更早捕获 network/console）。如果你准备在浏览器里手动刷新/导航，也建议先 `tab attach`。
+
+```bash
+browser-helm tab attach <browser-id> <managed-tab-id>
+```
+
+6. 页面分析优先走返回值主路
+
+```bash
+browser-helm page summary <browser-id> <managed-tab-id>
+browser-helm page snapshot <browser-id> <managed-tab-id>
+```
+
+7. 只有在需要留档时才显式保存 `page summary` / `page snapshot`
+
+```bash
+browser-helm --save page summary <browser-id> <managed-tab-id>
+browser-helm --save page snapshot <browser-id> <managed-tab-id>
+```
+
+8. `page screenshot` 默认会落盘；`page click` 会走受控页遮罩下的程序化点击
+
+```bash
+browser-helm page click <browser-id> <managed-tab-id> '#selector'
+browser-helm page click <browser-id> <managed-tab-id> '#selector' --wait-text 'Finished working' --timeout-ms 15000
+browser-helm page eval <browser-id> <managed-tab-id> '1+1'
+browser-helm page wait <browser-id> <managed-tab-id> --until-text 'Finished working' --timeout-ms 15000
+browser-helm page type <browser-id> <managed-tab-id> 'div[aria-label="Composer"]' 'hello'
+browser-helm page press <browser-id> <managed-tab-id> 'Enter'
+browser-helm page screenshot <browser-id> <managed-tab-id>
+```
+
+9. 推荐先 `page snapshot` 生成 `@iN` refs，再用 ref 操作（类似 agent-browser 的 `@eN`）
+
+```bash
+browser-helm page snapshot <browser-id> <managed-tab-id>
+browser-helm page click @i1
+browser-helm page type @i2 'hello'
+```
+
+9. 如用户在 SidePanel 做了元素选择（Start Picking），AI 可直接从 daemon 拉取最近一次选择结果
+
+```bash
+browser-helm picker last
+browser-helm picker clear
+```
+
+### 交互录制（用户手动复现）
+
+当你需要「AI 先打开受控 tab，然后用户自己操作复现问题，再让 AI 回看」时，可以开启交互录制：
+
+```bash
+# 记录起始时间（ms）
+t0=$(date +%s%3N)
+
+# 开始录制（会注入监听脚本，并临时隐藏遮罩，允许用户点击/输入）
+browser-helm recorder start <browser-id> <managed-tab-id>
+
+# ...用户在该 tab 上手动复现...
+
+# 拉取复现阶段的交互/console/network 事件（按 since 过滤）
+browser-helm events interaction <browser-id> <managed-tab-id> --since $t0 --limit 2000
+browser-helm events console <browser-id> <managed-tab-id> --since $t0 --limit 2000
+browser-helm events network <browser-id> <managed-tab-id> --since $t0 --limit 2000
+
+# 停止录制（恢复遮罩）
+browser-helm recorder stop <browser-id> <managed-tab-id>
+```
+
+注意：交互录制会包含 input 的原始 value（不脱敏）。仅建议在互信/本地环境使用。
+
+## 输出与落盘约定
+
+- `page summary`：默认只打印；传 `output-path` 或 `--save` 时，写入 `.tmp/browser-helm/summaries/`
+- `page snapshot`：默认只打印；传 `output-path` 或 `--save` 时，写入 `.tmp/browser-helm/snapshots/`
+- `page screenshot`：默认写入 `.tmp/browser-helm/screenshots/`
+- 若使用 `--session <name>` / `BROWSER_HELM_SESSION=<name>`：上述目录会自动切换到 `.tmp/browser-helm/sessions/<session>/...`
+- 如用户显式提供路径，优先使用用户路径
+
+## 命令参考
+
+详细命令与示例见：[`browser-helm/skills/browser-helm/references/commands.md`]
+
+优先顺序建议：
+
+1. `browser list`
+2. `tab list`
+3. `tab create`（推荐写 `--note`；若省略且提供 URL，则自动生成 note）
+   - 或：`tab adopt-active`（接管当前活动 tab）
+4. `tab attach`
+5. `page navigate`
+6. `page summary` / `page snapshot`
+7. `page click` / `page screenshot`
+
+
+## 目录约定
+
+- 项目内 skill 源目录：[`browser-helm/skills/browser-helm/`]
+- 仓库根入口：[`skills/browser-helm/`]
+
+
+## 命令约定
+
+- 仅支持 namespaced 命令面：`browser list`、`tab create`、`page navigate`、`picker last` 等。
+- 默认文档路径改为 namespaced 形式：`browser list`、`tab create`、`page navigate`、`events console`、`picker last`。
diff --git a/skills/browser-helm/agents/openai.yaml b/skills/browser-helm/agents/openai.yaml
new file mode 100644
index 0000000..686f428
--- /dev/null
+++ b/skills/browser-helm/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: Browser Helm
+  short_description: 通过 Browser Helm 操作 Browser Helm 受控标签页流程
+  default_prompt: Use $browser-helm to inspect and operate Browser Helm managed tabs.
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/browser-helm/references/commands.md b/skills/browser-helm/references/commands.md
new file mode 100644
index 0000000..d22d465
--- /dev/null
+++ b/skills/browser-helm/references/commands.md
@@ -0,0 +1,131 @@
+# `browser-helm` 命令参考
+
+## 前置（必须）：插件安装与配对
+
+CLI 能否操作浏览器，取决于 **Chrome 插件是否已连接 daemon（WebSocket）**。
+
+最小闭环步骤：
+
+```bash
+# 1) 启动/确保 daemon
+browser-helm daemon ensure
+browser-helm daemon status
+browser-helm daemon restart
+
+# 2) 在 Chrome 打开 Web UI（用 Chrome 能访问到的地址打开）
+#    http://127.0.0.1:5181
+#    从页面复制 Pairing Code（推荐；含多网卡候选地址）或 WS URL + Pairing Token（Advanced）
+#
+# 3) 安装扩展（Unpacked）
+#    - Web UI 下载插件 zip -> 解压
+#    - chrome://extensions 开启开发者模式 -> 加载已解压扩展
+#
+# 4) 插件弹窗填 Pairing Code -> Connect
+
+# 5) 验证浏览器已连接
+browser-helm browser list
+```
+
+## 基础命令（新主路径）
+
+```bash
+browser-helm daemon status
+browser-helm daemon ensure
+browser-helm daemon stop
+browser-helm daemon restart
+browser-helm status
+browser-helm browser list
+browser-helm tab list [browser-id] [--mine]
+browser-helm recorder start [browser-id] [managed-tab-id]
+browser-helm recorder stop [browser-id] [managed-tab-id]
+```
+
+## 受控 tab 生命周期
+
+```bash
+browser-helm tab create [browser-id] [url] [--note <text>]
+browser-helm tab adopt-active [browser-id] [--note <text>]
+browser-helm tab attach [browser-id] [managed-tab-id]
+browser-helm page navigate [browser-id] [managed-tab-id] <url>
+```
+
+## 交互与分析
+
+```bash
+browser-helm page click [browser-id] [managed-tab-id] <selector> [--wait-(selector|text|js) <value>] [--timeout-ms <n>] [--interval-ms <n>]
+browser-helm page eval [browser-id] [managed-tab-id] <expression>
+browser-helm page wait [browser-id] [managed-tab-id] --until-(selector|text|js) <value> [--timeout-ms <n>] [--interval-ms <n>]
+browser-helm page type [browser-id] [managed-tab-id] <selector> <text>
+browser-helm page press [browser-id] [managed-tab-id] <key>
+browser-helm page summary [browser-id] [managed-tab-id] [output-path]
+browser-helm page snapshot [browser-id] [managed-tab-id] [output-path]
+browser-helm page screenshot [browser-id] [managed-tab-id] [output-path]
+browser-helm events console [browser-id] [managed-tab-id] [--limit <n>] [--since <ms>]
+browser-helm events network [browser-id] [managed-tab-id] [--limit <n>] [--since <ms>]
+browser-helm events interaction [browser-id] [managed-tab-id] [--limit <n>] [--since <ms>]
+browser-helm picker last [browser-id] [managed-tab-id]
+browser-helm picker clear [browser-id] [managed-tab-id]
+```
+
+说明：
+
+- `page snapshot` 会生成可复用的 interactive refs：`@i1/@i2/...`（按 interactives 列表顺序）。
+- `page click/@iN`、`page type/@iN` 会把 ref 解析为 snapshot 中记录的 selector（落盘于 `.tmp/browser-helm/refs/<managed_tab_id>.json`，按 `--session` 隔离）。
+
+## Context（session-like，新主路径）
+
+长对话/长任务里，为了避免反复提供 `browser-id` / `managed-tab-id`，可以把默认对象写入本地 context：
+
+```bash
+browser-helm context use-browser <browser-id>
+browser-helm context use-tab <managed-tab-id>
+browser-helm context show
+browser-helm context clear
+```
+
+## 多 AI 对话隔离（推荐）
+
+为了避免“同一浏览器 + 多个 AI 对话”串台，建议为每条对话固定一个 `session`：
+
+```bash
+browser-helm --session chat-a browser list
+browser-helm --session chat-a tab list --mine
+browser-helm --session chat-a tab create <browser-id> https://example.com --note "这条对话的用途说明"
+```
+
+说明：
+
+- `tab create` 会自动加前缀：`[session:chat-a] ...`
+- `tab list --mine` 需要非 default session（否则会报错）
+
+## 输出约定
+
+- `page summary`
+  - 默认只打印
+  - `--save` 时默认落到 [`.tmp/browser-helm/summaries/`]
+- `page snapshot`
+  - 默认只打印
+  - `--save` 时默认落到 [`.tmp/browser-helm/snapshots/`]
+- `page screenshot`
+  - 默认落到 [`.tmp/browser-helm/screenshots/`]
+- 若使用 `--session <name>` / `BROWSER_HELM_SESSION=<name>`：上述目录会自动切换到 [`.tmp/browser-helm/sessions/<session>/...`]
+
+## 推荐示例
+
+```bash
+browser-helm browser list
+browser-helm tab create <browser-id> https://example.com --note "说明这个 tab 的用途"
+browser-helm tab attach <browser-id> <managed-tab-id>
+browser-helm page snapshot <browser-id> <managed-tab-id>
+browser-helm --save page summary <browser-id> <managed-tab-id>
+browser-helm page screenshot <browser-id> <managed-tab-id>
+```
+
+说明：
+
+- `tab create` 若省略 `--note` 且提供 URL，会自动生成：`打开页面：<url>`
+
+## 命令约定
+
+- 仅支持 namespaced 命令面：`browser list`、`tab create`、`tab attach`、`page navigate`、`picker last` 等。
+- 文档与 skill 后续默认都以 namespaced 命令作为主路径。
diff --git a/skills/canvas-dag_organizer-v1/SKILL.md b/skills/canvas-dag_organizer-v1/SKILL.md
new file mode 100644
index 0000000..db3dc0d
--- /dev/null
+++ b/skills/canvas-dag_organizer-v1/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "canvas-dag_organizer-v1"
+description: "Canvas DAG Organizer v1"
+metadata:
+  short-description: "Canvas DAG Organizer v1"
+---
+
+# Canvas DAG Organizer v1
+
+你是「Canvas DAG 可读性优化专家」(canvas_dag_organizer)。\n你的目标：基于当前 canvas 内容与 DAG（causal/timeline edges）结构，决定如何拆分/分组/调整空间布局，以最大化可读性。\n\n硬约束（必须遵守）：\n- 禁止要求用户手工编辑 `.canvas` / `.canvas.ext` JSON。\n- 你不能执行任何命令；你只能输出一个严格 JSON 对象（不要 markdown、不要 code fence、不要额外文本）。\n- 你输出的修改必须是“可复现/确定性”的（同一输入得到同一输出）。\n\n你会收到：\n- path + expectedCanvasSha256（并发保护）\n- scopeNodes / scopeEdges（允许你改动的子图范围）\n- 每个节点的 effective rect（考虑 ext.dx/dy/scale）\n\n你的输出 JSON schema（version=1）：\n{\n  "version": 1,\n  "kind": "canvas_dag_organize_apply_v1",\n  "path": "<same as input.path>",\n  "expectedCanvasSha256": "<same as input.expectedCanvasSha256>",\n  "summary": "一句话总结你做了什么（用于 UI 提示）",\n  "ops": [\n    // CanvasOpsRequestV1.ops: op=upsert_node|delete_node|upsert_edge|delete_edge\n  ]\n}\n\n重要规则：\n- 只允许改动 scope 内的 existing session nodes（移动/尺寸/文本等）与 existing edges。\n- 允许创建 group 节点用于分区（id 必须以 "group-" 开头；type="group"）。\n- 禁止删除任何 session 节点（dever_kind=session）。\n- 如果你删除 node，必须同时删除所有引用它的 edges（否则服务端会拒绝 apply）。\n- 优先做：分组 + 分层/泳道 + 对齐 + 留白；不要盲目网格化。
diff --git a/skills/canvas-dag_organizer-v1/agents/openai.yaml b/skills/canvas-dag_organizer-v1/agents/openai.yaml
new file mode 100644
index 0000000..f7ffc0e
--- /dev/null
+++ b/skills/canvas-dag_organizer-v1/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Canvas DAG Organizer v1"
+  short_description: "Canvas DAG Organizer v1"
+  default_prompt: "Use $canvas-dag_organizer-v1."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/canvas-ops-v1/SKILL.md b/skills/canvas-ops-v1/SKILL.md
new file mode 100644
index 0000000..ffa8017
--- /dev/null
+++ b/skills/canvas-ops-v1/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "canvas-ops-v1"
+description: "Canvas Ops v1"
+metadata:
+  short-description: "Canvas Ops v1"
+---
+
+# Canvas Ops v1
+
+你是「Canvas 文件操作助手」(canvas_ops)。\n你的目标：对 `*.canvas` / `*.canvas.ext` 的任何修改，都必须通过项目内的脚本执行；禁止手工编辑 JSON。\n\n唯一允许的执行入口：\n- `.dever/tools/canvas_ops/canvas_ops.sh`\n- 配置：`.dever/tools/canvas_ops/config.json`\n\n硬约束：\n- 你只能生成 `apply` 需要的 request JSON（version=1），并给出一条可执行命令来调用脚本。\n- 禁止直接输出/粘贴完整 `.canvas` 内容作为“修改后的文件”。\n- 如果需要删除 node：必须同时显式删除所有依赖该 node 的 edges（否则脚本会拒绝执行）。\n\n你的输出格式（两段，且仅两段）：\n(1) request JSON（纯 JSON，不要 markdown，不要 code fence）\n(2) 一段 bash 命令（用 heredoc 把 JSON 送进脚本；命令内必须显式传 `-w` 与 `-c`）\n\n命令模板（把 <WORKDIR> 替换为项目根；一般是 `.`）：\n.dever/tools/canvas_ops/canvas_ops.sh apply -w <WORKDIR> -c .dever/tools/canvas_ops/config.json --request-stdin <<'JSON'\n{...}\nJSON\n\n建议（可选）：命令后再跑一次 validate，确认写盘结果可读且 ext sha 一致。
diff --git a/skills/canvas-ops-v1/agents/openai.yaml b/skills/canvas-ops-v1/agents/openai.yaml
new file mode 100644
index 0000000..5566cff
--- /dev/null
+++ b/skills/canvas-ops-v1/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: Canvas Ops v1
+  short_description: Canvas Ops v1
+  default_prompt: Use $canvas-ops-v1.
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/canvas-tidy_selection-v1/SKILL.md b/skills/canvas-tidy_selection-v1/SKILL.md
new file mode 100644
index 0000000..0dbfdf1
--- /dev/null
+++ b/skills/canvas-tidy_selection-v1/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "canvas-tidy_selection-v1"
+description: "Canvas Tidy Selection v1"
+metadata:
+  short-description: "Canvas Tidy Selection v1"
+---
+
+# Canvas Tidy Selection v1
+
+你是「Canvas 会话块整理专家」(canvas_tidy_selection)。\n你的目标：为“画布上选中的会话块”提供一键自动整理（确定性布局、可复现）。\n\n硬约束：\n- 禁止建议用户手工编辑 `.canvas` / `.canvas.ext` JSON。\n- 不要输出“修改后的完整 canvas 文件内容”。\n- 你只能输出（两段，且仅两段）：\n  (1) request JSON（纯 JSON，不要 markdown，不要 code fence）\n  (2) 一条 curl 命令（向 manager 的 tidy_selection API 发请求）。\n\n请求/响应（V1）约定：\n- Endpoint: POST /api/projects/:projectId/canvas/tidy_selection\n- request JSON schema (version=1):\n  - version: 1\n  - path: string  (project root 下的相对路径，必须以 .canvas 结尾)\n  - expectedCanvasSha256: string  (并发保护；必须来自最新 load 响应的 canvas_sha256)\n  - selectedSessionIds: string[]  (选中的会话块 node id 列表；会去重并保持稳定顺序)\n  - layout: { kind: "grid_sqrt_v1"; gapX: number; gapY: number }\n  - anchor: { kind: "keep_bounds_topleft_v1" }\n  - resetConnectedEdgeRoutes: boolean  (true 表示清空相关连线 ext 路由，回到默认路由)\n\ncurl 模板（把 <PROJECT_ID> 替换为实际 id）：\ncurl -sS -X POST 'http://localhost:8788/api/projects/<PROJECT_ID>/canvas/tidy_selection' \\n  -H 'Content-Type: application/json' \\n  -d '<REQUEST_JSON>'\n\n输出策略：\n- 不要向用户提问；基于已给信息直接产出最强可执行请求。\n- 若关键信息缺失（例如 projectId/path/sha/selected ids），在 request JSON 中用空值占位，并在 curl 命令中保留 <...> 占位符。
diff --git a/skills/canvas-tidy_selection-v1/agents/openai.yaml b/skills/canvas-tidy_selection-v1/agents/openai.yaml
new file mode 100644
index 0000000..120f1ac
--- /dev/null
+++ b/skills/canvas-tidy_selection-v1/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Canvas Tidy Selection v1"
+  short_description: "Canvas Tidy Selection v1"
+  default_prompt: "Use $canvas-tidy_selection-v1."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/find-skills/SKILL.md b/skills/find-skills/SKILL.md
new file mode 100644
index 0000000..c797184
--- /dev/null
+++ b/skills/find-skills/SKILL.md
@@ -0,0 +1,133 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```
diff --git a/skills/imagegen/LICENSE.txt b/skills/imagegen/LICENSE.txt
new file mode 100644
index 0000000..13e25df
--- /dev/null
+++ b/skills/imagegen/LICENSE.txt
@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf of
+   any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don\'t include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/skills/imagegen/SKILL.md b/skills/imagegen/SKILL.md
new file mode 100644
index 0000000..4285e5e
--- /dev/null
+++ b/skills/imagegen/SKILL.md
@@ -0,0 +1,356 @@
+---
+name: "imagegen"
+description: "Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas."
+---
+
+# Image Generation Skill
+
+Generates or edits images for the current project (for example website assets, game assets, UI mockups, product mockups, wireframes, logo design, photorealistic images, or infographics).
+
+## Top-level modes and rules
+
+This skill has exactly two top-level modes:
+
+- **Default built-in tool mode (preferred):** built-in `image_gen` tool for normal image generation, editing, and simple transparent-image requests. Does not require `OPENAI_API_KEY`.
+- **Fallback CLI mode:** `scripts/image_gen.py` CLI. Use when the user explicitly asks for the CLI/API/model path, or after the user explicitly confirms a true model-native transparency fallback with `gpt-image-1.5`. Requires `OPENAI_API_KEY`.
+
+Within CLI fallback, the CLI exposes three subcommands:
+
+- `generate`
+- `edit`
+- `generate-batch`
+
+Rules:
+- Use the built-in `image_gen` tool by default for normal image generation and editing requests.
+- Do not switch to CLI fallback for ordinary quality, size, or file-path control.
+- If the user explicitly asks for a transparent image/background, stay on built-in `image_gen` first: prompt for a flat removable chroma-key background, then remove it locally with the installed helper at `$CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py`.
+- Never silently switch from built-in `image_gen` or CLI `gpt-image-2` to CLI `gpt-image-1.5`. Treat this as a model/path downgrade and ask the user before doing it, unless the user has already explicitly requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback.
+- If a transparent request appears too complex for clean chroma-key removal, asks for true/native transparency, or local removal fails validation, explain that true transparency requires CLI `gpt-image-1.5 --background transparent --output-format png` because `gpt-image-2` does not support `background=transparent`, then ask whether to proceed. Run the CLI fallback only after the user confirms.
+- The word `batch` by itself does not mean CLI fallback. If the user asks for many assets or says to batch-generate assets without explicitly asking for CLI/API/model controls, stay on the built-in path and issue one built-in call per requested asset or variant.
+- If the built-in tool fails or is unavailable, tell the user the CLI fallback exists and that it requires `OPENAI_API_KEY`. Proceed only if the user explicitly asks for that fallback.
+- If the user explicitly asks for CLI mode, use the bundled `scripts/image_gen.py` workflow. Do not create one-off SDK runners.
+- Never modify `scripts/image_gen.py`. If something is missing, ask the user before doing anything else.
+
+Built-in save-path policy:
+- In built-in tool mode, Codex saves generated images under `$CODEX_HOME/*` by default.
+- Do not describe or rely on OS temp as the default built-in destination.
+- Do not describe or rely on a destination-path argument (if any) on the built-in `image_gen` tool. If a specific location is needed, generate first and then move or copy the selected output from `$CODEX_HOME/generated_images/...`.
+- Save-path precedence in built-in mode:
+  1. If the user names a destination, move or copy the selected output there.
+  2. If the image is meant for the current project, move or copy the final selected image into the workspace before finishing.
+  3. If the image is only for preview or brainstorming, render it inline; the underlying file can remain at the default `$CODEX_HOME/*` path.
+- Never leave a project-referenced asset only at the default `$CODEX_HOME/*` path.
+- Do not overwrite an existing asset unless the user explicitly asked for replacement; otherwise create a sibling versioned filename such as `hero-v2.png` or `item-icon-edited.png`.
+
+Shared prompt guidance for both modes lives in `references/prompting.md` and `references/sample-prompts.md`.
+
+Fallback-only docs/resources for CLI mode:
+- `references/cli.md`
+- `references/image-api.md`
+- `references/codex-network.md`
+- `scripts/image_gen.py`
+
+Local post-processing helper:
+- `$CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py`: removes a flat chroma-key background from a generated image and writes a PNG/WebP with alpha. Prefer auto-key sampling, soft matte, and despill for antialiased edges.
+
+## When to use
+- Generate a new image (concept art, product shot, cover, website hero)
+- Generate a new image using one or more reference images for style, composition, or mood
+- Edit an existing image (inpainting, lighting or weather transformations, background replacement, object removal, compositing, transparent background)
+- Produce many assets or variants for one task
+
+## When not to use
+- Extending or matching an existing SVG/vector icon set, logo system, or illustration library inside the repo
+- Creating simple shapes, diagrams, wireframes, or icons that are better produced directly in SVG, HTML/CSS, or canvas
+- Making a small project-local asset edit when the source file already exists in an editable native format
+- Any task where the user clearly wants deterministic code-native output instead of a generated bitmap
+
+## Decision tree
+
+Think about two separate questions:
+
+1. **Intent:** is this a new image or an edit of an existing image?
+2. **Execution strategy:** is this one asset or many assets/variants?
+
+Intent:
+- If the user wants to modify an existing image while preserving parts of it, treat the request as **edit**.
+- If the user provides images only as references for style, composition, mood, or subject guidance, treat the request as **generate**.
+- If the user provides no images, treat the request as **generate**.
+
+Built-in edit semantics:
+- Built-in edit mode is for images already visible in the conversation context, such as attached images or images generated earlier in the thread.
+- If the user wants to edit a local image file with the built-in tool, first load it with built-in `view_image` tool so the image is visible in the conversation context, then proceed with the built-in edit flow.
+- Do not promise arbitrary filesystem-path editing through the built-in tool.
+- If a local file still needs direct file-path control, masks, or other explicit CLI-only parameters, use the explicit CLI fallback only when the user asks for it.
+- For edits, preserve invariants aggressively and save non-destructively by default.
+
+Execution strategy:
+- In the built-in default path, produce many assets or variants by issuing one `image_gen` call per requested asset or variant.
+- In the CLI fallback path, use the CLI `generate-batch` subcommand only when the user explicitly chose CLI mode and needs many prompts/assets.
+- For many distinct assets, do not use `n` as a substitute for separate prompts. `n` is for variants of one prompt; distinct assets need distinct built-in calls or distinct CLI `generate-batch` jobs.
+
+Assume the user wants a new image unless they clearly ask to change an existing one.
+
+## Workflow
+1. Decide the top-level mode: built-in by default, including simple transparent-output requests; fallback CLI only if explicitly requested or after the user explicitly confirms a transparent-output fallback.
+2. Decide the intent: `generate` or `edit`.
+3. Decide whether the output is preview-only or meant to be consumed by the current project.
+4. Decide the execution strategy: single asset vs repeated built-in calls vs CLI `generate-batch`.
+5. Collect inputs up front: prompt(s), exact text (verbatim), constraints/avoid list, and any input images.
+6. For every input image, label its role explicitly:
+   - reference image
+   - edit target
+   - supporting insert/style/compositing input
+7. If the edit target is only on the local filesystem and you are staying on the built-in path, inspect it with `view_image` first so the image is available in conversation context.
+8. If the user asked for a photo, illustration, sprite, product image, banner, or other explicitly raster-style asset, use `image_gen` rather than substituting SVG/HTML/CSS placeholders. If the request is for an icon, logo, or UI graphic that should match existing repo-native SVG/vector/code assets, prefer editing those directly instead.
+9. Augment the prompt based on specificity:
+   - If the user's prompt is already specific and detailed, normalize it into a clear spec without adding creative requirements.
+   - If the user's prompt is generic, add tasteful augmentation only when it materially improves output quality.
+10. Use the built-in `image_gen` tool by default.
+11. For transparent-output requests, follow the transparent image guidance below: generate with built-in `image_gen` on a flat chroma-key background, copy the selected output into the workspace or `tmp/imagegen/`, run the installed `$CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py` helper, and validate the alpha result before using it. If this path looks unsuitable or fails, ask before switching to CLI `gpt-image-1.5`.
+12. Inspect outputs and validate: subject, style, composition, text accuracy, and invariants/avoid items.
+13. Iterate with a single targeted change, then re-check.
+14. For preview-only work, render the image inline; the underlying file may remain at the default `$CODEX_HOME/generated_images/...` path.
+15. For project-bound work, move or copy the selected artifact into the workspace and update any consuming code or references. Never leave a project-referenced asset only at the default `$CODEX_HOME/generated_images/...` path.
+16. For batches or multi-asset requests, persist every requested deliverable final in the workspace unless the user explicitly asked to keep outputs preview-only. Discarded variants do not need to be kept unless requested.
+17. If the user explicitly chooses or confirms the CLI fallback, then use the fallback-only docs for model, quality, size, `input_fidelity`, masks, output format, output paths, and network setup.
+18. Always report the final saved path(s) for any workspace-bound asset(s), plus the final prompt or prompt set and whether the built-in tool or fallback CLI mode was used.
+
+## Transparent image requests
+
+Transparent-image requests still use built-in `image_gen` first. Because the built-in tool does not expose a true transparent-background control, create a removable chroma-key source image and then convert the key color to alpha locally.
+
+Default sequence:
+1. Use built-in `image_gen` to generate the requested subject on a perfectly flat solid chroma-key background.
+2. Choose a key color that is unlikely to appear in the subject: default `#00ff00`, use `#ff00ff` for green subjects, and avoid `#0000ff` for blue subjects.
+3. After generation, move or copy the selected source image from `$CODEX_HOME/generated_images/...` into the workspace or `tmp/imagegen/`.
+4. Run the installed helper path, not a project-relative script path:
+   ```bash
+   python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" \
+     --input <source> \
+     --out <final.png> \
+     --auto-key border \
+     --soft-matte \
+     --transparent-threshold 12 \
+     --opaque-threshold 220 \
+     --despill
+   ```
+5. Validate that the output has an alpha channel, transparent corners, plausible subject coverage, and no obvious key-color fringe. If a thin fringe remains, retry once with `--edge-contract 1`; use `--edge-feather 0.25` only when the edge is visibly stair-stepped and the subject is not shiny or reflective.
+6. Save the final alpha PNG/WebP in the project if the asset is project-bound. Never leave a project-referenced transparent asset only under `$CODEX_HOME/*`.
+
+Prompt transparent requests like this:
+
+```text
+Create the requested subject on a perfectly flat solid #00ff00 chroma-key background for background removal.
+The background must be one uniform color with no shadows, gradients, texture, reflections, floor plane, or lighting variation.
+Keep the subject fully separated from the background with crisp edges and generous padding.
+Do not use #00ff00 anywhere in the subject.
+No cast shadow, no contact shadow, no reflection, no watermark, and no text unless explicitly requested.
+```
+
+Do not automatically use CLI `gpt-image-1.5 --background transparent --output-format png` instead of chroma keying. Ask the user first when the user asks for true/native transparency, when local removal fails validation, or when the requested image is complex: hair, fur, feathers, smoke, glass, liquids, translucent materials, reflective objects, soft shadows, realistic product grounding, or subject colors that conflict with all practical key colors.
+
+Use a concise confirmation like:
+
+```text
+This likely needs true native transparency. The default built-in path uses a chroma-key background plus local removal, but true transparency requires the CLI fallback with gpt-image-1.5 because gpt-image-2 does not support background=transparent. It also requires OPENAI_API_KEY. Should I proceed with that CLI fallback?
+```
+
+## Prompt augmentation
+
+Reformat user prompts into a structured, production-oriented spec. Make the user's goal clearer and more actionable, but do not blindly add detail.
+
+Treat this as prompt-shaping guidance, not a closed schema. Use only the lines that help, and add a short extra labeled line when it materially improves clarity.
+
+### Specificity policy
+
+Use the user's prompt specificity to decide how much augmentation is appropriate:
+
+- If the prompt is already specific and detailed, preserve that specificity and only normalize/structure it.
+- If the prompt is generic, you may add tasteful augmentation when it will materially improve the result.
+
+Allowed augmentations:
+- composition or framing hints
+- polish level or intended-use hints
+- practical layout guidance
+- reasonable scene concreteness that supports the stated request
+
+Not allowed augmentations:
+- extra characters or objects that are not implied by the request
+- brand names, slogans, palettes, or narrative beats that are not implied
+- arbitrary side-specific placement unless the surrounding layout supports it
+
+## Use-case taxonomy (exact slugs)
+
+Classify each request into one of these buckets and keep the slug consistent across prompts and references.
+
+Generate:
+- photorealistic-natural — candid/editorial lifestyle scenes with real texture and natural lighting.
+- product-mockup — product/packaging shots, catalog imagery, merch concepts.
+- ui-mockup — app/web interface mockups and wireframes; specify the desired fidelity.
+- infographic-diagram — diagrams/infographics with structured layout and text.
+- scientific-educational — classroom explainers, scientific diagrams, and learning visuals with required labels and accuracy constraints.
+- ads-marketing — campaign concepts and ad creatives with audience, brand position, scene, and exact tagline/copy.
+- productivity-visual — slide, chart, workflow, and data-heavy business visuals.
+- logo-brand — logo/mark exploration, vector-friendly.
+- illustration-story — comics, children’s book art, narrative scenes.
+- stylized-concept — style-driven concept art, 3D/stylized renders.
+- historical-scene — period-accurate/world-knowledge scenes.
+
+Edit:
+- text-localization — translate/replace in-image text, preserve layout.
+- identity-preserve — try-on, person-in-scene; lock face/body/pose.
+- precise-object-edit — remove/replace a specific element (including interior swaps).
+- lighting-weather — time-of-day/season/atmosphere changes only.
+- background-extraction — transparent background / clean cutout. Use built-in `image_gen` with chroma-key removal first for simple opaque subjects; ask before using CLI true transparency for complex subjects.
+- style-transfer — apply reference style while changing subject/scene.
+- compositing — multi-image insert/merge with matched lighting/perspective.
+- sketch-to-render — drawing/line art to photoreal render.
+
+## Shared prompt schema
+
+Use the following labeled spec as shared prompt scaffolding for both top-level modes:
+
+```text
+Use case: <taxonomy slug>
+Asset type: <where the asset will be used>
+Primary request: <user's main prompt>
+Input images: <Image 1: role; Image 2: role> (optional)
+Scene/backdrop: <environment>
+Subject: <main subject>
+Style/medium: <photo/illustration/3D/etc>
+Composition/framing: <wide/close/top-down; placement>
+Lighting/mood: <lighting + mood>
+Color palette: <palette notes>
+Materials/textures: <surface details>
+Text (verbatim): "<exact text>"
+Constraints: <must keep/must avoid>
+Avoid: <negative constraints>
+```
+
+Notes:
+- `Asset type` and `Input images` are prompt scaffolding, not dedicated CLI flags.
+- `Scene/backdrop` refers to the visual setting. It is not the same as the fallback CLI `background` parameter, which controls output transparency behavior.
+- Fallback-only execution notes such as `Quality:`, `Input fidelity:`, masks, output format, and output paths belong in the CLI path only. Do not treat them as built-in `image_gen` tool arguments.
+
+Augmentation rules:
+- Keep it short.
+- Add only the details needed to improve the prompt materially.
+- For edits, explicitly list invariants (`change only X; keep Y unchanged`).
+- If any critical detail is missing and blocks success, ask a question; otherwise proceed.
+
+## Examples
+
+### Generation example (hero image)
+```text
+Use case: product-mockup
+Asset type: landing page hero
+Primary request: a minimal hero image of a ceramic coffee mug
+Style/medium: clean product photography
+Composition/framing: wide composition with usable negative space for page copy if needed
+Lighting/mood: soft studio lighting
+Constraints: no logos, no text, no watermark
+```
+
+### Edit example (invariants)
+```text
+Use case: precise-object-edit
+Asset type: product photo background replacement
+Primary request: replace only the background with a warm sunset gradient
+Constraints: change only the background; keep the product and its edges unchanged; no text; no watermark
+```
+
+## Prompting best practices
+- Structure prompt as scene/backdrop -> subject -> details -> constraints.
+- Include intended use (ad, UI mock, infographic) to set the mode and polish level.
+- Use camera/composition language for photorealism.
+- Only use SVG/vector stand-ins when the user explicitly asked for vector output or a non-image placeholder.
+- Quote exact text and specify typography + placement.
+- For tricky words, spell them letter-by-letter and require verbatim rendering.
+- For multi-image inputs, reference images by index and describe how they should be used.
+- For edits, repeat invariants every iteration to reduce drift.
+- Iterate with single-change follow-ups.
+- If the prompt is generic, add only the extra detail that will materially help.
+- If the prompt is already detailed, normalize it instead of expanding it.
+- For CLI fallback only, see `references/cli.md` and `references/image-api.md` for model, `quality`, `input_fidelity`, masks, output format, and output-path guidance.
+- For transparent images, use the built-in-first chroma-key workflow unless the request is complex enough to need true CLI transparency; ask before switching to CLI `gpt-image-1.5`.
+
+More principles shared by both modes: `references/prompting.md`.
+Copy/paste specs shared by both modes: `references/sample-prompts.md`.
+
+## Guidance by asset type
+Asset-type templates (website assets, game assets, wireframes, logo) are consolidated in `references/sample-prompts.md`.
+
+## gpt-image-2 guidance for CLI fallback
+
+The fallback CLI defaults to `gpt-image-2`.
+
+- Use `gpt-image-2` for new CLI/API workflows unless the request needs true model-native transparent output.
+- If a transparent request may need CLI fallback, ask before using `gpt-image-1.5` unless the user already explicitly requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback. Explain that the built-in chroma-key path is the default, but true transparency requires `gpt-image-1.5` because `gpt-image-2` does not support `background=transparent`.
+- `gpt-image-2` always uses high fidelity for image inputs; do not set `input_fidelity` with this model.
+- `gpt-image-2` supports `quality` values `low`, `medium`, `high`, and `auto`.
+- Use `quality low` for fast drafts, thumbnails, and quick iterations. Use `medium`, `high`, or `auto` for final assets, dense text, diagrams, identity-sensitive edits, or high-resolution outputs.
+- Square images are typically fastest to generate. Use `1024x1024` for fast square drafts.
+- If the user asks for 4K-style output, use `3840x2160` for landscape or `2160x3840` for portrait.
+- `gpt-image-2` size may be `auto` or `WIDTHxHEIGHT` if all constraints hold: max edge `<= 3840px`, both edges multiples of `16px`, long-to-short ratio `<= 3:1`, total pixels between `655,360` and `8,294,400`.
+
+Popular `gpt-image-2` sizes:
+- `1024x1024` square
+- `1536x1024` landscape
+- `1024x1536` portrait
+- `2048x2048` 2K square
+- `2048x1152` 2K landscape
+- `3840x2160` 4K landscape
+- `2160x3840` 4K portrait
+- `auto`
+
+## Fallback CLI mode only
+
+### Temp and output conventions
+These conventions apply only to the CLI fallback. They do not describe built-in `image_gen` output behavior.
+- Use `tmp/imagegen/` for intermediate files (for example JSONL batches); delete them when done.
+- Write final artifacts under `output/imagegen/`.
+- Use `--out` or `--out-dir` to control output paths; keep filenames stable and descriptive.
+
+### Dependencies
+Prefer `uv` for dependency management in this repo.
+
+Required Python package:
+```bash
+uv pip install openai
+```
+
+Required for local chroma-key removal and optional downscaling:
+```bash
+uv pip install pillow
+```
+
+Portability note:
+- If you are using the installed skill outside this repo, install dependencies into that environment with its package manager.
+- In uv-managed environments, `uv pip install ...` remains the preferred path.
+
+### Environment
+- `OPENAI_API_KEY` must be set for live API calls.
+- Do not ask the user for `OPENAI_API_KEY` when using the built-in `image_gen` tool.
+- Never ask the user to paste the full key in chat. Ask them to set it locally and confirm when ready.
+
+If the key is missing, give the user these steps:
+1. Create an API key in the OpenAI platform UI: https://platform.openai.com/api-keys
+2. Set `OPENAI_API_KEY` as an environment variable in their system.
+3. Offer to guide them through setting the environment variable for their OS/shell if needed.
+
+If installation is not possible in this environment, tell the user which dependency is missing and how to install it into their active environment.
+
+### Script-mode notes
+- CLI commands + examples: `references/cli.md`
+- API parameter quick reference: `references/image-api.md`
+- Network approvals / sandbox settings for CLI mode: `references/codex-network.md`
+
+## Reference map
+- `references/prompting.md`: shared prompting principles for both modes.
+- `references/sample-prompts.md`: shared copy/paste prompt recipes for both modes.
+- `references/cli.md`: fallback-only CLI usage via `scripts/image_gen.py`.
+- `references/image-api.md`: fallback-only API/CLI parameter reference.
+- `references/codex-network.md`: fallback-only network/sandbox troubleshooting for CLI mode.
+- `scripts/image_gen.py`: fallback-only CLI implementation. Do not load or use it unless the user explicitly chooses CLI mode or explicitly confirms a transparent request's true CLI transparency fallback.
+- `$CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py`: local post-processing helper for built-in transparent-image requests.
diff --git a/skills/imagegen/agents/openai.yaml b/skills/imagegen/agents/openai.yaml
new file mode 100644
index 0000000..5e01d44
--- /dev/null
+++ b/skills/imagegen/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Image Gen"
+  short_description: "Generate or edit images for websites, games, and more"
+  icon_small: "./assets/imagegen-small.svg"
+  icon_large: "./assets/imagegen.png"
+  default_prompt: "Use $imagegen to make or edit an image for this project."
diff --git a/skills/imagegen/assets/imagegen-small.svg b/skills/imagegen/assets/imagegen-small.svg
new file mode 100644
index 0000000..20128b2
--- /dev/null
+++ b/skills/imagegen/assets/imagegen-small.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
+  <path fill="currentColor" d="M7.51 6.827a1 1 0 1 1 .278 1.982 1 1 0 0 1-.278-1.982Z"/>
+  <path fill="currentColor" fill-rule="evenodd" d="M8.31 4.47c.368-.016.699.008 1.016.124l.186.075c.423.194.786.5 1.047.888l.067.107c.148.253.235.533.3.848.073.354.126.797.193 1.343l.277 2.25.088.745c.024.224.041.425.049.605.013.322-.004.615-.085.896l-.04.12a2.53 2.53 0 0 1-.802 1.115l-.16.118c-.281.189-.596.292-.956.366a9.46 9.46 0 0 1-.6.1l-.743.094-2.25.277c-.547.067-.99.121-1.35.136a2.765 2.765 0 0 1-.896-.085l-.12-.039a2.533 2.533 0 0 1-1.115-.802l-.118-.161c-.189-.28-.292-.596-.366-.956a9.42 9.42 0 0 1-.1-.599l-.094-.744-.276-2.25a17.884 17.884 0 0 1-.137-1.35c-.015-.367.009-.698.124-1.015l.076-.185c.193-.423.5-.787.887-1.048l.107-.067c.253-.148.534-.234.849-.3.354-.073.796-.126 1.343-.193l2.25-.277.744-.088c.224-.024.425-.041.606-.049Zm-2.905 5.978a1.47 1.47 0 0 0-.875.074c-.127.052-.267.146-.475.344-.212.204-.462.484-.822.889l-.314.351c.018.115.036.219.055.313.061.295.127.458.206.575l.07.094c.167.211.39.372.645.465l.109.032c.119.027.273.038.499.029.308-.013.7-.06 1.264-.13l2.25-.275.727-.093.198-.03-2.05-1.64a16.848 16.848 0 0 0-.96-.738c-.18-.121-.31-.19-.421-.23l-.106-.03Zm2.95-4.915c-.154.006-.33.021-.536.043l-.729.086-2.25.276c-.564.07-.956.118-1.257.18a1.937 1.937 0 0 0-.478.15l-.097.057a1.47 1.47 0 0 0-.515.608l-.044.107c-.048.133-.073.307-.06.608.012.307.06.7.129 1.264l.22 1.8.178-.197c.145-.159.278-.298.403-.418.255-.243.507-.437.809-.56l.181-.067a2.526 2.526 0 0 1 1.328-.06l.118.029c.27.079.517.215.772.387.287.194.619.46 1.03.789l2.52 2.016c.146-.148.26-.326.332-.524l.031-.109c.027-.119.039-.273.03-.499a8.311 8.311 0 0 0-.044-.536l-.086-.728-.276-2.25c-.07-.564-.118-.956-.18-1.258a1.935 1.935 0 0 0-.15-.477l-.057-.098a1.468 1.468 0 0 0-.608-.515l-.107-.043c-.133-.049-.306-.074-.607-.061Z" clip-rule="evenodd"/>
+  <path fill="currentColor" d="M7.783 1.272c.36.014.803.07 1.35.136l2.25.277.743.095c.224.03.423.062.6.099.36.074.675.177.955.366l.161.118c.364.29.642.675.802 1.115l.04.12c.081.28.098.574.085.896a9.42 9.42 0 0 1-.05.605l-.087.745-.277 2.25c-.067.547-.12.989-.193 1.343a2.765 2.765 0 0 1-.3.848l-.067.107a2.534 2.534 0 0 1-.415.474l-.086.064a.532.532 0 0 1-.622-.858l.13-.13c.04-.046.077-.094.111-.145l.057-.098c.055-.109.104-.256.15-.477.062-.302.11-.694.18-1.258l.276-2.25.086-.728c.022-.207.037-.382.043-.536.01-.226-.002-.38-.029-.5l-.032-.108a1.469 1.469 0 0 0-.464-.646l-.094-.069c-.118-.08-.28-.145-.575-.206a8.285 8.285 0 0 0-.53-.088l-.728-.092-2.25-.276c-.565-.07-.956-.117-1.264-.13a1.94 1.94 0 0 0-.5.029l-.108.032a1.469 1.469 0 0 0-.647.465l-.068.094c-.054.08-.102.18-.146.33l-.04.1a.533.533 0 0 1-.98-.403l.055-.166c.059-.162.133-.314.23-.457l.117-.16c.29-.365.675-.643 1.115-.803l.12-.04c.28-.08.574-.097.896-.084Z"/>
+</svg>
diff --git a/skills/imagegen/assets/imagegen.png b/skills/imagegen/assets/imagegen.png
new file mode 100644
index 0000000..94b5454
Binary files /dev/null and b/skills/imagegen/assets/imagegen.png differ
diff --git a/skills/imagegen/references/cli.md b/skills/imagegen/references/cli.md
new file mode 100644
index 0000000..f4a5a63
--- /dev/null
+++ b/skills/imagegen/references/cli.md
@@ -0,0 +1,242 @@
+# CLI reference (`scripts/image_gen.py`)
+
+This file is for the fallback CLI mode only. Read it when the user explicitly asks to use `scripts/image_gen.py` / CLI / API / model controls, or after the user explicitly confirms that a transparent-output request should use the `gpt-image-1.5` true-transparency fallback path.
+
+`generate-batch` is a CLI subcommand in this fallback path. It is not a top-level mode of the skill.
+The word `batch` in a user request is not CLI opt-in by itself.
+
+## What this CLI does
+- `generate`: generate a new image from a prompt
+- `edit`: edit one or more existing images
+- `generate-batch`: run many generation jobs from a JSONL file after the user explicitly chooses CLI/API/model controls
+
+Real API calls require **network access** + `OPENAI_API_KEY`. `--dry-run` does not.
+
+## Quick start (works from any repo)
+Set a stable path to the skill CLI (default `CODEX_HOME` is `~/.codex`):
+
+```
+export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+export IMAGE_GEN="$CODEX_HOME/skills/.system/imagegen/scripts/image_gen.py"
+```
+
+Install dependencies into that environment with its package manager. In uv-managed environments, `uv pip install ...` remains the preferred path.
+
+## Quick start
+
+Dry-run (no API call; no network required; does not require the `openai` package):
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "Test" \
+  --out output/imagegen/test.png \
+  --dry-run
+```
+
+Notes:
+- One-off dry-runs print the API payload and the computed output path(s).
+- Repo-local finals should live under `output/imagegen/`.
+
+Generate (requires `OPENAI_API_KEY` + network):
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "A cozy alpine cabin at dawn" \
+  --size 1024x1024 \
+  --out output/imagegen/alpine-cabin.png
+```
+
+Edit:
+
+```bash
+python "$IMAGE_GEN" edit \
+  --image input.png \
+  --prompt "Replace only the background with a warm sunset" \
+  --out output/imagegen/sunset-edit.png
+```
+
+## Guardrails
+- Use the bundled CLI directly (`python "$IMAGE_GEN" ...`) after activating the correct environment.
+- Do **not** create one-off runners (for example `gen_images.py`) unless the user explicitly asks for a custom wrapper.
+- **Never modify** `scripts/image_gen.py`. If something is missing, ask the user before doing anything else.
+- Do not silently downgrade from CLI `gpt-image-2` or built-in `image_gen` to CLI `gpt-image-1.5`; ask first unless the user already explicitly requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback.
+
+## Defaults
+- Model: `gpt-image-2`
+- Supported model family for this CLI: GPT Image models (`gpt-image-*`)
+- Size: `auto`
+- Quality: `medium`
+- Output format: `png`
+- Default one-off output path: `output/imagegen/output.png`
+- Background: unspecified unless `--background` is set
+
+## gpt-image-2 size and model guidance
+
+`gpt-image-2` is the default model for new CLI fallback work.
+
+- Use `--quality low` for fast drafts, thumbnails, and quick iterations.
+- Use `--quality medium`, `--quality high`, or `--quality auto` for final assets, dense text, diagrams, identity-sensitive edits, and high-resolution outputs.
+- Square images are typically fastest. Use `--size 1024x1024` for quick square drafts.
+- If the user asks for 4K-style output, use `--size 3840x2160` for landscape or `--size 2160x3840` for portrait.
+- Do not pass `--input-fidelity` with `gpt-image-2`; this model always uses high fidelity for image inputs.
+- Do not use `--background transparent` with `gpt-image-2`; the default transparent-image workflow uses built-in `image_gen` on a flat chroma-key background plus local removal. Use `gpt-image-1.5` only after the user explicitly confirms the true-transparent CLI fallback, unless they already requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback.
+
+Popular `gpt-image-2` sizes:
+- `1024x1024`
+- `1536x1024`
+- `1024x1536`
+- `2048x2048`
+- `2048x1152`
+- `3840x2160`
+- `2160x3840`
+- `auto`
+
+`gpt-image-2` size constraints:
+- max edge `<= 3840px`
+- both edges multiples of `16px`
+- long edge to short edge ratio `<= 3:1`
+- total pixels between `655,360` and `8,294,400`
+- outputs above `2560x1440` total pixels are experimental
+
+Fast draft:
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "A product thumbnail of a matte ceramic mug on a stone surface" \
+  --quality low \
+  --size 1024x1024 \
+  --out output/imagegen/mug-draft.png
+```
+
+Final 2K landscape:
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "A polished landing-page hero image of a matte ceramic mug on a stone surface" \
+  --quality high \
+  --size 2048x1152 \
+  --out output/imagegen/mug-hero.png
+```
+
+4K landscape:
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "A detailed architectural visualization at golden hour" \
+  --size 3840x2160 \
+  --quality high \
+  --out output/imagegen/architecture-4k.png
+```
+
+True transparent fallback request:
+
+Ask for confirmation before using this command unless the user already explicitly requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback.
+
+```bash
+python "$IMAGE_GEN" generate \
+  --model gpt-image-1.5 \
+  --prompt "A clean product cutout on a transparent background" \
+  --background transparent \
+  --output-format png \
+  --out output/imagegen/product-cutout.png
+```
+
+When using this path, explain briefly that built-in `image_gen` plus chroma-key removal is the default transparent-image path, but this request needs true model-native transparency. `gpt-image-2` does not support `background=transparent`, so `gpt-image-1.5` is required for this confirmed fallback.
+
+## Quality, input fidelity, and masks (CLI fallback only)
+These are explicit CLI controls. They are not built-in `image_gen` tool arguments.
+
+- `--quality` works for `generate`, `edit`, and `generate-batch`: `low|medium|high|auto`
+- `--input-fidelity` is **edit-only** and validated as `low|high`; it is not supported for `gpt-image-2`
+- `--mask` is **edit-only**
+
+Example:
+
+```bash
+python "$IMAGE_GEN" edit \
+  --model gpt-image-1.5 \
+  --image input.png \
+  --prompt "Change only the background" \
+  --quality high \
+  --input-fidelity high \
+  --out output/imagegen/background-edit.png
+```
+
+Mask notes:
+- For multi-image edits, pass repeated `--image` flags. Their order is meaningful, so describe each image by index and role in the prompt.
+- The CLI accepts a single `--mask`.
+- Image and mask must be the same size and format and each under 50MB.
+- Masks must include an alpha channel.
+- If multiple input images are provided, the mask applies to the first image.
+- Masking is prompt-guided; do not promise exact pixel-perfect mask boundaries.
+- Use a PNG mask when possible; the script treats mask handling as best-effort and does not perform full preflight validation beyond file checks/warnings.
+- In the edit prompt, repeat invariants (`change only the background; keep the subject unchanged`) to reduce drift.
+
+## Output handling
+- Use `tmp/imagegen/` for temporary JSONL inputs or scratch files.
+- Use `output/imagegen/` for final outputs.
+- Reruns fail if a target file already exists unless you pass `--force`.
+- `--out-dir` changes one-off naming to `image_1.<ext>`, `image_2.<ext>`, and so on.
+- Downscaled copies use the default suffix `-web` unless you override it.
+
+## Common recipes
+
+Generate with augmentation fields:
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "A minimal hero image of a ceramic coffee mug" \
+  --use-case "product-mockup" \
+  --style "clean product photography" \
+  --composition "wide product shot with usable negative space for page copy" \
+  --constraints "no logos, no text" \
+  --out output/imagegen/mug-hero.png
+```
+
+Generate + also write a downscaled copy for fast web loading:
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "A cozy alpine cabin at dawn" \
+  --size 1024x1024 \
+  --downscale-max-dim 1024 \
+  --out output/imagegen/alpine-cabin.png
+```
+
+Generate multiple prompts concurrently (async batch):
+
+```bash
+mkdir -p tmp/imagegen output/imagegen/batch
+cat > tmp/imagegen/prompts.jsonl << 'EOF'
+{"prompt":"Cavernous hangar interior with a compact shuttle parked near the center","use_case":"stylized-concept","composition":"wide-angle, low-angle","lighting":"volumetric light rays through drifting fog","constraints":"no logos or trademarks; no watermark","size":"1536x1024"}
+{"prompt":"Gray wolf in profile in a snowy forest","use_case":"photorealistic-natural","composition":"eye-level","constraints":"no logos or trademarks; no watermark","size":"1024x1024"}
+EOF
+
+python "$IMAGE_GEN" generate-batch \
+  --input tmp/imagegen/prompts.jsonl \
+  --out-dir output/imagegen/batch \
+  --concurrency 5
+
+rm -f tmp/imagegen/prompts.jsonl
+```
+
+Notes:
+- `generate-batch` requires `--out-dir`.
+- generate-batch requires --out-dir.
+- Use `--concurrency` to control parallelism (default `5`).
+- Per-job overrides are supported in JSONL (for example `size`, `quality`, `background`, `output_format`, `output_compression`, `moderation`, `n`, `model`, `out`, and prompt-augmentation fields).
+- `--n` generates multiple variants for a single prompt; `generate-batch` is for many different prompts.
+- In batch mode, per-job `out` is treated as a filename under `--out-dir`.
+- For many requested deliverable assets, provide one prompt/job per distinct asset and use semantic filenames when possible.
+
+## CLI notes
+- Supported sizes depend on the model. `gpt-image-2` supports flexible constrained sizes; older GPT Image models support `1024x1024`, `1536x1024`, `1024x1536`, or `auto`.
+- True transparent CLI outputs require `output_format` to be `png` or `webp` and are not supported by `gpt-image-2`.
+- `--prompt-file`, `--output-compression`, `--moderation`, `--max-attempts`, `--fail-fast`, `--force`, and `--no-augment` are supported.
+- This CLI is intended for GPT Image models. Do not assume older non-GPT image-model behavior applies here.
+
+## See also
+- API parameter quick reference for fallback CLI mode: `references/image-api.md`
+- Prompt examples shared across both top-level modes: `references/sample-prompts.md`
+- Network/sandbox notes for fallback CLI mode: `references/codex-network.md`
+- Built-in-first transparent image workflow: `SKILL.md` and `$CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py`
diff --git a/skills/imagegen/references/codex-network.md b/skills/imagegen/references/codex-network.md
new file mode 100644
index 0000000..5ce1fbc
--- /dev/null
+++ b/skills/imagegen/references/codex-network.md
@@ -0,0 +1,33 @@
+# Codex network approvals / sandbox notes
+
+This file is for the fallback CLI mode only. Read it when the user explicitly asks to use `scripts/image_gen.py` / CLI / API / model controls, or after the user explicitly confirms that a transparent-output request should use the `gpt-image-1.5` true-transparency fallback path.
+
+This guidance is intentionally isolated from `SKILL.md` because it can vary by environment and may become stale. Prefer the defaults in your environment when in doubt.
+
+## Why am I asked to approve image generation calls?
+The fallback CLI uses the OpenAI Image API, so it needs outbound network access. In many Codex setups, network access is disabled by default and/or the approval policy requires confirmation before networked commands run.
+
+## Important note about approvals vs network
+- `--ask-for-approval never` suppresses approval prompts.
+- It does **not** by itself enable network access.
+- In `workspace-write`, network access still depends on your Codex configuration (for example `[sandbox_workspace_write] network_access = true`).
+
+## How do I reduce repeated approval prompts?
+If you trust the repo and want fewer prompts, use a configuration or profile that both:
+- enables network for the sandbox mode you plan to use
+- sets an approval policy that matches your risk tolerance
+
+Example `~/.codex/config.toml` pattern:
+
+```toml
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+
+[sandbox_workspace_write]
+network_access = true
+```
+
+If you want quieter automation after network is enabled, you can choose a stricter approval policy, but do that intentionally and with care.
+
+## Safety note
+Enabling network and reducing approvals lowers friction, but increases risk if you run untrusted code or work in an untrusted repository.
diff --git a/skills/imagegen/references/image-api.md b/skills/imagegen/references/image-api.md
new file mode 100644
index 0000000..db8567d
--- /dev/null
+++ b/skills/imagegen/references/image-api.md
@@ -0,0 +1,90 @@
+# Image API quick reference
+
+This file is for the fallback CLI mode only. Use it when the user explicitly asks to use `scripts/image_gen.py` / CLI / API / model controls, or after the user explicitly confirms that a transparent-output request should use the `gpt-image-1.5` true-transparency fallback path.
+
+These parameters describe the Image API and bundled CLI fallback surface. Do not assume they are normal arguments on the built-in `image_gen` tool.
+
+## Scope
+- This fallback CLI is intended for GPT Image models (`gpt-image-2`, `gpt-image-1.5`, `gpt-image-1`, and `gpt-image-1-mini`).
+- The built-in `image_gen` tool and the fallback CLI do not expose the same controls.
+
+## Model summary
+
+| Model | Quality | Input fidelity | Resolutions | Recommended use |
+| --- | --- | --- | --- | --- |
+| `gpt-image-2` | `low`, `medium`, `high`, `auto` | Always high fidelity for image inputs; do not set `input_fidelity` | `auto` or flexible sizes that satisfy the constraints below | Default for new CLI/API workflows: high-quality generation and editing, text-heavy images, photorealism, compositing, identity-sensitive edits, and workflows where fewer retries matter |
+| `gpt-image-1.5` | `low`, `medium`, `high`, `auto` | `low`, `high` | `1024x1024`, `1024x1536`, `1536x1024`, `auto` | True transparent-background fallback and backward-compatible workflows |
+| `gpt-image-1` | `low`, `medium`, `high`, `auto` | `low`, `high` | `1024x1024`, `1024x1536`, `1536x1024`, `auto` | Legacy compatibility |
+| `gpt-image-1-mini` | `low`, `medium`, `high`, `auto` | `low`, `high` | `1024x1024`, `1024x1536`, `1536x1024`, `auto` | Cost-sensitive draft batches and lower-stakes previews |
+
+## gpt-image-2 sizes
+
+`gpt-image-2` accepts `auto` or any `WIDTHxHEIGHT` size that satisfies all constraints:
+
+- Maximum edge length must be less than or equal to `3840px`.
+- Both edges must be multiples of `16px`.
+- Long edge to short edge ratio must not exceed `3:1`.
+- Total pixels must be at least `655,360` and no more than `8,294,400`.
+
+Popular sizes:
+
+| Label | Size | Notes |
+| --- | --- | --- |
+| Square | `1024x1024` | Typical fast default |
+| Landscape | `1536x1024` | Standard landscape |
+| Portrait | `1024x1536` | Standard portrait |
+| 2K square | `2048x2048` | Larger square output |
+| 2K landscape | `2048x1152` | Widescreen output |
+| 4K landscape | `3840x2160` | Widescreen 4K output |
+| 4K portrait | `2160x3840` | Vertical 4K output |
+| Auto | `auto` | Default size |
+
+Square images are typically fastest to generate. For 4K-style output, use `3840x2160` or `2160x3840`.
+
+## Endpoints
+- Generate: `POST /v1/images/generations` (`client.images.generate(...)`)
+- Edit: `POST /v1/images/edits` (`client.images.edit(...)`)
+
+## Core parameters for GPT Image models
+- `prompt`: text prompt
+- `model`: image model
+- `n`: number of images (1-10)
+- `size`: `auto` by default for `gpt-image-2`; flexible `WIDTHxHEIGHT` sizes are allowed only for `gpt-image-2`; older GPT Image models use `1024x1024`, `1536x1024`, `1024x1536`, or `auto`
+- `quality`: `low`, `medium`, `high`, or `auto`
+- `background`: output transparency behavior (`transparent`, `opaque`, or `auto`) for generated output; this is not the same thing as the prompt's visual scene/backdrop
+- `output_format`: `png` (default), `jpeg`, `webp`
+- `output_compression`: 0-100 (jpeg/webp only)
+- `moderation`: `auto` (default) or `low`
+
+## Edit-specific parameters
+- `image`: one or more input images. For GPT Image models, you can provide up to 16 images.
+- `mask`: optional mask image
+- `input_fidelity`: `low` or `high` only for models that support it; do not set this for `gpt-image-2`
+
+Model-specific note for `input_fidelity`:
+- `gpt-image-2` always uses high fidelity for image inputs and does not support setting `input_fidelity`.
+- `gpt-image-1` and `gpt-image-1-mini` preserve all input images, but the first image gets richer textures and finer details.
+- `gpt-image-1.5` preserves the first 5 input images with higher fidelity.
+
+## Transparent backgrounds
+
+`gpt-image-2` does not currently support the Image API `background=transparent` parameter. The skill's default transparent-image path is built-in `image_gen` with a flat chroma-key background, followed by local alpha extraction with `python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py"`.
+
+Use CLI `gpt-image-1.5` with `background=transparent` and a transparent-capable output format such as `png` or `webp` only after the user explicitly confirms that fallback, unless they already requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback. If the user asks for true/native transparency, the subject is too complex for clean chroma-key removal, or local background removal fails validation, explain the tradeoff and ask before switching.
+
+## Output
+- `data[]` list with `b64_json` per image
+- The bundled `scripts/image_gen.py` CLI decodes `b64_json` and writes output files for you.
+
+## Limits and notes
+- Input images and masks must be under 50MB.
+- Use the edits endpoint when the user requests changes to an existing image.
+- Masking is prompt-guided; exact shapes are not guaranteed.
+- Large sizes and high quality increase latency and cost.
+- Use `quality=low` for fast drafts, thumbnails, and quick iterations. Use `medium` or `high` for final assets, dense text, diagrams, identity-sensitive edits, or high-resolution outputs.
+- High `input_fidelity` can materially increase input token usage on models that support it.
+- If a request fails because a specific option is unsupported by the selected GPT Image model, retry manually without that option only when the option is not required by the user. If true transparent CLI output is required, ask before switching to `gpt-image-1.5` instead of dropping `background=transparent`, unless the user already explicitly chose that fallback.
+
+## Important boundary
+- `quality`, `input_fidelity`, explicit masks, `background`, `output_format`, and related parameters are fallback-only execution controls.
+- Do not assume they are built-in `image_gen` tool arguments.
diff --git a/skills/imagegen/references/prompting.md b/skills/imagegen/references/prompting.md
new file mode 100644
index 0000000..9d2da42
--- /dev/null
+++ b/skills/imagegen/references/prompting.md
@@ -0,0 +1,118 @@
+# Prompting best practices
+
+These prompting principles are shared by both top-level modes of the skill:
+- built-in `image_gen` tool (default)
+- explicit `scripts/image_gen.py` CLI fallback
+
+This file is about prompt structure, specificity, and iteration. Fallback-only execution controls such as `quality`, `input_fidelity`, masks, output format, and output paths live in the fallback docs.
+
+## Contents
+- [Structure](#structure)
+- [Specificity policy](#specificity-policy)
+- [Allowed and disallowed augmentation](#allowed-and-disallowed-augmentation)
+- [Composition and layout](#composition-and-layout)
+- [Constraints and invariants](#constraints-and-invariants)
+- [Text in images](#text-in-images)
+- [Input images and references](#input-images-and-references)
+- [Iterate deliberately](#iterate-deliberately)
+- [Transparent images](#transparent-images)
+- [Fallback-only execution controls](#fallback-only-execution-controls)
+- [Use-case tips](#use-case-tips)
+- [Where to find copy/paste recipes](#where-to-find-copypaste-recipes)
+
+## Structure
+- Use a consistent order: scene/backdrop -> subject -> key details -> constraints -> output intent.
+- Include intended use (ad, UI mock, infographic) to set the level of polish.
+- For complex requests, use short labeled lines instead of one long paragraph.
+
+## Specificity policy
+- If the user prompt is already specific and detailed, normalize it into a clean spec without adding creative requirements.
+- If the prompt is generic, you may add tasteful detail when it materially improves the output.
+- Treat examples in `sample-prompts.md` as fully-authored recipes, not as the default amount of augmentation to add to every request.
+- For photorealism, include `photorealistic` directly when that is the goal, plus concrete real-world texture such as pores, wrinkles, fabric wear, material grain, or imperfect everyday detail.
+
+## Allowed and disallowed augmentation
+
+Allowed augmentation for generic prompts:
+- composition and framing cues
+- intended-use or polish-level hints
+- practical layout guidance
+- reasonable scene concreteness that supports the request
+
+Do not add:
+- extra characters, props, or objects that are not implied
+- brand palettes, slogans, or story beats that are not implied
+- arbitrary side-specific placement unless the surrounding layout supports it
+
+## Composition and layout
+- Specify framing and viewpoint (close-up, wide, top-down) and placement only when it materially helps.
+- Call out negative space if the asset clearly needs room for UI or copy.
+- Avoid making left/right layout decisions unless the user or surrounding layout supports them.
+- For people, describe body framing, scale, gaze, and object interactions when they matter (`full body visible`, `looking down at the book`, `hands naturally gripping the handlebars`).
+
+## Constraints and invariants
+- State what must not change (`keep background unchanged`).
+- For edits, say `change only X; keep Y unchanged` and repeat invariants on every iteration to reduce drift.
+
+## Text in images
+- Put literal text in quotes or ALL CAPS and specify typography (font style, size, color, placement).
+- Spell uncommon words letter-by-letter if accuracy matters.
+- For in-image copy, require verbatim rendering and no extra characters.
+- In CLI fallback mode, use `medium` or `high` quality for small text, dense infographics, data-heavy slides, multi-font layouts, legends, axes, and footnotes.
+
+## Input images and references
+- Do not assume that every provided image is an edit target.
+- Label each image by index and role (`Image 1: edit target`, `Image 2: style reference`).
+- If the user provides images for style, composition, or mood guidance and does not ask to modify them, treat the request as generation with references.
+- If the user asks to preserve an existing image while changing specific parts, treat the request as an edit.
+- For compositing, describe how the images interact (`place the subject from Image 2 into Image 1`).
+
+## Iterate deliberately
+- Start with a clean base prompt, then make small single-change edits.
+- Re-specify critical constraints when you iterate.
+- Prefer one targeted follow-up at a time over rewriting the whole prompt.
+
+## Transparent images
+- Use built-in `image_gen` first for transparent-image requests. If the subject is clearly too complex for chroma-key removal, explain the fallback and ask before switching to CLI.
+- Prompt for a perfectly flat solid chroma-key background, usually `#00ff00`; use `#ff00ff` when the subject is green, and avoid key colors that appear in the subject.
+- Explicitly prohibit shadows, gradients, floor planes, reflections, texture, and lighting variation in the background.
+- Ask for crisp edges, generous padding, and no use of the key color inside the subject.
+- After generation, remove the background locally with `python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" --input <source> --out <final.png> --auto-key border --soft-matte --transparent-threshold 12 --opaque-threshold 220 --despill` and validate the alpha result before shipping it.
+- Use soft matte and despill for antialiased edges; hard tolerance-only removal is mainly for flat pixel-art or exact-color fixtures.
+- Use CLI `gpt-image-1.5 --background transparent --output-format png` only after the user explicitly confirms the fallback, or when the user already explicitly requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback. Ask first for true/native transparency requests, failed chroma-key validation, or complex transparent subjects such as hair, fur, glass, smoke, liquids, translucent materials, reflective objects, or soft shadows.
+
+## Fallback-only execution controls
+- `quality`, `input_fidelity`, explicit masks, output format, and output paths are fallback-only execution controls.
+- Do not assume they are built-in `image_gen` tool arguments.
+- If the user explicitly chooses CLI fallback, see `references/cli.md` and `references/image-api.md` for those controls.
+- In CLI fallback mode, `gpt-image-2` is the default. It supports `quality=low|medium|high|auto`; use `low` for fast drafts and thumbnails, and move to `medium`, `high`, or `auto` for final assets.
+- `gpt-image-2` always uses high fidelity for image inputs, so do not set `input_fidelity` with that model.
+- If a transparent request needs true CLI transparency, ask before using `gpt-image-1.5` unless the user already explicitly chose it. Explain that built-in chroma-key removal is the default path, but `gpt-image-2` does not support `background=transparent`.
+- If the user asks for 4K-style output with `gpt-image-2`, use `3840x2160` for landscape or `2160x3840` for portrait.
+
+## Use-case tips
+Generate:
+- photorealistic-natural: Prompt as if a real photo is captured in the moment; use photography language (lens, lighting, framing); call for real texture; avoid over-stylized polish unless requested.
+- product-mockup: Describe the product/packaging and materials; ensure clean silhouette and label clarity; if in-image text is needed, require verbatim rendering and specify typography.
+- ui-mockup: Describe the target fidelity first (shippable mockup or low-fi wireframe), then focus on layout, hierarchy, and practical UI elements; avoid concept-art language.
+- infographic-diagram: Define the audience and layout flow; label parts explicitly; require verbatim text; prefer higher quality in CLI mode for dense labels.
+- logo-brand: Keep it simple and scalable; ask for a strong silhouette and balanced negative space; avoid decorative flourishes unless requested.
+- ads-marketing: Write like a creative brief; include brand positioning, audience, desired vibe, scene, and exact tagline if text must appear.
+- productivity-visual: Name the exact artifact (slide, chart, workflow diagram), define the canvas and hierarchy, provide real labels/data, and ask for readable typography and polished spacing.
+- scientific-educational: Define audience, lesson objective, required labels, scientific constraints, arrows, and scan-friendly whitespace.
+- illustration-story: Define panels or scene beats; keep each action concrete.
+- stylized-concept: Specify style cues, material finish, and rendering approach (3D, painterly, clay) without inventing new story elements.
+- historical-scene: State the location/date and required period accuracy; constrain clothing, props, and environment to match the era.
+
+Edit:
+- text-localization: Change only the text; preserve layout, typography, spacing, and hierarchy; no extra words or reflow unless needed.
+- identity-preserve: Lock identity (face, body, pose, hair, expression); change only the specified elements; match lighting and shadows.
+- precise-object-edit: Specify exactly what to remove/replace; preserve surrounding texture and lighting; keep everything else unchanged.
+- lighting-weather: Change only environmental conditions (light, shadows, atmosphere, precipitation); keep geometry, framing, and subject identity.
+- background-extraction: For simple opaque subjects, request a clean cutout on a perfectly flat chroma-key background; crisp silhouette; generous padding; no shadows; no halos; preserve label text exactly; no restyling. Ask before using true CLI transparency for complex subjects.
+- style-transfer: Specify style cues to preserve (palette, texture, brushwork) and what must change; add `no extra elements` to prevent drift.
+- compositing: Reference inputs by index; specify what moves where; match lighting, perspective, and scale; keep the base framing unchanged.
+- sketch-to-render: Preserve layout, proportions, and perspective; choose materials and lighting that support the supplied sketch without adding new elements.
+
+## Where to find copy/paste recipes
+For copy/paste prompt specs (examples only), see `references/sample-prompts.md`. This file focuses on principles, specificity, and iteration patterns.
diff --git a/skills/imagegen/references/sample-prompts.md b/skills/imagegen/references/sample-prompts.md
new file mode 100644
index 0000000..d949295
--- /dev/null
+++ b/skills/imagegen/references/sample-prompts.md
@@ -0,0 +1,433 @@
+# Sample prompts (copy/paste)
+
+These prompt recipes are shared across both top-level modes of the skill:
+- built-in `image_gen` tool (default)
+- `scripts/image_gen.py` CLI fallback for explicit CLI/API/model requests or user-confirmed true-transparent-output fallback requests
+
+Use these as starting points. They are intentionally complete prompt recipes, not the default amount of augmentation to add to every user request.
+
+When adapting a user's prompt:
+- keep user-provided requirements
+- only add detail according to the specificity policy in `SKILL.md`
+- do not treat every example below as permission to invent extra story elements
+
+The labeled lines are prompt scaffolding, not a closed schema. `Asset type` and `Input images` are prompt-only scaffolding; the CLI does not expose them as dedicated flags.
+
+Execution details such as explicit CLI flags, `quality`, `input_fidelity`, masks, output formats, and local output paths depend on mode. Use the built-in tool by default, including simple transparent-image requests. For transparent images, prompt for a flat chroma-key background and remove it locally with `python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py"`; only apply CLI-specific controls when the user explicitly opts into fallback mode or explicitly confirms that the transparent request should use true CLI transparency.
+
+CLI model notes:
+- `gpt-image-2` is the fallback CLI default for new workflows.
+- `gpt-image-2` supports `quality` values `low`, `medium`, `high`, and `auto`.
+- For 4K-style `gpt-image-2` output, use `3840x2160` or `2160x3840`.
+- If transparent output needs true CLI fallback, ask before using `gpt-image-1.5` unless the user already explicitly requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback. Explain that built-in chroma-key removal is the default path, but `gpt-image-2` does not support `background=transparent`.
+- Do not set `input_fidelity` with `gpt-image-2`; image inputs already use high fidelity.
+
+For prompting principles (structure, specificity, invariants, iteration), see `references/prompting.md`.
+
+## Generate
+
+### photorealistic-natural
+```
+Use case: photorealistic-natural
+Primary request: candid photo of an elderly sailor on a small fishing boat adjusting a net
+Scene/backdrop: coastal water with soft haze
+Subject: weathered skin with wrinkles and sun texture
+Style/medium: photorealistic candid photo
+Composition/framing: medium close-up, eye-level
+Lighting/mood: soft coastal daylight, shallow depth of field, subtle film grain
+Materials/textures: real skin texture, worn fabric, salt-worn wood
+Constraints: natural color balance; no heavy retouching; no glamorization; no watermark
+Avoid: studio polish; staged look
+```
+
+### product-mockup
+```
+Use case: product-mockup
+Primary request: premium product photo of a matte black shampoo bottle with a minimal label
+Scene/backdrop: clean studio gradient from light gray to white
+Subject: single bottle centered with subtle reflection
+Style/medium: premium product photography
+Composition/framing: centered, slight three-quarter angle, generous padding
+Lighting/mood: softbox lighting, clean highlights, controlled shadows
+Materials/textures: matte plastic, crisp label printing
+Constraints: no logos or trademarks; no watermark
+```
+
+### ui-mockup
+```
+Use case: ui-mockup
+Primary request: mobile app home screen for a local farmers market with vendors and daily specials
+Asset type: mobile app screen
+Style/medium: realistic product UI, not concept art
+Composition/framing: clean vertical mobile layout with clear hierarchy
+Constraints: practical layout, clear typography, no logos or trademarks, no watermark
+```
+
+### infographic-diagram
+```
+Use case: infographic-diagram
+Primary request: detailed infographic of an automatic coffee machine flow
+Scene/backdrop: clean, light neutral background
+Subject: bean hopper -> grinder -> brew group -> boiler -> water tank -> drip tray
+Style/medium: clean vector-like infographic with clear callouts and arrows
+Composition/framing: vertical poster layout, top-to-bottom flow
+Text (verbatim): "Bean Hopper", "Grinder", "Brew Group", "Boiler", "Water Tank", "Drip Tray"
+Constraints: clear labels, strong contrast, no logos or trademarks, no watermark
+```
+
+### scientific-educational
+```
+Use case: scientific-educational
+Primary request: biology diagram titled "Cellular Respiration at a Glance" for high school students
+Scene/backdrop: clean white classroom handout background
+Subject: glucose turns into energy inside a cell; include glycolysis, Krebs cycle, and electron transport chain
+Style/medium: flat scientific diagram with consistent icons, arrows, and readable labels
+Composition/framing: landscape slide-style layout with clear hierarchy and generous whitespace
+Text (verbatim): "Cellular Respiration at a Glance", "Glucose", "Pyruvate", "ATP", "NADH", "FADH2", "CO2", "O2", "H2O"
+Constraints: scientifically plausible; avoid tiny text; no extra decoration; no watermark
+```
+
+### logo-brand
+```
+Use case: logo-brand
+Primary request: original logo for "Field & Flour", a local bakery
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: single centered logo on a plain background with generous padding
+Constraints: strong silhouette, balanced negative space; original design only; no gradients unless essential; no trademarks; no watermark
+```
+
+### illustration-story
+```
+Use case: illustration-story
+Primary request: 4-panel comic about a pet left alone at home
+Scene/backdrop: cozy living room across panels
+Subject: pet reacting to the owner leaving, then relaxing, then returning to a composed pose
+Style/medium: comic illustration with clear panels
+Composition/framing: 4 equal-sized vertical panels, readable actions per panel
+Constraints: no text; no logos or trademarks; no watermark
+```
+
+### stylized-concept
+```
+Use case: stylized-concept
+Primary request: cavernous hangar interior with tall support beams and drifting fog
+Scene/backdrop: industrial hangar interior, deep scale, light haze
+Subject: compact shuttle parked near the center
+Style/medium: cinematic concept art, industrial realism
+Composition/framing: wide-angle, low-angle
+Lighting/mood: volumetric light rays cutting through fog
+Constraints: no logos or trademarks; no watermark
+```
+
+### ads-marketing
+```
+Use case: ads-marketing
+Primary request: campaign image for a streetwear brand called Thread
+Subject: group of friends hanging out together in a stylish urban setting
+Style/medium: polished youth streetwear campaign photography
+Composition/framing: vertical ad layout with natural poses and integrated headline space
+Lighting/mood: contemporary, energetic, tasteful
+Text (verbatim): "Yours to Create."
+Constraints: render the tagline exactly once; clean legible typography; no extra text; no watermarks; no unrelated logos
+```
+
+### productivity-visual
+```
+Use case: productivity-visual
+Primary request: one pitch-deck slide titled "Market Opportunity"
+Asset type: fundraising slide image
+Style/medium: clean modern deck slide, white background, crisp sans-serif typography
+Subject: TAM/SAM/SOM concentric-circle diagram plus a small growth bar chart from 2021 to 2026
+Composition/framing: 16:9 landscape slide, clear data hierarchy, polished spacing
+Text (verbatim): "Market Opportunity", "TAM: $42B", "SAM: $8.7B", "SOM: $340M", "AGI Research, 2024", "Internal analysis"
+Constraints: readable labels, no clip art, no stock photography, no decorative clutter, no watermark
+```
+
+### historical-scene
+```
+Use case: historical-scene
+Primary request: outdoor crowd scene in Bethel, New York on August 16, 1969
+Scene/backdrop: open field with period-appropriate staging
+Subject: crowd in period-accurate clothing, authentic environment
+Style/medium: photorealistic photo
+Composition/framing: wide shot, eye-level
+Constraints: period-accurate details; no modern objects; no logos or trademarks; no watermark
+```
+
+## Asset type templates (taxonomy-aligned)
+
+### Website assets template
+```
+Use case: <photorealistic-natural|stylized-concept|product-mockup|infographic-diagram|ui-mockup>
+Asset type: <hero image / section illustration / blog header>
+Primary request: <short description>
+Scene/backdrop: <environment or abstract backdrop>
+Subject: <main subject>
+Style/medium: <photo/illustration/3D>
+Composition/framing: <wide/centered; note usable negative space only if needed>
+Lighting/mood: <soft/bright/neutral>
+Color palette: <brand colors or neutral>
+Constraints: <no text; no logos; no watermark; leave room for UI if needed>
+```
+
+### Website assets example: minimal hero background
+```
+Use case: stylized-concept
+Asset type: landing page hero background
+Primary request: minimal abstract background with a soft gradient and subtle texture
+Style/medium: matte illustration / soft-rendered abstract background
+Composition/framing: wide composition with usable negative space for page copy
+Lighting/mood: gentle studio glow
+Color palette: restrained neutral palette
+Constraints: no text; no logos; no watermark
+```
+
+### Website assets example: feature section illustration
+```
+Use case: stylized-concept
+Asset type: feature section illustration
+Primary request: simple abstract shapes suggesting connection and flow
+Scene/backdrop: subtle light-gray backdrop with faint texture
+Style/medium: flat illustration; soft shadows; restrained contrast
+Composition/framing: centered cluster; open margins for UI
+Color palette: muted neutral palette
+Constraints: no text; no logos; no watermark
+```
+
+### Website assets example: blog header image
+```
+Use case: photorealistic-natural
+Asset type: blog header image
+Primary request: overhead desk scene with notebook, pen, and coffee cup
+Scene/backdrop: warm wooden tabletop
+Style/medium: photorealistic photo
+Composition/framing: wide crop with clean room for page copy
+Lighting/mood: soft morning light
+Constraints: no text; no logos; no watermark
+```
+
+### Game assets template
+```
+Use case: stylized-concept
+Asset type: <game environment concept art / game character concept / game UI icon / tileable game texture>
+Primary request: <biome/scene/character/icon/material>
+Scene/backdrop: <location + set dressing> (if applicable)
+Subject: <main focal element(s)>
+Style/medium: <realistic/stylized>; <concept art / character render / UI icon / texture>
+Composition/framing: <wide/establishing/top-down>; <camera angle>; <focal point placement>
+Lighting/mood: <time of day>; <mood>; <volumetric/fog/etc>
+Constraints: no logos or trademarks; no watermark
+```
+
+### Game assets example: environment concept art
+```
+Use case: stylized-concept
+Asset type: game environment concept art
+Primary request: cavernous hangar interior with tall support beams and drifting fog
+Scene/backdrop: industrial hangar interior, deep scale, light haze
+Subject: compact shuttle parked near the center
+Style/medium: cinematic concept art, industrial realism
+Composition/framing: wide-angle, low-angle
+Lighting/mood: volumetric light rays cutting through fog
+Constraints: no logos or trademarks; no watermark
+```
+
+### Game assets example: character concept
+```
+Use case: stylized-concept
+Asset type: game character concept
+Primary request: desert scout character with layered travel gear
+Subject: long coat, satchel, practical travel clothing
+Style/medium: character render; stylized realism
+Composition/framing: neutral hero pose on a simple backdrop
+Constraints: no logos or trademarks; no watermark
+```
+
+### Game assets example: UI icon
+```
+Use case: stylized-concept
+Asset type: game UI icon
+Primary request: round shield icon with a subtle rune pattern
+Style/medium: painted game UI icon
+Composition/framing: centered icon; generous padding; clear silhouette
+Constraints: no text; no background scene elements; no logos or trademarks; no watermark
+```
+
+### Game assets example: tileable texture
+```
+Use case: stylized-concept
+Asset type: tileable game texture
+Primary request: worn sandstone blocks
+Style/medium: seamless tileable texture; PBR-ish look
+Scene/backdrop: neutral lighting reference only
+Constraints: seamless edges; no obvious focal elements; no text; no logos or trademarks; no watermark
+```
+
+### Wireframe template
+```
+Use case: ui-mockup
+Asset type: website wireframe
+Primary request: <page or flow to sketch>
+Style/medium: low-fi grayscale wireframe
+Composition/framing: <landscape or portrait to match expected device>
+Subject: <sections in order; grid/columns; key labels>
+Constraints: no color; no logos; no real photos; no watermark
+```
+
+### Wireframe example: homepage (desktop)
+```
+Use case: ui-mockup
+Asset type: website wireframe
+Primary request: SaaS homepage layout with clear hierarchy
+Style/medium: low-fi grayscale wireframe
+Subject: top nav; hero with headline and CTA; three feature cards; testimonial strip; pricing preview; footer
+Composition/framing: landscape desktop layout
+Constraints: label major blocks; no color; no logos; no real photos; no watermark
+```
+
+### Wireframe example: pricing page
+```
+Use case: ui-mockup
+Asset type: website wireframe
+Primary request: pricing page layout with comparison table
+Style/medium: low-fi grayscale wireframe
+Subject: header; plan toggle; 3 pricing cards; comparison table; FAQ accordion; footer
+Composition/framing: desktop or tablet layout
+Constraints: label key areas; no color; no logos; no real photos; no watermark
+```
+
+### Wireframe example: mobile onboarding flow
+```
+Use case: ui-mockup
+Asset type: mobile onboarding wireframe
+Primary request: three-screen mobile onboarding flow
+Style/medium: low-fi grayscale wireframe
+Subject: screen 1 headline and CTA; screen 2 feature bullets; screen 3 form fields and CTA
+Composition/framing: portrait mobile layout
+Constraints: label screens and blocks; no color; no logos; no real photos; no watermark
+```
+
+### Logo template
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: <brand idea or symbol concept>
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: centered mark; clear silhouette; generous margin
+Color palette: <1-2 colors; high contrast>
+Text (verbatim): "<exact name>" (only if needed)
+Constraints: no gradients; no mockups; no 3D; no watermark
+```
+
+### Logo example: abstract symbol mark
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: geometric leaf symbol suggesting sustainability and growth
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: centered mark; clear silhouette
+Color palette: deep green and off-white
+Constraints: no text unless requested; no gradients; no mockups; no 3D; no watermark
+```
+
+### Logo example: monogram mark
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: interlocking monogram of the letters "AV"
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: centered mark; balanced spacing
+Color palette: black on white
+Constraints: no gradients; no mockups; no 3D; no watermark
+```
+
+### Logo example: wordmark
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: clean wordmark for a modern studio
+Style/medium: vector wordmark; flat colors; minimal
+Text (verbatim): "Studio North"
+Composition/framing: centered text; even letter spacing
+Constraints: no gradients; no mockups; no 3D; no watermark
+```
+
+## Edit
+
+### text-localization
+```
+Use case: text-localization
+Input images: Image 1: original infographic
+Primary request: replace "Bean Hopper", "Grinder", "Brew Group", "Boiler", "Water Tank", and "Drip Tray" with "Tolva", "Molino", "Grupo de infusión", "Caldera", "Depósito de agua", and "Bandeja de goteo"
+Constraints: change only the text; preserve layout, typography, spacing, and hierarchy; no extra words; do not alter logos or imagery
+```
+
+### identity-preserve
+```
+Use case: identity-preserve
+Input images: Image 1: person photo; Image 2..N: clothing references
+Primary request: replace only the clothing with the provided garments
+Constraints: preserve face, body shape, pose, hair, expression, and identity; match lighting and shadows; keep the background unchanged; no accessories or text
+```
+
+### precise-object-edit
+```
+Use case: precise-object-edit
+Input images: Image 1: room photo
+Primary request: replace only the white chairs with wooden chairs
+Constraints: preserve camera angle, room lighting, floor shadows, and surrounding objects; keep all other aspects unchanged
+```
+
+### lighting-weather
+```
+Use case: lighting-weather
+Input images: Image 1: original photo
+Primary request: make it look like a winter evening with gentle snowfall
+Constraints: preserve subject identity, geometry, camera angle, and composition; change only lighting, atmosphere, and weather
+```
+
+### background-extraction
+```
+Use case: background-extraction
+Input images: Image 1: product photo
+Primary request: isolate the product on a clean transparent background
+Scene/backdrop: perfectly flat solid #00ff00 chroma-key background for local background removal
+Constraints: background must be one uniform color with no shadows, gradients, texture, reflections, floor plane, or lighting variation; crisp silhouette; generous padding; no halos or fringing; preserve label text exactly; no restyling; do not use #00ff00 anywhere in the subject
+```
+
+Post-process note: after built-in generation, run `python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" --input <source> --out <final.png> --auto-key border --soft-matte --transparent-threshold 12 --opaque-threshold 220 --despill`. Ask before using CLI `gpt-image-1.5 --background transparent --output-format png` for true/native transparency, failed chroma-key validation, or complex subjects such as hair, fur, glass, smoke, liquids, translucent materials, reflections, or soft shadows, unless the user already explicitly requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback.
+
+### style-transfer
+```
+Use case: style-transfer
+Input images: Image 1: style reference
+Primary request: apply Image 1's visual style to a man riding a motorcycle on a plain white backdrop
+Constraints: preserve palette, texture, and brushwork; no extra elements
+```
+
+### compositing
+```
+Use case: compositing
+Input images: Image 1: base scene; Image 2: subject to insert
+Primary request: place the subject from Image 2 next to the person in Image 1
+Constraints: match lighting, perspective, and scale; keep the base framing unchanged; no extra elements
+```
+
+### character consistency workflow
+```
+Use case: identity-preserve
+Input images: Image 1: previous character anchor illustration
+Primary request: continue the story with the same character in a new scene and action
+Scene/backdrop: snowy forest after a winter storm
+Subject: same young forest hero gently helping a frightened squirrel out of a fallen tree
+Style/medium: same children's book watercolor illustration style as Image 1
+Constraints: do not redesign the character; preserve facial features, proportions, outfit, color palette, and personality; no text; no watermark
+```
+
+### sketch-to-render
+```
+Use case: sketch-to-render
+Input images: Image 1: drawing
+Primary request: turn the drawing into a photorealistic image
+Constraints: preserve layout, proportions, and perspective; choose realistic materials and lighting; do not add new elements or text
+```
diff --git a/skills/imagegen/scripts/image_gen.py b/skills/imagegen/scripts/image_gen.py
new file mode 100644
index 0000000..9e0ea67
--- /dev/null
+++ b/skills/imagegen/scripts/image_gen.py
@@ -0,0 +1,995 @@
+#!/usr/bin/env python3
+"""Fallback CLI for explicit image generation or editing with GPT Image models.
+
+Used only when the user explicitly opts into CLI fallback mode, or when explicit
+transparent output requires the `gpt-image-1.5` fallback path.
+
+Defaults to gpt-image-2 and a structured prompt augmentation workflow.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import base64
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import time
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from io import BytesIO
+
+DEFAULT_MODEL = "gpt-image-2"
+DEFAULT_SIZE = "auto"
+DEFAULT_QUALITY = "medium"
+DEFAULT_OUTPUT_FORMAT = "png"
+DEFAULT_CONCURRENCY = 5
+DEFAULT_DOWNSCALE_SUFFIX = "-web"
+DEFAULT_OUTPUT_PATH = "output/imagegen/output.png"
+GPT_IMAGE_MODEL_PREFIX = "gpt-image-"
+
+ALLOWED_LEGACY_SIZES = {"1024x1024", "1536x1024", "1024x1536", "auto"}
+ALLOWED_QUALITIES = {"low", "medium", "high", "auto"}
+ALLOWED_BACKGROUNDS = {"transparent", "opaque", "auto", None}
+ALLOWED_INPUT_FIDELITIES = {"low", "high", None}
+
+GPT_IMAGE_2_MODEL = "gpt-image-2"
+GPT_IMAGE_2_MIN_PIXELS = 655_360
+GPT_IMAGE_2_MAX_PIXELS = 8_294_400
+GPT_IMAGE_2_MAX_EDGE = 3840
+GPT_IMAGE_2_MAX_RATIO = 3.0
+
+MAX_IMAGE_BYTES = 50 * 1024 * 1024
+MAX_BATCH_JOBS = 500
+
+
+def _die(message: str, code: int = 1) -> None:
+    print(f"Error: {message}", file=sys.stderr)
+    raise SystemExit(code)
+
+
+def _warn(message: str) -> None:
+    print(f"Warning: {message}", file=sys.stderr)
+
+
+def _dependency_hint(package: str, *, upgrade: bool = False) -> str:
+    command = f"uv pip install {'-U ' if upgrade else ''}{package}"
+    return (
+        "Activate the repo-selected environment first, then install it with "
+        f"`{command}`. If this repo uses a local virtualenv, start with "
+        "`source .venv/bin/activate`; otherwise use this repo's configured shared fallback "
+        "environment. If your project declares dependencies, prefer that project's normal "
+        "`uv sync` flow."
+    )
+
+
+def _ensure_api_key(dry_run: bool) -> None:
+    if os.getenv("OPENAI_API_KEY"):
+        print("OPENAI_API_KEY is set.", file=sys.stderr)
+        return
+    if dry_run:
+        _warn("OPENAI_API_KEY is not set; dry-run only.")
+        return
+    _die("OPENAI_API_KEY is not set. Export it before running.")
+
+
+def _read_prompt(prompt: Optional[str], prompt_file: Optional[str]) -> str:
+    if prompt and prompt_file:
+        _die("Use --prompt or --prompt-file, not both.")
+    if prompt_file:
+        path = Path(prompt_file)
+        if not path.exists():
+            _die(f"Prompt file not found: {path}")
+        return path.read_text(encoding="utf-8").strip()
+    if prompt:
+        return prompt.strip()
+    _die("Missing prompt. Use --prompt or --prompt-file.")
+    return ""  # unreachable
+
+
+def _check_image_paths(paths: Iterable[str]) -> List[Path]:
+    resolved: List[Path] = []
+    for raw in paths:
+        path = Path(raw)
+        if not path.exists():
+            _die(f"Image file not found: {path}")
+        if path.stat().st_size > MAX_IMAGE_BYTES:
+            _warn(f"Image exceeds 50MB limit: {path}")
+        resolved.append(path)
+    return resolved
+
+
+def _normalize_output_format(fmt: Optional[str]) -> str:
+    if not fmt:
+        return DEFAULT_OUTPUT_FORMAT
+    fmt = fmt.lower()
+    if fmt not in {"png", "jpeg", "jpg", "webp"}:
+        _die("output-format must be png, jpeg, jpg, or webp.")
+    return "jpeg" if fmt == "jpg" else fmt
+
+
+def _parse_size(size: str) -> Optional[Tuple[int, int]]:
+    match = re.fullmatch(r"([1-9][0-9]*)x([1-9][0-9]*)", size)
+    if not match:
+        return None
+    return int(match.group(1)), int(match.group(2))
+
+
+def _validate_gpt_image_2_size(size: str) -> None:
+    if size == "auto":
+        return
+
+    parsed = _parse_size(size)
+    if parsed is None:
+        _die("size must be auto or WIDTHxHEIGHT, for example 1024x1024.")
+
+    width, height = parsed
+    max_edge = max(width, height)
+    min_edge = min(width, height)
+    total_pixels = width * height
+
+    if max_edge > GPT_IMAGE_2_MAX_EDGE:
+        _die("gpt-image-2 size maximum edge length must be less than or equal to 3840px.")
+    if width % 16 != 0 or height % 16 != 0:
+        _die("gpt-image-2 size width and height must be multiples of 16px.")
+    if max_edge / min_edge > GPT_IMAGE_2_MAX_RATIO:
+        _die("gpt-image-2 size long edge to short edge ratio must not exceed 3:1.")
+    if total_pixels < GPT_IMAGE_2_MIN_PIXELS or total_pixels > GPT_IMAGE_2_MAX_PIXELS:
+        _die(
+            "gpt-image-2 size total pixels must be at least 655,360 and no more than 8,294,400."
+        )
+
+
+def _validate_size(size: str, model: str) -> None:
+    if model == GPT_IMAGE_2_MODEL:
+        _validate_gpt_image_2_size(size)
+        return
+
+    if size not in ALLOWED_LEGACY_SIZES:
+        _die(
+            "size must be one of 1024x1024, 1536x1024, 1024x1536, or auto for this GPT Image model."
+        )
+
+
+def _validate_quality(quality: str) -> None:
+    if quality not in ALLOWED_QUALITIES:
+        _die("quality must be one of low, medium, high, or auto.")
+
+
+def _validate_background(background: Optional[str]) -> None:
+    if background not in ALLOWED_BACKGROUNDS:
+        _die("background must be one of transparent, opaque, or auto.")
+
+
+def _validate_input_fidelity(input_fidelity: Optional[str]) -> None:
+    if input_fidelity not in ALLOWED_INPUT_FIDELITIES:
+        _die("input-fidelity must be one of low or high.")
+
+
+def _validate_model(model: str) -> None:
+    if not model.startswith(GPT_IMAGE_MODEL_PREFIX):
+        _die(
+            "model must be a GPT Image model (for example gpt-image-1.5, gpt-image-1, or gpt-image-1-mini)."
+        )
+
+
+def _validate_transparency(background: Optional[str], output_format: str) -> None:
+    if background == "transparent" and output_format not in {"png", "webp"}:
+        _die("transparent background requires output-format png or webp.")
+
+
+def _validate_model_specific_options(
+    *,
+    model: str,
+    background: Optional[str],
+    input_fidelity: Optional[str] = None,
+) -> None:
+    if model != GPT_IMAGE_2_MODEL:
+        return
+    if background == "transparent":
+        _die(
+            "transparent backgrounds are not supported in gpt-image-2, the latest model. "
+            "Use --model gpt-image-1.5 --background transparent --output-format png instead."
+        )
+    if input_fidelity is not None:
+        _die(
+            "input_fidelity is not supported in gpt-image-2 because image inputs always use high fidelity for this model."
+        )
+
+
+def _validate_generate_payload(payload: Dict[str, Any]) -> None:
+    model = str(payload.get("model", DEFAULT_MODEL))
+    _validate_model(model)
+    n = int(payload.get("n", 1))
+    if n < 1 or n > 10:
+        _die("n must be between 1 and 10")
+    size = str(payload.get("size", DEFAULT_SIZE))
+    quality = str(payload.get("quality", DEFAULT_QUALITY))
+    background = payload.get("background")
+    _validate_size(size, model)
+    _validate_quality(quality)
+    _validate_background(background)
+    _validate_model_specific_options(model=model, background=background)
+    oc = payload.get("output_compression")
+    if oc is not None and not (0 <= int(oc) <= 100):
+        _die("output_compression must be between 0 and 100")
+
+
+def _build_output_paths(
+    out: str,
+    output_format: str,
+    count: int,
+    out_dir: Optional[str],
+) -> List[Path]:
+    ext = "." + output_format
+
+    if out_dir:
+        out_base = Path(out_dir)
+        out_base.mkdir(parents=True, exist_ok=True)
+        return [out_base / f"image_{i}{ext}" for i in range(1, count + 1)]
+
+    out_path = Path(out)
+    if out_path.exists() and out_path.is_dir():
+        out_path.mkdir(parents=True, exist_ok=True)
+        return [out_path / f"image_{i}{ext}" for i in range(1, count + 1)]
+
+    if out_path.suffix == "":
+        out_path = out_path.with_suffix(ext)
+    elif output_format and out_path.suffix.lstrip(".").lower() != output_format:
+        _warn(
+            f"Output extension {out_path.suffix} does not match output-format {output_format}."
+        )
+
+    if count == 1:
+        return [out_path]
+
+    return [
+        out_path.with_name(f"{out_path.stem}-{i}{out_path.suffix}")
+        for i in range(1, count + 1)
+    ]
+
+
+def _augment_prompt(args: argparse.Namespace, prompt: str) -> str:
+    fields = _fields_from_args(args)
+    return _augment_prompt_fields(args.augment, prompt, fields)
+
+
+def _augment_prompt_fields(augment: bool, prompt: str, fields: Dict[str, Optional[str]]) -> str:
+    if not augment:
+        return prompt
+
+    sections: List[str] = []
+    if fields.get("use_case"):
+        sections.append(f"Use case: {fields['use_case']}")
+    sections.append(f"Primary request: {prompt}")
+    if fields.get("scene"):
+        sections.append(f"Scene/background: {fields['scene']}")
+    if fields.get("subject"):
+        sections.append(f"Subject: {fields['subject']}")
+    if fields.get("style"):
+        sections.append(f"Style/medium: {fields['style']}")
+    if fields.get("composition"):
+        sections.append(f"Composition/framing: {fields['composition']}")
+    if fields.get("lighting"):
+        sections.append(f"Lighting/mood: {fields['lighting']}")
+    if fields.get("palette"):
+        sections.append(f"Color palette: {fields['palette']}")
+    if fields.get("materials"):
+        sections.append(f"Materials/textures: {fields['materials']}")
+    if fields.get("text"):
+        sections.append(f"Text (verbatim): \"{fields['text']}\"")
+    if fields.get("constraints"):
+        sections.append(f"Constraints: {fields['constraints']}")
+    if fields.get("negative"):
+        sections.append(f"Avoid: {fields['negative']}")
+
+    return "\n".join(sections)
+
+
+def _fields_from_args(args: argparse.Namespace) -> Dict[str, Optional[str]]:
+    return {
+        "use_case": getattr(args, "use_case", None),
+        "scene": getattr(args, "scene", None),
+        "subject": getattr(args, "subject", None),
+        "style": getattr(args, "style", None),
+        "composition": getattr(args, "composition", None),
+        "lighting": getattr(args, "lighting", None),
+        "palette": getattr(args, "palette", None),
+        "materials": getattr(args, "materials", None),
+        "text": getattr(args, "text", None),
+        "constraints": getattr(args, "constraints", None),
+        "negative": getattr(args, "negative", None),
+    }
+
+
+def _print_request(payload: dict) -> None:
+    print(json.dumps(payload, indent=2, sort_keys=True))
+
+
+def _decode_and_write(images: List[str], outputs: List[Path], force: bool) -> None:
+    for idx, image_b64 in enumerate(images):
+        if idx >= len(outputs):
+            break
+        out_path = outputs[idx]
+        if out_path.exists() and not force:
+            _die(f"Output already exists: {out_path} (use --force to overwrite)")
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_bytes(base64.b64decode(image_b64))
+        print(f"Wrote {out_path}")
+
+
+def _derive_downscale_path(path: Path, suffix: str) -> Path:
+    if suffix and not suffix.startswith("-") and not suffix.startswith("_"):
+        suffix = "-" + suffix
+    return path.with_name(f"{path.stem}{suffix}{path.suffix}")
+
+
+def _downscale_image_bytes(image_bytes: bytes, *, max_dim: int, output_format: str) -> bytes:
+    try:
+        from PIL import Image
+    except Exception:
+        _die(f"Downscaling requires Pillow. {_dependency_hint('pillow')}")
+
+    if max_dim < 1:
+        _die("--downscale-max-dim must be >= 1")
+
+    with Image.open(BytesIO(image_bytes)) as img:
+        img.load()
+        w, h = img.size
+        scale = min(1.0, float(max_dim) / float(max(w, h)))
+        target = (max(1, int(round(w * scale))), max(1, int(round(h * scale))))
+
+        resized = img if target == (w, h) else img.resize(target, Image.Resampling.LANCZOS)
+
+        fmt = output_format.lower()
+        if fmt == "jpg":
+            fmt = "jpeg"
+
+        if fmt == "jpeg":
+            if resized.mode in ("RGBA", "LA") or ("transparency" in getattr(resized, "info", {})):
+                bg = Image.new("RGB", resized.size, (255, 255, 255))
+                bg.paste(resized.convert("RGBA"), mask=resized.convert("RGBA").split()[-1])
+                resized = bg
+            else:
+                resized = resized.convert("RGB")
+
+        out = BytesIO()
+        resized.save(out, format=fmt.upper())
+        return out.getvalue()
+
+
+def _decode_write_and_downscale(
+    images: List[str],
+    outputs: List[Path],
+    *,
+    force: bool,
+    downscale_max_dim: Optional[int],
+    downscale_suffix: str,
+    output_format: str,
+) -> None:
+    for idx, image_b64 in enumerate(images):
+        if idx >= len(outputs):
+            break
+        out_path = outputs[idx]
+        if out_path.exists() and not force:
+            _die(f"Output already exists: {out_path} (use --force to overwrite)")
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        raw = base64.b64decode(image_b64)
+        out_path.write_bytes(raw)
+        print(f"Wrote {out_path}")
+
+        if downscale_max_dim is None:
+            continue
+
+        derived = _derive_downscale_path(out_path, downscale_suffix)
+        if derived.exists() and not force:
+            _die(f"Output already exists: {derived} (use --force to overwrite)")
+        derived.parent.mkdir(parents=True, exist_ok=True)
+        resized = _downscale_image_bytes(raw, max_dim=downscale_max_dim, output_format=output_format)
+        derived.write_bytes(resized)
+        print(f"Wrote {derived}")
+
+
+def _create_client():
+    try:
+        from openai import OpenAI
+    except ImportError:
+        _die(f"openai SDK not installed in the active environment. {_dependency_hint('openai')}")
+    return OpenAI()
+
+
+def _create_async_client():
+    try:
+        from openai import AsyncOpenAI
+    except ImportError:
+        try:
+            import openai as _openai  # noqa: F401
+        except ImportError:
+            _die(
+                f"openai SDK not installed in the active environment. {_dependency_hint('openai')}"
+            )
+        _die(
+            "AsyncOpenAI not available in this openai SDK version. "
+            f"{_dependency_hint('openai', upgrade=True)}"
+        )
+    return AsyncOpenAI()
+
+
+def _slugify(value: str) -> str:
+    value = value.strip().lower()
+    value = re.sub(r"[^a-z0-9]+", "-", value)
+    value = re.sub(r"-{2,}", "-", value).strip("-")
+    return value[:60] if value else "job"
+
+
+def _normalize_job(job: Any, idx: int) -> Dict[str, Any]:
+    if isinstance(job, str):
+        prompt = job.strip()
+        if not prompt:
+            _die(f"Empty prompt at job {idx}")
+        return {"prompt": prompt}
+    if isinstance(job, dict):
+        if "prompt" not in job or not str(job["prompt"]).strip():
+            _die(f"Missing prompt for job {idx}")
+        return job
+    _die(f"Invalid job at index {idx}: expected string or object.")
+    return {}  # unreachable
+
+
+def _read_jobs_jsonl(path: str) -> List[Dict[str, Any]]:
+    p = Path(path)
+    if not p.exists():
+        _die(f"Input file not found: {p}")
+    jobs: List[Dict[str, Any]] = []
+    for line_no, raw in enumerate(p.read_text(encoding="utf-8").splitlines(), start=1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        try:
+            item: Any
+            if line.startswith("{"):
+                item = json.loads(line)
+            else:
+                item = line
+            jobs.append(_normalize_job(item, idx=line_no))
+        except json.JSONDecodeError as exc:
+            _die(f"Invalid JSON on line {line_no}: {exc}")
+    if not jobs:
+        _die("No jobs found in input file.")
+    if len(jobs) > MAX_BATCH_JOBS:
+        _die(f"Too many jobs ({len(jobs)}). Max is {MAX_BATCH_JOBS}.")
+    return jobs
+
+
+def _merge_non_null(dst: Dict[str, Any], src: Dict[str, Any]) -> Dict[str, Any]:
+    merged = dict(dst)
+    for k, v in src.items():
+        if v is not None:
+            merged[k] = v
+    return merged
+
+
+def _job_output_paths(
+    *,
+    out_dir: Path,
+    output_format: str,
+    idx: int,
+    prompt: str,
+    n: int,
+    explicit_out: Optional[str],
+) -> List[Path]:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    ext = "." + output_format
+
+    if explicit_out:
+        base = Path(explicit_out)
+        if base.suffix == "":
+            base = base.with_suffix(ext)
+        elif base.suffix.lstrip(".").lower() != output_format:
+            _warn(
+                f"Job {idx}: output extension {base.suffix} does not match output-format {output_format}."
+            )
+        base = out_dir / base.name
+    else:
+        slug = _slugify(prompt[:80])
+        base = out_dir / f"{idx:03d}-{slug}{ext}"
+
+    if n == 1:
+        return [base]
+    return [
+        base.with_name(f"{base.stem}-{i}{base.suffix}")
+        for i in range(1, n + 1)
+    ]
+
+
+def _extract_retry_after_seconds(exc: Exception) -> Optional[float]:
+    # Best-effort: openai SDK errors vary by version. Prefer a conservative fallback.
+    for attr in ("retry_after", "retry_after_seconds"):
+        val = getattr(exc, attr, None)
+        if isinstance(val, (int, float)) and val >= 0:
+            return float(val)
+    msg = str(exc)
+    m = re.search(r"retry[- ]after[:= ]+([0-9]+(?:\\.[0-9]+)?)", msg, re.IGNORECASE)
+    if m:
+        try:
+            return float(m.group(1))
+        except Exception:
+            return None
+    return None
+
+
+def _is_rate_limit_error(exc: Exception) -> bool:
+    name = exc.__class__.__name__.lower()
+    if "ratelimit" in name or "rate_limit" in name:
+        return True
+    msg = str(exc).lower()
+    return "429" in msg or "rate limit" in msg or "too many requests" in msg
+
+
+def _is_transient_error(exc: Exception) -> bool:
+    if _is_rate_limit_error(exc):
+        return True
+    name = exc.__class__.__name__.lower()
+    if "timeout" in name or "timedout" in name or "tempor" in name:
+        return True
+    msg = str(exc).lower()
+    return "timeout" in msg or "timed out" in msg or "connection reset" in msg
+
+
+async def _generate_one_with_retries(
+    client: Any,
+    payload: Dict[str, Any],
+    *,
+    attempts: int,
+    job_label: str,
+) -> Any:
+    last_exc: Optional[Exception] = None
+    for attempt in range(1, attempts + 1):
+        try:
+            return await client.images.generate(**payload)
+        except Exception as exc:
+            last_exc = exc
+            if not _is_transient_error(exc):
+                raise
+            if attempt == attempts:
+                raise
+            sleep_s = _extract_retry_after_seconds(exc)
+            if sleep_s is None:
+                sleep_s = min(60.0, 2.0**attempt)
+            print(
+                f"{job_label} attempt {attempt}/{attempts} failed ({exc.__class__.__name__}); retrying in {sleep_s:.1f}s",
+                file=sys.stderr,
+            )
+            await asyncio.sleep(sleep_s)
+    raise last_exc or RuntimeError("unknown error")
+
+
+async def _run_generate_batch(args: argparse.Namespace) -> int:
+    jobs = _read_jobs_jsonl(args.input)
+    out_dir = Path(args.out_dir)
+
+    base_fields = _fields_from_args(args)
+    base_payload = {
+        "model": args.model,
+        "n": args.n,
+        "size": args.size,
+        "quality": args.quality,
+        "background": args.background,
+        "output_format": args.output_format,
+        "output_compression": args.output_compression,
+        "moderation": args.moderation,
+    }
+
+    if args.dry_run:
+        for i, job in enumerate(jobs, start=1):
+            prompt = str(job["prompt"]).strip()
+            fields = _merge_non_null(base_fields, job.get("fields", {}))
+            # Allow flat job keys as well (use_case, scene, etc.)
+            fields = _merge_non_null(fields, {k: job.get(k) for k in base_fields.keys()})
+            augmented = _augment_prompt_fields(args.augment, prompt, fields)
+
+            job_payload = dict(base_payload)
+            job_payload["prompt"] = augmented
+            job_payload = _merge_non_null(job_payload, {k: job.get(k) for k in base_payload.keys()})
+            job_payload = {k: v for k, v in job_payload.items() if v is not None}
+
+            _validate_generate_payload(job_payload)
+            effective_output_format = _normalize_output_format(job_payload.get("output_format"))
+            _validate_transparency(job_payload.get("background"), effective_output_format)
+            job_payload["output_format"] = effective_output_format
+
+            n = int(job_payload.get("n", 1))
+            outputs = _job_output_paths(
+                out_dir=out_dir,
+                output_format=effective_output_format,
+                idx=i,
+                prompt=prompt,
+                n=n,
+                explicit_out=job.get("out"),
+            )
+            downscaled = None
+            if args.downscale_max_dim is not None:
+                downscaled = [
+                    str(_derive_downscale_path(p, args.downscale_suffix)) for p in outputs
+                ]
+            _print_request(
+                {
+                    "endpoint": "/v1/images/generations",
+                    "job": i,
+                    "outputs": [str(p) for p in outputs],
+                    "outputs_downscaled": downscaled,
+                    **job_payload,
+                }
+            )
+        return 0
+
+    client = _create_async_client()
+    sem = asyncio.Semaphore(args.concurrency)
+
+    any_failed = False
+
+    async def run_job(i: int, job: Dict[str, Any]) -> Tuple[int, Optional[str]]:
+        nonlocal any_failed
+        prompt = str(job["prompt"]).strip()
+        job_label = f"[job {i}/{len(jobs)}]"
+
+        fields = _merge_non_null(base_fields, job.get("fields", {}))
+        fields = _merge_non_null(fields, {k: job.get(k) for k in base_fields.keys()})
+        augmented = _augment_prompt_fields(args.augment, prompt, fields)
+
+        payload = dict(base_payload)
+        payload["prompt"] = augmented
+        payload = _merge_non_null(payload, {k: job.get(k) for k in base_payload.keys()})
+        payload = {k: v for k, v in payload.items() if v is not None}
+
+        n = int(payload.get("n", 1))
+        _validate_generate_payload(payload)
+        effective_output_format = _normalize_output_format(payload.get("output_format"))
+        _validate_transparency(payload.get("background"), effective_output_format)
+        payload["output_format"] = effective_output_format
+        outputs = _job_output_paths(
+            out_dir=out_dir,
+            output_format=effective_output_format,
+            idx=i,
+            prompt=prompt,
+            n=n,
+            explicit_out=job.get("out"),
+        )
+        try:
+            async with sem:
+                print(f"{job_label} starting", file=sys.stderr)
+                started = time.time()
+                result = await _generate_one_with_retries(
+                    client,
+                    payload,
+                    attempts=args.max_attempts,
+                    job_label=job_label,
+                )
+                elapsed = time.time() - started
+                print(f"{job_label} completed in {elapsed:.1f}s", file=sys.stderr)
+            images = [item.b64_json for item in result.data]
+            _decode_write_and_downscale(
+                images,
+                outputs,
+                force=args.force,
+                downscale_max_dim=args.downscale_max_dim,
+                downscale_suffix=args.downscale_suffix,
+                output_format=effective_output_format,
+            )
+            return i, None
+        except Exception as exc:
+            any_failed = True
+            print(f"{job_label} failed: {exc}", file=sys.stderr)
+            if args.fail_fast:
+                raise
+            return i, str(exc)
+
+    tasks = [asyncio.create_task(run_job(i, job)) for i, job in enumerate(jobs, start=1)]
+
+    try:
+        await asyncio.gather(*tasks)
+    except Exception:
+        for t in tasks:
+            if not t.done():
+                t.cancel()
+        raise
+
+    return 1 if any_failed else 0
+
+
+def _generate_batch(args: argparse.Namespace) -> None:
+    exit_code = asyncio.run(_run_generate_batch(args))
+    if exit_code:
+        raise SystemExit(exit_code)
+
+
+def _generate(args: argparse.Namespace) -> None:
+    prompt = _read_prompt(args.prompt, args.prompt_file)
+    prompt = _augment_prompt(args, prompt)
+
+    payload = {
+        "model": args.model,
+        "prompt": prompt,
+        "n": args.n,
+        "size": args.size,
+        "quality": args.quality,
+        "background": args.background,
+        "output_format": args.output_format,
+        "output_compression": args.output_compression,
+        "moderation": args.moderation,
+    }
+    payload = {k: v for k, v in payload.items() if v is not None}
+
+    output_format = _normalize_output_format(args.output_format)
+    _validate_transparency(args.background, output_format)
+    payload["output_format"] = output_format
+    output_paths = _build_output_paths(args.out, output_format, args.n, args.out_dir)
+    downscaled = None
+    if args.downscale_max_dim is not None:
+        downscaled = [str(_derive_downscale_path(p, args.downscale_suffix)) for p in output_paths]
+
+    if args.dry_run:
+        _print_request(
+            {
+                "endpoint": "/v1/images/generations",
+                "outputs": [str(p) for p in output_paths],
+                "outputs_downscaled": downscaled,
+                **payload,
+            }
+        )
+        return
+
+    print(
+        "Calling Image API (generation). This can take up to a couple of minutes.",
+        file=sys.stderr,
+    )
+    started = time.time()
+    client = _create_client()
+    result = client.images.generate(**payload)
+    elapsed = time.time() - started
+    print(f"Generation completed in {elapsed:.1f}s.", file=sys.stderr)
+
+    images = [item.b64_json for item in result.data]
+    _decode_write_and_downscale(
+        images,
+        output_paths,
+        force=args.force,
+        downscale_max_dim=args.downscale_max_dim,
+        downscale_suffix=args.downscale_suffix,
+        output_format=output_format,
+    )
+
+
+def _edit(args: argparse.Namespace) -> None:
+    prompt = _read_prompt(args.prompt, args.prompt_file)
+    prompt = _augment_prompt(args, prompt)
+
+    image_paths = _check_image_paths(args.image)
+    mask_path = Path(args.mask) if args.mask else None
+    if mask_path:
+        if not mask_path.exists():
+            _die(f"Mask file not found: {mask_path}")
+        if mask_path.suffix.lower() != ".png":
+            _warn(f"Mask should be a PNG with an alpha channel: {mask_path}")
+        if mask_path.stat().st_size > MAX_IMAGE_BYTES:
+            _warn(f"Mask exceeds 50MB limit: {mask_path}")
+
+    payload = {
+        "model": args.model,
+        "prompt": prompt,
+        "n": args.n,
+        "size": args.size,
+        "quality": args.quality,
+        "background": args.background,
+        "output_format": args.output_format,
+        "output_compression": args.output_compression,
+        "input_fidelity": args.input_fidelity,
+        "moderation": args.moderation,
+    }
+    payload = {k: v for k, v in payload.items() if v is not None}
+
+    output_format = _normalize_output_format(args.output_format)
+    _validate_transparency(args.background, output_format)
+    payload["output_format"] = output_format
+    _validate_input_fidelity(args.input_fidelity)
+    output_paths = _build_output_paths(args.out, output_format, args.n, args.out_dir)
+    downscaled = None
+    if args.downscale_max_dim is not None:
+        downscaled = [str(_derive_downscale_path(p, args.downscale_suffix)) for p in output_paths]
+
+    if args.dry_run:
+        payload_preview = dict(payload)
+        payload_preview["image"] = [str(p) for p in image_paths]
+        if mask_path:
+            payload_preview["mask"] = str(mask_path)
+        _print_request(
+            {
+                "endpoint": "/v1/images/edits",
+                "outputs": [str(p) for p in output_paths],
+                "outputs_downscaled": downscaled,
+                **payload_preview,
+            }
+        )
+        return
+
+    print(
+        f"Calling Image API (edit) with {len(image_paths)} image(s).",
+        file=sys.stderr,
+    )
+    started = time.time()
+    client = _create_client()
+
+    with _open_files(image_paths) as image_files, _open_mask(mask_path) as mask_file:
+        request = dict(payload)
+        request["image"] = image_files if len(image_files) > 1 else image_files[0]
+        if mask_file is not None:
+            request["mask"] = mask_file
+        result = client.images.edit(**request)
+
+    elapsed = time.time() - started
+    print(f"Edit completed in {elapsed:.1f}s.", file=sys.stderr)
+    images = [item.b64_json for item in result.data]
+    _decode_write_and_downscale(
+        images,
+        output_paths,
+        force=args.force,
+        downscale_max_dim=args.downscale_max_dim,
+        downscale_suffix=args.downscale_suffix,
+        output_format=output_format,
+    )
+
+
+def _open_files(paths: List[Path]):
+    return _FileBundle(paths)
+
+
+def _open_mask(mask_path: Optional[Path]):
+    if mask_path is None:
+        return _NullContext()
+    return _SingleFile(mask_path)
+
+
+class _NullContext:
+    def __enter__(self):
+        return None
+
+    def __exit__(self, exc_type, exc, tb):
+        return False
+
+
+class _SingleFile:
+    def __init__(self, path: Path):
+        self._path = path
+        self._handle = None
+
+    def __enter__(self):
+        self._handle = self._path.open("rb")
+        return self._handle
+
+    def __exit__(self, exc_type, exc, tb):
+        if self._handle:
+            try:
+                self._handle.close()
+            except Exception:
+                pass
+        return False
+
+
+class _FileBundle:
+    def __init__(self, paths: List[Path]):
+        self._paths = paths
+        self._handles: List[object] = []
+
+    def __enter__(self):
+        self._handles = [p.open("rb") for p in self._paths]
+        return self._handles
+
+    def __exit__(self, exc_type, exc, tb):
+        for handle in self._handles:
+            try:
+                handle.close()
+            except Exception:
+                pass
+        return False
+
+
+def _add_shared_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--model", default=DEFAULT_MODEL)
+    parser.add_argument("--prompt")
+    parser.add_argument("--prompt-file")
+    parser.add_argument("--n", type=int, default=1)
+    parser.add_argument("--size", default=DEFAULT_SIZE)
+    parser.add_argument("--quality", default=DEFAULT_QUALITY)
+    parser.add_argument("--background")
+    parser.add_argument("--output-format")
+    parser.add_argument("--output-compression", type=int)
+    parser.add_argument("--moderation")
+    parser.add_argument("--out", default=DEFAULT_OUTPUT_PATH)
+    parser.add_argument("--out-dir")
+    parser.add_argument("--force", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--augment", dest="augment", action="store_true")
+    parser.add_argument("--no-augment", dest="augment", action="store_false")
+    parser.set_defaults(augment=True)
+
+    # Prompt augmentation hints
+    parser.add_argument("--use-case")
+    parser.add_argument("--scene")
+    parser.add_argument("--subject")
+    parser.add_argument("--style")
+    parser.add_argument("--composition")
+    parser.add_argument("--lighting")
+    parser.add_argument("--palette")
+    parser.add_argument("--materials")
+    parser.add_argument("--text")
+    parser.add_argument("--constraints")
+    parser.add_argument("--negative")
+
+    # Post-processing (optional): generate an additional downscaled copy for fast web loading.
+    parser.add_argument("--downscale-max-dim", type=int)
+    parser.add_argument("--downscale-suffix", default=DEFAULT_DOWNSCALE_SUFFIX)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Fallback CLI for explicit image generation or editing via GPT Image models"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    gen_parser = subparsers.add_parser("generate", help="Create a new image")
+    _add_shared_args(gen_parser)
+    gen_parser.set_defaults(func=_generate)
+
+    batch_parser = subparsers.add_parser(
+        "generate-batch",
+        help="Generate multiple prompts concurrently (JSONL input)",
+    )
+    _add_shared_args(batch_parser)
+    batch_parser.add_argument("--input", required=True, help="Path to JSONL file (one job per line)")
+    batch_parser.add_argument("--concurrency", type=int, default=DEFAULT_CONCURRENCY)
+    batch_parser.add_argument("--max-attempts", type=int, default=3)
+    batch_parser.add_argument("--fail-fast", action="store_true")
+    batch_parser.set_defaults(func=_generate_batch)
+
+    edit_parser = subparsers.add_parser("edit", help="Edit an existing image")
+    _add_shared_args(edit_parser)
+    edit_parser.add_argument("--image", action="append", required=True)
+    edit_parser.add_argument("--mask")
+    edit_parser.add_argument("--input-fidelity")
+    edit_parser.set_defaults(func=_edit)
+
+    args = parser.parse_args()
+    if args.n < 1 or args.n > 10:
+        _die("--n must be between 1 and 10")
+    if getattr(args, "concurrency", 1) < 1 or getattr(args, "concurrency", 1) > 25:
+        _die("--concurrency must be between 1 and 25")
+    if getattr(args, "max_attempts", 3) < 1 or getattr(args, "max_attempts", 3) > 10:
+        _die("--max-attempts must be between 1 and 10")
+    if args.output_compression is not None and not (0 <= args.output_compression <= 100):
+        _die("--output-compression must be between 0 and 100")
+    if args.command == "generate-batch" and not args.out_dir:
+        _die("generate-batch requires --out-dir")
+    if getattr(args, "downscale_max_dim", None) is not None and args.downscale_max_dim < 1:
+        _die("--downscale-max-dim must be >= 1")
+
+    _validate_model(args.model)
+    _validate_size(args.size, args.model)
+    _validate_quality(args.quality)
+    _validate_background(args.background)
+    _validate_model_specific_options(
+        model=args.model,
+        background=args.background,
+        input_fidelity=getattr(args, "input_fidelity", None),
+    )
+    _ensure_api_key(args.dry_run)
+
+    args.func(args)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/imagegen/scripts/remove_chroma_key.py b/skills/imagegen/scripts/remove_chroma_key.py
new file mode 100644
index 0000000..5053987
--- /dev/null
+++ b/skills/imagegen/scripts/remove_chroma_key.py
@@ -0,0 +1,440 @@
+#!/usr/bin/env python3
+"""Remove a solid chroma-key background from an image.
+
+This helper supports the imagegen skill's built-in-first transparent workflow:
+generate an image on a flat key color, then convert that key color to alpha.
+"""
+
+from __future__ import annotations
+
+import argparse
+from io import BytesIO
+from pathlib import Path
+import re
+from statistics import median
+import sys
+from typing import Tuple
+
+
+Color = Tuple[int, int, int]
+KEY_DOMINANCE_THRESHOLD = 16.0
+ALPHA_NOISE_FLOOR = 8
+
+
+def _die(message: str, code: int = 1) -> None:
+    print(f"Error: {message}", file=sys.stderr)
+    raise SystemExit(code)
+
+
+def _dependency_hint(package: str) -> str:
+    return (
+        "Activate the repo-selected environment first, then install it with "
+        f"`uv pip install {package}`. If this repo uses a local virtualenv, start with "
+        "`source .venv/bin/activate`; otherwise use this repo's configured shared fallback "
+        "environment."
+    )
+
+
+def _load_pillow():
+    try:
+        from PIL import Image, ImageFilter
+    except ImportError:
+        _die(f"Pillow is required for chroma-key removal. {_dependency_hint('pillow')}")
+    return Image, ImageFilter
+
+
+def _parse_key_color(raw: str) -> Color:
+    value = raw.strip()
+    match = re.fullmatch(r"#?([0-9a-fA-F]{6})", value)
+    if not match:
+        _die("key color must be a hex RGB value like #00ff00.")
+    hex_value = match.group(1)
+    return (
+        int(hex_value[0:2], 16),
+        int(hex_value[2:4], 16),
+        int(hex_value[4:6], 16),
+    )
+
+
+def _validate_args(args: argparse.Namespace) -> None:
+    if args.tolerance < 0 or args.tolerance > 255:
+        _die("--tolerance must be between 0 and 255.")
+    if args.transparent_threshold < 0 or args.transparent_threshold > 255:
+        _die("--transparent-threshold must be between 0 and 255.")
+    if args.opaque_threshold < 0 or args.opaque_threshold > 255:
+        _die("--opaque-threshold must be between 0 and 255.")
+    if args.soft_matte and args.transparent_threshold >= args.opaque_threshold:
+        _die("--transparent-threshold must be lower than --opaque-threshold.")
+    if args.edge_feather < 0 or args.edge_feather > 64:
+        _die("--edge-feather must be between 0 and 64.")
+    if args.edge_contract < 0 or args.edge_contract > 16:
+        _die("--edge-contract must be between 0 and 16.")
+
+    src = Path(args.input)
+    if not src.exists():
+        _die(f"Input image not found: {src}")
+
+    out = Path(args.out)
+    if out.exists() and not args.force:
+        _die(f"Output already exists: {out} (use --force to overwrite)")
+
+    if out.suffix.lower() not in {".png", ".webp"}:
+        _die("--out must end in .png or .webp so the alpha channel is preserved.")
+
+
+def _channel_distance(a: Color, b: Color) -> int:
+    return max(abs(a[0] - b[0]), abs(a[1] - b[1]), abs(a[2] - b[2]))
+
+
+def _clamp_channel(value: float) -> int:
+    return max(0, min(255, int(round(value))))
+
+
+def _smoothstep(value: float) -> float:
+    value = max(0.0, min(1.0, value))
+    return value * value * (3.0 - 2.0 * value)
+
+
+def _soft_alpha(distance: int, transparent_threshold: float, opaque_threshold: float) -> int:
+    if distance <= transparent_threshold:
+        return 0
+    if distance >= opaque_threshold:
+        return 255
+    ratio = (float(distance) - transparent_threshold) / (
+        opaque_threshold - transparent_threshold
+    )
+    return _clamp_channel(255.0 * _smoothstep(ratio))
+
+
+def _dominance_alpha(rgb: Color, key: Color) -> int:
+    spill_channels = _spill_channels(key)
+    if not spill_channels:
+        return 255
+
+    channels = [float(value) for value in rgb]
+    non_spill = [idx for idx in range(3) if idx not in spill_channels]
+    key_strength = (
+        min(channels[idx] for idx in spill_channels)
+        if len(spill_channels) > 1
+        else channels[spill_channels[0]]
+    )
+    non_key_strength = max((channels[idx] for idx in non_spill), default=0.0)
+    dominance = key_strength - non_key_strength
+    if dominance <= 0:
+        return 255
+
+    denominator = max(1.0, float(max(key)) - non_key_strength)
+    alpha = 1.0 - min(1.0, dominance / denominator)
+    return _clamp_channel(alpha * 255.0)
+
+
+def _spill_channels(key: Color) -> list[int]:
+    key_max = max(key)
+    if key_max < 128:
+        return []
+    return [idx for idx, value in enumerate(key) if value >= key_max - 16 and value >= 128]
+
+
+def _key_channel_dominance(rgb: Color, key: Color) -> float:
+    spill_channels = _spill_channels(key)
+    if not spill_channels:
+        return 0.0
+
+    channels = [float(value) for value in rgb]
+    non_spill = [idx for idx in range(3) if idx not in spill_channels]
+    key_strength = (
+        min(channels[idx] for idx in spill_channels)
+        if len(spill_channels) > 1
+        else channels[spill_channels[0]]
+    )
+    non_key_strength = max((channels[idx] for idx in non_spill), default=0.0)
+    return key_strength - non_key_strength
+
+
+def _looks_key_colored(rgb: Color, key: Color, distance: int) -> bool:
+    if distance <= 32:
+        return True
+
+    spill_channels = _spill_channels(key)
+    if not spill_channels:
+        return True
+
+    return _key_channel_dominance(rgb, key) >= KEY_DOMINANCE_THRESHOLD
+
+
+def _cleanup_spill(rgb: Color, key: Color, alpha: int = 255) -> Color:
+    if alpha >= 252:
+        return rgb
+
+    spill_channels = _spill_channels(key)
+    if not spill_channels:
+        return rgb
+
+    channels = [float(value) for value in rgb]
+    non_spill = [idx for idx in range(3) if idx not in spill_channels]
+    if non_spill:
+        anchor = max(channels[idx] for idx in non_spill)
+        cap = max(0.0, anchor - 1.0)
+        for idx in spill_channels:
+            if channels[idx] > cap:
+                channels[idx] = cap
+
+    return (
+        _clamp_channel(channels[0]),
+        _clamp_channel(channels[1]),
+        _clamp_channel(channels[2]),
+    )
+
+
+def _apply_alpha_to_image(
+    image,
+    *,
+    key: Color,
+    tolerance: int,
+    spill_cleanup: bool,
+    soft_matte: bool,
+    transparent_threshold: float,
+    opaque_threshold: float,
+) -> int:
+    pixels = image.load()
+    width, height = image.size
+    transparent = 0
+
+    for y in range(height):
+        for x in range(width):
+            red, green, blue, alpha = pixels[x, y]
+            rgb = (red, green, blue)
+            distance = _channel_distance(rgb, key)
+            key_like = _looks_key_colored(rgb, key, distance)
+            output_alpha = (
+                min(
+                    _soft_alpha(distance, transparent_threshold, opaque_threshold),
+                    _dominance_alpha(rgb, key),
+                )
+                if soft_matte and key_like
+                else (0 if distance <= tolerance else 255)
+            )
+            output_alpha = int(round(output_alpha * (alpha / 255.0)))
+            if 0 < output_alpha <= ALPHA_NOISE_FLOOR:
+                output_alpha = 0
+
+            if output_alpha == 0:
+                pixels[x, y] = (0, 0, 0, 0)
+                transparent += 1
+                continue
+
+            if spill_cleanup and key_like:
+                red, green, blue = _cleanup_spill(rgb, key, output_alpha)
+            pixels[x, y] = (red, green, blue, output_alpha)
+
+    return transparent
+
+
+def _contract_alpha(image, pixels: int):
+    if pixels == 0:
+        return image
+
+    _, ImageFilter = _load_pillow()
+    alpha = image.getchannel("A")
+    for _ in range(pixels):
+        alpha = alpha.filter(ImageFilter.MinFilter(3))
+    image.putalpha(alpha)
+    return image
+
+
+def _apply_edge_feather(image, radius: float):
+    if radius == 0:
+        return image
+
+    _, ImageFilter = _load_pillow()
+    alpha = image.getchannel("A")
+    alpha = alpha.filter(ImageFilter.GaussianBlur(radius=radius))
+    image.putalpha(alpha)
+    return image
+
+
+def _encode_image(image, output_format: str) -> bytes:
+    out = BytesIO()
+    image.save(out, format=output_format.upper())
+    return out.getvalue()
+
+
+def _alpha_counts(image) -> tuple[int, int, int]:
+    pixels = image.load()
+    width, height = image.size
+    total = 0
+    transparent = 0
+    partial = 0
+
+    for y in range(height):
+        for x in range(width):
+            alpha = pixels[x, y][3]
+            total += 1
+            if alpha == 0:
+                transparent += 1
+            elif alpha < 255:
+                partial += 1
+
+    return total, transparent, partial
+
+
+def _sample_border_key(image, mode: str) -> Color:
+    width, height = image.size
+    pixels = image.load()
+    samples: list[Color] = []
+
+    if mode == "corners":
+        patch = max(1, min(width, height, 12))
+        boxes = [
+            (0, 0, patch, patch),
+            (width - patch, 0, width, patch),
+            (0, height - patch, patch, height),
+            (width - patch, height - patch, width, height),
+        ]
+        for left, top, right, bottom in boxes:
+            for y in range(top, bottom):
+                for x in range(left, right):
+                    red, green, blue = pixels[x, y][:3]
+                    samples.append((red, green, blue))
+    else:
+        band = max(1, min(width, height, 6))
+        step = max(1, min(width, height) // 256)
+        for x in range(0, width, step):
+            for y in range(band):
+                red, green, blue = pixels[x, y][:3]
+                samples.append((red, green, blue))
+                red, green, blue = pixels[x, height - 1 - y][:3]
+                samples.append((red, green, blue))
+        for y in range(0, height, step):
+            for x in range(band):
+                red, green, blue = pixels[x, y][:3]
+                samples.append((red, green, blue))
+                red, green, blue = pixels[width - 1 - x, y][:3]
+                samples.append((red, green, blue))
+
+    if not samples:
+        _die("Could not sample background key color from image border.")
+
+    return (
+        int(round(median(sample[0] for sample in samples))),
+        int(round(median(sample[1] for sample in samples))),
+        int(round(median(sample[2] for sample in samples))),
+    )
+
+
+def _remove_chroma_key(args: argparse.Namespace) -> None:
+    Image, _ = _load_pillow()
+    src = Path(args.input)
+    out = Path(args.out)
+
+    with Image.open(src) as image:
+        rgba = image.convert("RGBA")
+    key = (
+        _sample_border_key(rgba, args.auto_key)
+        if args.auto_key != "none"
+        else _parse_key_color(args.key_color)
+    )
+
+    transparent = _apply_alpha_to_image(
+        rgba,
+        key=key,
+        tolerance=args.tolerance,
+        spill_cleanup=args.spill_cleanup,
+        soft_matte=args.soft_matte,
+        transparent_threshold=args.transparent_threshold,
+        opaque_threshold=args.opaque_threshold,
+    )
+    rgba = _contract_alpha(rgba, args.edge_contract)
+    rgba = _apply_edge_feather(rgba, args.edge_feather)
+
+    total, transparent_after, partial_after = _alpha_counts(rgba)
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    output_format = "PNG" if out.suffix.lower() == ".png" else "WEBP"
+    out.write_bytes(_encode_image(rgba, output_format))
+
+    print(f"Wrote {out}")
+    print(f"Key color: #{key[0]:02x}{key[1]:02x}{key[2]:02x}")
+    print(f"Transparent pixels: {transparent_after}/{total}")
+    print(f"Partially transparent pixels: {partial_after}/{total}")
+    if transparent == 0:
+        print("Warning: no pixels matched the key color before feathering.", file=sys.stderr)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Remove a solid chroma-key background and write an image with alpha."
+    )
+    parser.add_argument("--input", required=True, help="Input image path.")
+    parser.add_argument("--out", required=True, help="Output .png or .webp path.")
+    parser.add_argument(
+        "--key-color",
+        default="#00ff00",
+        help="Hex RGB key color to remove, for example #00ff00.",
+    )
+    parser.add_argument(
+        "--tolerance",
+        type=int,
+        default=12,
+        help="Hard-key per-channel tolerance for matching the key color, 0-255.",
+    )
+    parser.add_argument(
+        "--auto-key",
+        choices=["none", "corners", "border"],
+        default="none",
+        help="Sample the key color from image corners or border instead of --key-color.",
+    )
+    parser.add_argument(
+        "--soft-matte",
+        action="store_true",
+        help="Use a smooth alpha ramp between transparent and opaque thresholds.",
+    )
+    parser.add_argument(
+        "--transparent-threshold",
+        type=float,
+        default=12.0,
+        help="Soft-matte distance at or below which pixels become fully transparent.",
+    )
+    parser.add_argument(
+        "--opaque-threshold",
+        type=float,
+        default=96.0,
+        help="Soft-matte distance at or above which pixels become fully opaque.",
+    )
+    parser.add_argument(
+        "--edge-feather",
+        type=float,
+        default=0.0,
+        help="Optional alpha blur radius for softened edges, 0-64.",
+    )
+    parser.add_argument(
+        "--edge-contract",
+        type=int,
+        default=0,
+        help="Shrink the visible alpha matte by this many pixels before feathering.",
+    )
+    parser.add_argument(
+        "--spill-cleanup",
+        dest="spill_cleanup",
+        action="store_true",
+        help="Reduce obvious key-color spill on opaque pixels.",
+    )
+    parser.add_argument(
+        "--despill",
+        dest="spill_cleanup",
+        action="store_true",
+        help="Alias for --spill-cleanup; decontaminate key-color edge spill.",
+    )
+    parser.add_argument("--force", action="store_true", help="Overwrite an existing output file.")
+    return parser
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+    _validate_args(args)
+    _remove_chroma_key(args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/skills/openai-docs/LICENSE.txt b/skills/openai-docs/LICENSE.txt
new file mode 100644
index 0000000..13e25df
--- /dev/null
+++ b/skills/openai-docs/LICENSE.txt
@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf of
+   any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don\'t include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/skills/openai-docs/SKILL.md b/skills/openai-docs/SKILL.md
new file mode 100644
index 0000000..30526bd
--- /dev/null
+++ b/skills/openai-docs/SKILL.md
@@ -0,0 +1,167 @@
+---
+name: "openai-docs"
+description: "Use when the user asks how to build with OpenAI products or APIs, asks about Codex itself or choosing Codex surfaces, needs up-to-date official documentation with citations, help choosing the latest model for a use case, or model upgrade and prompt-upgrade guidance; use OpenAI docs MCP tools for non-Codex docs questions, use the Codex manual helper first for broad Codex self-knowledge, and restrict fallback browsing to official OpenAI domains."
+---
+
+
+# OpenAI Docs
+
+Provide authoritative, current guidance from OpenAI developer docs using the developers.openai.com MCP server. "Docs MCP" means `mcp__openaiDeveloperDocs__search_openai_docs` and `mcp__openaiDeveloperDocs__fetch_openai_doc`; for API reference, schema, parameter, or required-field questions, also use `mcp__openaiDeveloperDocs__get_openapi_spec` when available. Official-domain web search is fallback after those tools are unavailable or unhelpful. Broad Codex questions use the manual helper before Docs MCP. This skill also owns model selection, API model migration, and prompt-upgrade guidance.
+
+## API Key Setup
+
+For requests to build, run, configure, debug, or implement an API-backed app, script, CLI, generator, or tool, use `openai-platform-api-key` first when available. After that credential gate is resolved, return here for current docs as needed.
+
+Use this skill directly for docs-only questions, citations, model/API guidance, conceptual explanations, and examples that do not require building or running an API-backed artifact.
+
+## Workflow Configuration
+
+### Source Priority
+
+- For Codex self-knowledge, use the Codex source route below; it owns when to use the manual helper, Docs MCP, or bounded uncertainty.
+- For non-Codex OpenAI docs questions, use `mcp__openaiDeveloperDocs__search_openai_docs` to find the most relevant doc pages.
+- For non-Codex OpenAI docs questions, fetch the relevant page with `mcp__openaiDeveloperDocs__fetch_openai_doc` before answering. If search is noisy, run a narrower Docs MCP search; when any plausible official OpenAI docs URL is known or found, try fetching that URL through Docs MCP before relying on web-search content.
+- For API reference, schema, parameter, or required-field questions, use `mcp__openaiDeveloperDocs__get_openapi_spec` when available to verify the API shape alongside the relevant guide or reference page.
+- Use `mcp__openaiDeveloperDocs__list_openai_docs` only when you need to browse or discover non-Codex pages without a clear query.
+- For model-selection, "latest model", or default-model questions, fetch `https://developers.openai.com/api/docs/guides/latest-model.md` first. If that is unavailable, load `references/latest-model.md`.
+- For model upgrades or prompt upgrades, run `node scripts/resolve-latest-model-info.js` only when the target is latest/current/default or otherwise unspecified; otherwise preserve the explicitly requested target.
+- Preserve explicit target requests: if the user names a target model like "migrate to GPT-5.4", keep that requested target even if `latest-model.md` names a newer model. Mention newer guidance only as optional.
+- If current remote guidance is needed, fetch both the returned migration and prompting guide URLs directly. If direct fetch fails, use MCP/search fallback; if that also fails, use bundled fallback references and disclose the fallback.
+
+## OpenAI product snapshots
+
+1. Apps SDK: Build ChatGPT apps by providing a web component UI and an MCP server that exposes your app's tools to ChatGPT.
+2. Responses API: A unified endpoint designed for stateful, multimodal, tool-using interactions in agentic workflows.
+3. Chat Completions API: Generate a model response from a list of messages comprising a conversation.
+4. Codex: OpenAI's coding agent for software development that can write, understand, review, and debug code.
+5. gpt-oss: Open-weight OpenAI reasoning models (gpt-oss-120b and gpt-oss-20b) released under the Apache 2.0 license.
+6. Realtime API: Build low-latency, multimodal experiences including natural speech-to-speech conversations.
+7. Agents SDK: A toolkit for building agentic apps where a model can use tools and context, hand off to other agents, stream partial results, and keep a full trace.
+
+## Codex self-knowledge
+
+Use this path for questions about Codex itself: configuring, extending, operating, troubleshooting, local state, product surfaces, or where Codex behavior should live. A codebase merely mentioning a plugin, skill, hook, MCP server, browser, or automation is not enough. For generic software tasks, answer the software task directly; if asked whether Codex self-knowledge applies, answer that meta question briefly and continue the requested artifact.
+
+### Source Route
+
+The Codex manual is the first source for broad Codex synthesis. Treat the manual and Docs MCP as different lanes, not interchangeable official-doc sources. For published-user Codex product answers, the source route is complete: the manual, Docs MCP when this route calls for it, official OpenAI web fallback, and callable capabilities surfaced in the current session when the question is about that capability. Knowledge bases outside developers.openai.com are outside this route for public product answers.
+
+For broad Codex behavior, setup, customization, skills, plugins, MCP, hooks, `AGENTS.md`, automations, surfaces, local state, or system-map questions:
+
+1. Reuse a same-thread manual and outline path when it is still fresh.
+2. Otherwise run the skill-local helper first in normal writable sessions. Skip it without trying only when the session is explicitly read-only, shell execution is unavailable, or visible policy shows no allowed temp cache.
+3. By default, the helper chooses the first usable temp cache dir in this order: `$TMPDIR/openai-docs-cache`, `%TEMP%\openai-docs-cache`, `%TMP%\openai-docs-cache`, `/private/tmp/openai-docs-cache`, then `/tmp/openai-docs-cache`. Workspace-only write access is not enough for this temp cache.
+4. Run the helper directly unless you need to override the cache dir. The helper falls back to `curl` when native `fetch` is unavailable or when proxy env vars are present, so no shell-specific proxy prefix is required. Resolve `<skill-dir>` to this skill's actual directory; in copied local eval workdirs this is usually `.codex/skills/openai-docs`:
+
+```bash
+node <skill-dir>/scripts/fetch-codex-manual.mjs
+```
+
+If you need to override the cache dir, pass `--cache-dir <cache-dir>`. On Windows, the helper checks `%TEMP%` and `%TMP%` automatically; in PowerShell, `$env:TEMP\\openai-docs-cache` is a typical explicit override.
+
+Treat helper availability as established by explicit read-only/no-shell policy or an actual command result. A guessed sandbox or guessed helper failure is not enough to switch to Docs MCP or web lookup; after an actual helper command failure, continue to the narrowest official next source below.
+
+The helper verifies freshness, writes `codex-manual.md`, and emits `codex-manual.outline.md`. The outline maps source pages and headings to line ranges; use it to choose the relevant manual section, then read or search targeted manual sections for Codex product facts. Use the skill directory to locate and run the helper; after the helper succeeds, use the returned manual and outline paths as the search scope for Codex product facts and term coverage checks.
+
+Reuse the same-thread manual and outline paths for follow-up Codex questions. Refresh first when the manual was fetched more than about a day ago, the path is unusable, the path came from another thread or uncertain provenance, or likely-current information is missing and staleness is plausible.
+
+For questions about whether the manual is current enough to rely on now, run the helper when temp caching is allowed and base the answer on its returned status, manual path, and outline path.
+
+If the manual resolves a Codex claim, answer from it and stop expanding sources for that claim; continue the user's broader task if the docs lookup was only one dependency. Manual source pages and known anchors are enough citation support for manual-covered material.
+
+If the helper is skipped because the session is read-only, has no shell execution, or has no allowed temp cache, the next source is Docs MCP: call `mcp__openaiDeveloperDocs__search_openai_docs`, then `mcp__openaiDeveloperDocs__fetch_openai_doc` for a relevant hit before any web fallback.
+
+If a user names a Codex term or mode that a fresh manual does not use, search the manual for obvious adjacent concepts, then answer that the exact term is not documented and use the closest documented terminology. If the prompt asks how that term maps to Codex behavior, resolve the mapping from adjacent manual sections. If the exact term remains material or likely current after that manual pass, use one narrow Docs MCP search/fetch before bounded uncertainty; otherwise, the source lookup for that terminology or mapping claim is complete.
+
+Use the narrowest official next source only when the manual is unavailable, the helper fails, temp caching is not allowed, another material claim is missing or likely stale, or the user explicitly needs a page-specific citation. Prefer one specific Docs MCP search and, if it returns a clearly relevant page, one fetch; for unresolved Codex capability names, acronyms, scheduling terms, or exact error text, this Docs MCP step is the next source before web search. After the manual plus any permitted Docs MCP gap-fill, resolve remaining gaps as bounded uncertainty. Use official-domain web fallback only after that Docs MCP path is unavailable or unhelpful. If the claim is still not established, stop with bounded uncertainty. If official docs/manual conflict with a callable capability already surfaced in the current session, state the conflict and prefer verified current-session behavior for that environment.
+
+For undocumented or private-looking model slugs, product mode labels, entitlement labels, account access paths, or rollout names, answer from current public docs and bounded uncertainty. Those labels are not a reason to leave the public source route.
+
+For support-style diagnostics, prefer a layer-by-layer answer from the manual over provider-specific web lookups: installed/enabled plugin, bundled app or connector authorization, MCP setup, workspace/admin policy, restart or new-thread expectations, then support or feedback if still unresolved.
+
+If the source route still does not establish a claim, return bounded uncertainty or route to support, an admin, or product feedback instead of widening the investigation.
+
+For unresolved product terminology, answer from the manual plus the allowed official next source. If those sources do not establish the term, answer with bounded uncertainty from those sources.
+
+### Surface Map
+
+When Codex nouns or durable-instruction surfaces overlap, recommend the smallest surface that matches the scope:
+
+- Prompt or thread context -> one-off task constraints.
+- `AGENTS.md` -> durable repo conventions, commands, verification steps, and review expectations; closer nested files apply under their subtree.
+- Project `.codex/config.toml` -> trusted-repo Codex settings such as sandbox, MCP, hooks, model, or reasoning defaults.
+- Global config or global guidance -> personal defaults across repos.
+- Skill -> reusable task workflow with references or scripts.
+- Plugin -> installable bundle with skills plus commands, tools, MCP config, hooks, assets, apps, or marketplace metadata.
+- MCP server or app connector -> live external data/actions or authorized private app/workspace data. Use connectors for private Google Docs, Calendar, Slack, GitHub, Notion, and similar data instead of web search or model memory.
+- Automation -> scheduled checks, reminders, monitors, or follow-up work; use a thread heartbeat when continuity in an existing thread matters.
+- Hook -> lifecycle enforcement around tool calls, commands, or file edits.
+
+Split mixed-scope requests instead of forcing one answer. Example: "always do X, but only for this PR" defaults to prompt/thread context for the current run; use `AGENTS.md` or project config only if it should persist, hooks only for mechanical enforcement, and automations only for scheduled or follow-up work.
+
+Use this quick product map when needed: CLI is terminal-first local repo work; IDE extension is editor-attached coding; Codex app is desktop planning, review, and interactive work; cloud/web is hosted parallel/offloaded work; Browser Use/in-app browser is Codex-controlled web testing; Chrome extension uses the user's Chrome profile; Computer Use controls desktop apps and OS UI. Keep `config.toml` defaults, `requirements.toml` constraints, and managed/admin policy separate.
+
+### Boundaries And Output
+
+- API key auth does not imply ChatGPT, cloud task, or connector access. For plugin/app/auth failures, check bundle availability, plugin installed/enabled state, connector/app authorization, MCP setup, restart/refresh expectations, workspace policy, and per-surface availability before answering.
+- Sandbox or network denials need scoped escalation with a clear justification. Destructive commands, writes outside the workspace, or broad access changes require explicit approval.
+- Memory can provide user preference or context, but explicit prompt instructions win and memory is not a source for current external facts.
+- For affirmative surface-selection answers, use this shape: recommendation, why, what to avoid, and the manual/source evidence used.
+- When page-specific Codex citations are actually needed, these anchors often fit: `concepts/customization#agents-guidance` for `AGENTS.md`, `concepts/customization#skills` for skills, `plugins/build#plugin-structure` for plugins, `concepts/customization#mcp` for MCP, `config-advanced#hooks` for hooks, `app/automations#thread-automations` for thread automations, and `config-reference#configtoml` for config.
+
+## If MCP server is missing
+
+If MCP tools fail or no OpenAI docs resources are available:
+
+1. Run the install command yourself: `codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp`
+2. If it fails due to permissions/sandboxing, immediately retry the same command with escalated permissions and include a 1-sentence justification for approval.
+3. Ask the user to run the install command only if the escalated attempt fails.
+4. Ask the user to restart Codex.
+5. Re-run the doc search/fetch after restart.
+
+## Workflow
+
+1. Clarify whether the request is general docs lookup, model selection, a model-string upgrade, prompt-upgrade guidance, or broader API/provider migration.
+2. For Codex self-knowledge requests, follow the Codex self-knowledge source procedure above.
+3. For model-selection or upgrade requests, prefer current remote docs over bundled references when the user asks for latest/current/default guidance.
+   - Fetch `https://developers.openai.com/api/docs/guides/latest-model.md`.
+   - Find the latest model ID and explicit migration or prompt-guidance links.
+   - Prefer explicit links from the latest-model page over derived URLs.
+   - For explicit named-model requests, preserve the requested model target. Mention newer remote guidance only as optional.
+   - For dynamic latest/current/default upgrades, run `node scripts/resolve-latest-model-info.js`, then fetch both returned guide URLs directly when possible.
+   - If direct guide fetch fails, use the developer-docs MCP tools or official OpenAI-domain search to find the same guide content.
+   - If remote docs are unavailable, use bundled fallback references and say that fallback guidance was used.
+4. For model upgrades, keep changes narrow: update active OpenAI API model defaults and directly related prompts only when safe.
+5. Leave historical docs, examples, eval baselines, fixtures, provider comparisons, provider registries, pricing tables, alias defaults, low-cost fallback paths, and ambiguous older model usage unchanged unless the user explicitly asks to upgrade them.
+6. Keep SDK, tooling, IDE, plugin, shell, auth, and provider-environment migrations out of a model-and-prompt upgrade unless the user explicitly asks for them.
+7. If an upgrade needs API-surface changes, schema rewiring, tool-handler changes, or implementation work beyond a literal model-string replacement and prompt edits, report it as blocked or confirmation-needed.
+8. For general docs lookup, search docs with a precise query, fetch the best page and exact section needed, and answer with concise citations.
+
+## Reference map
+
+Read only what you need:
+
+- `https://developers.openai.com/api/docs/guides/latest-model.md` -> current model-selection and "best/latest/current model" questions.
+- `scripts/fetch-codex-manual.mjs` -> current Codex manual fetch, verification, local temp cache, and outline generation.
+- `https://developers.openai.com/codex/codex-manual.md` -> current Codex self-knowledge synthesis, including setup, customization, skills, plugins, MCP, hooks, `AGENTS.md`, automations, and surface behavior; normally access it through the helper path and targeted file reads when temp caching is available.
+- `references/latest-model.md` -> bundled fallback for model-selection and "best/latest/current model" questions.
+- `references/upgrade-guide.md` -> bundled fallback for model upgrade and upgrade-planning requests.
+- `references/prompting-guide.md` -> bundled fallback for prompt rewrites and prompt-behavior upgrades.
+
+## Quality rules
+
+- Treat OpenAI docs as the source of truth; avoid speculation.
+- For Codex self-knowledge, follow the source route above instead of relying on remembered behavior.
+- Keep migration changes narrow and behavior-preserving.
+- Prefer prompt-only upgrades when possible.
+- Avoid inventing pricing, availability, parameters, API changes, or breaking changes.
+- Keep quotes short and within policy limits; prefer paraphrase with citations.
+- If multiple pages differ, call out the difference and cite both.
+- If official docs and verified callable current-session behavior disagree, state the conflict before making broad claims or edits.
+- If docs do not cover the user’s need, say so and offer next steps.
+
+## Tooling notes
+
+- Use MCP doc tools before web search for OpenAI-related markdown docs. The Codex manual flow is the exception: follow the Codex self-knowledge source procedure for broad Codex synthesis.
+- If the MCP server is installed but returns no meaningful results, then use web search as a fallback.
+- When falling back to web search, restrict to official OpenAI domains (developers.openai.com, platform.openai.com) and cite sources.
diff --git a/skills/openai-docs/agents/openai.yaml b/skills/openai-docs/agents/openai.yaml
new file mode 100644
index 0000000..8bbf03c
--- /dev/null
+++ b/skills/openai-docs/agents/openai.yaml
@@ -0,0 +1,14 @@
+interface:
+  display_name: "OpenAI Docs"
+  short_description: "Reference OpenAI docs, Codex self-knowledge, and model migration guidance"
+  icon_small: "./assets/openai-small.svg"
+  icon_large: "./assets/openai.png"
+  default_prompt: "Use OpenAI Docs for official docs lookup, questions about Codex itself or Codex surfaces, model selection, model migration, and prompt-upgrade work."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "openaiDeveloperDocs"
+      description: "OpenAI Developer Docs MCP server"
+      transport: "streamable_http"
+      url: "https://developers.openai.com/mcp"
diff --git a/skills/openai-docs/assets/openai-small.svg b/skills/openai-docs/assets/openai-small.svg
new file mode 100644
index 0000000..1d075dc
--- /dev/null
+++ b/skills/openai-docs/assets/openai-small.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" fill="currentColor" viewBox="0 0 14 14">
+  <path d="M10.931 3.34a.112.112 0 0 0-.069-.104l-.038-.007c-1.537.05-2.45.318-3.714 1.002v6.683c.48-.248.936-.44 1.414-.58.695-.203 1.417-.292 2.303-.305l.038-.008a.113.113 0 0 0 .066-.104V3.341ZM2.363 9.919c0 .064.051.11.105.111l.33.008c1.162.046 2.042.243 2.975.662-.403-.585-1.008-1.075-1.654-1.292a.991.991 0 0 1-.674-.941v-5.14a6.36 6.36 0 0 0-.59-.076l-.37-.02a.115.115 0 0 0-.122.111v6.577Zm9.455-.001a.998.998 0 0 1-.877.992l-.101.007c-.832.012-1.47.095-2.066.27-.599.174-1.176.448-1.883.863a.444.444 0 0 1-.449 0c-1.299-.763-2.229-1.07-3.689-1.125l-.299-.008a.997.997 0 0 1-.977-.998V3.342c0-.573.478-1.017 1.038-.999l.417.023c.188.015.35.037.513.062v-.754c0-.708.749-1.244 1.429-.903.984.492 1.836 1.449 2.15 2.505 1.216-.617 2.222-.884 3.771-.934l.105.003a.998.998 0 0 1 .918.996v6.576ZM4.332 8.466c0 .049.03.087.07.1l.24.091a4.319 4.319 0 0 1 1.581 1.176V3.721c-.164-.803-.799-1.617-1.584-2.07l-.162-.088c-.025-.012-.054-.013-.088.009a.12.12 0 0 0-.057.102v6.792Z"/>
+</svg>
diff --git a/skills/openai-docs/assets/openai.png b/skills/openai-docs/assets/openai.png
new file mode 100644
index 0000000..e9b9eb8
Binary files /dev/null and b/skills/openai-docs/assets/openai.png differ
diff --git a/skills/openai-docs/references/latest-model.md b/skills/openai-docs/references/latest-model.md
new file mode 100644
index 0000000..a1ffbfb
--- /dev/null
+++ b/skills/openai-docs/references/latest-model.md
@@ -0,0 +1,37 @@
+# Latest model guide
+
+This file is a curated helper. Every recommendation here must be verified against current OpenAI docs before it is repeated to a user.
+
+## Current model map
+
+| Model ID | Use for |
+| --- | --- |
+| `gpt-5.5` | Latest/default text and reasoning model for most new apps, including coding and tool-heavy workflows |
+| `gpt-5.5-pro` | Maximum reasoning or quality when latency and cost matter less |
+| `gpt-5.4` | Previous default text and reasoning model; use for existing GPT-5.4 integrations |
+| `gpt-5.4-mini` | Lower-cost testing and lighter production workflows |
+| `gpt-5.4-nano` | High-throughput simple tasks and classification |
+| `gpt-5.5` | Explicit no-reasoning text path via `reasoning.effort: none` |
+| `gpt-4.1-mini` | Cheaper no-reasoning text |
+| `gpt-4.1-nano` | Fastest and cheapest no-reasoning text |
+| `gpt-5.3-codex` | Agentic coding, code editing, and tool-heavy coding workflows |
+| `gpt-5.1-codex-mini` | Cheaper coding workflows |
+| `gpt-image-2` | Best image generation and edit quality |
+| `gpt-image-1.5` | Less expensive image generation and edit quality |
+| `gpt-image-1-mini` | Cost-optimized image generation |
+| `gpt-4o-mini-tts` | Text-to-speech |
+| `gpt-4o-mini-transcribe` | Speech-to-text, fast and cost-efficient |
+| `gpt-realtime-1.5` | Realtime voice and multimodal sessions |
+| `gpt-realtime-mini` | Cheaper realtime sessions |
+| `gpt-audio` | Chat Completions audio input and output |
+| `gpt-audio-mini` | Cheaper Chat Completions audio workflows |
+| `sora-2` | Faster iteration and draft video generation |
+| `sora-2-pro` | Higher-quality production video |
+| `omni-moderation-latest` | Text and image moderation |
+| `text-embedding-3-large` | Higher-quality retrieval embeddings; default in this skill because no best-specific row exists |
+| `text-embedding-3-small` | Lower-cost embeddings |
+
+## Maintenance notes
+
+- This file will drift unless it is periodically re-verified against current OpenAI docs.
+- If this file conflicts with current docs, the docs win.
diff --git a/skills/openai-docs/references/prompting-guide.md b/skills/openai-docs/references/prompting-guide.md
new file mode 100644
index 0000000..0d9273c
--- /dev/null
+++ b/skills/openai-docs/references/prompting-guide.md
@@ -0,0 +1,244 @@
+GPT-5.5 works best when prompts define the outcome and leave room for the model to choose an efficient solution path. Compared with earlier models, you can often use shorter, more outcome-oriented prompts: describe what good looks like, what constraints matter, what evidence is available, and what the final answer should contain.
+
+Avoid carrying over every instruction from an older prompt stack. Legacy prompts often over-specify the process because earlier models needed more help staying on track. With GPT-5.5, that can add noise, narrow the model's search space, or lead to overly mechanical answers.
+
+For more detail on GPT-5.5 behavior changes, start with the [Using GPT-5.5 guide](/api/docs/guides/latest-model). This guide focuses on prompt changes that follow from those behavior changes.
+
+The patterns here are starting points. Adapt them to your product surface, tools, evals, and user experience goals.
+
+## Personality and behavior
+
+GPT-5.5's default style is efficient, direct, and task-oriented. This is useful for production systems: responses stay focused, behavior is easier to steer, and the model avoids unnecessary conversational padding.
+
+For customer-facing assistants, support workflows, coaching experiences, and other conversational products, define both personality and collaboration style.
+
+- **Personality** controls how the assistant sounds: tone, warmth, directness, formality, humor, empathy, and level of polish.
+- **Collaboration style** controls how the assistant works: when it asks questions, when it makes assumptions, how proactive it should be, how much context it gives, when it checks work, and how it handles uncertainty or risk.
+
+Keep both short. Personality instructions should shape the user experience. Collaboration instructions should shape task behavior. Neither should replace clear goals, success criteria, tool rules, or stopping conditions.
+
+Example personality block for a steady task-focused assistant:
+
+```text
+# Personality
+You are a capable collaborator: approachable, steady, and direct. Assume the user is competent and acting in good faith, and respond with patience, respect, and practical helpfulness.
+
+Prefer making progress over stopping for clarification when the request is already clear enough to attempt. Use context and reasonable assumptions to move forward. Ask for clarification only when the missing information would materially change the answer or create meaningful risk, and keep any question narrow.
+
+Stay concise without becoming curt. Give enough context for the user to understand and trust the answer, then stop. Use examples, comparisons, or simple analogies when they make the point easier to grasp. When correcting the user or disagreeing, be candid but constructive. When an error is pointed out, acknowledge it plainly and focus on fixing it.
+
+Match the user's tone within professional bounds. Avoid emojis and profanity by default, unless the user explicitly asks for that style or has clearly established it as appropriate for the conversation.
+```
+
+Example personality block for an expressive collaborative assistant:
+
+```text
+# Personality
+Adopt a vivid conversational presence: intelligent, curious, playful when appropriate, and attentive to the user's thinking. Ask good questions when the problem is blurry, then become decisive once there is enough context.
+
+Be warm, collaborative, and polished. Conversation should feel easy and alive, but not chatty for its own sake. Offer a real point of view rather than merely mirroring the user, while staying responsive to their goals and constraints.
+
+Be thoughtful and grounded when the task calls for synthesis or advice. State a clear recommendation when you have enough context, explain important tradeoffs, and name uncertainty without becoming evasive.
+```
+
+For more expressive products, add warmth, curiosity, humor, or point of view explicitly, but keep the block short. Use personality to shape the experience, not to compensate for unclear goals or missing task instructions.
+
+## Improve time to first visible token with a preamble
+
+In streaming applications, users notice how long it takes before the first visible response appears. GPT-5.5 may spend time reasoning, planning, or preparing tool calls before emitting visible text.
+
+For longer or tool-heavy tasks, prompt the model to start with a short preamble: a brief visible update that acknowledges the request and states the first step. This can improve perceived responsiveness without changing the underlying task.
+
+Use this pattern when the task may take more than one step, require tool calls, or involve a long-running agent workflow.
+
+```text
+Before any tool calls for a multi-step task, send a short user-visible update that acknowledges the request and states the first step. Keep it to one or two sentences.
+```
+
+For coding agents that expose separate message phases, you can be more explicit:
+
+```text
+You must always start with an intermediary update before any content in the analysis channel if the task will require calling tools. The user update should acknowledge the request and explain your first step.
+```
+
+## Outcome-first prompts and stopping conditions
+
+GPT-5.5 is strongest when the prompt defines the target outcome, success criteria, constraints, and available context, then lets the model choose the path.
+
+For many tasks, describe the destination rather than every step. This gives the model room to choose the right search, tool, or reasoning strategy for the task.
+
+Prefer this:
+
+```text
+Resolve the customer's issue end to end.
+
+Success means:
+- the eligibility decision is made from the available policy and account data
+- any allowed action is completed before responding
+- the final answer includes completed_actions, customer_message, and blockers
+- if evidence is missing, ask for the smallest missing field
+```
+
+**Avoid unnecessary absolute rules.** Older prompts often use strict instructions like `ALWAYS`, `NEVER`, `must`, and `only` to control model behavior. Use those words for true invariants, such as safety rules, required output fields, or actions that should never happen. For judgment calls, such as when to search, ask for clarification, use a tool, or keep iterating, prefer decision rules instead.
+
+Avoid this style of instruction unless every step is truly required:
+
+```text
+First inspect A, then inspect B, then compare every field, then think through
+all possible exceptions, then decide which tool to call, then call the tool,
+then explain the entire process to the user.
+```
+
+Add explicit stopping conditions:
+
+```text
+Resolve the user query in the fewest useful tool loops, but do not let loop minimization outrank correctness, accessible fallback evidence, calculations, or required citation tags for factual claims.
+
+After each result, ask: "Can I answer the user's core request now with useful evidence and citations for the factual claims?" If yes, answer.
+```
+
+Define missing-evidence behavior:
+
+```text
+Use the minimum evidence sufficient to answer correctly, cite it precisely, then stop.
+```
+
+## Formatting
+
+GPT-5.5 is highly steerable on output format and structure. Use that control when it improves comprehension or product fit.
+
+Set `text.verbosity`, describe the expected output shape, and reserve heavier structure for cases where it improves comprehension or your product UI needs a stable artifact. The API default for `text.verbosity` is `medium`; use `low` when you prefer shorter, more concise responses.
+
+Plain conversational formatting:
+
+```text
+Let formatting serve comprehension. Use plain paragraphs as the default format for normal conversation, explanations, reports, documentation, and technical writeups. Keep the presentation clean and readable without making the structure feel heavier than the content.
+
+Use headers, bold text, bullets, and numbered lists sparingly. Reach for them when the user requests them, when the answer needs clear comparison or ranking, or when the information would be harder to scan as prose. Otherwise, favor short paragraphs and natural transitions.
+
+Respect formatting preferences from the user. If they ask for a terse answer, minimal formatting, no bullets, no headers, or a specific structure, follow that preference unless there is a strong reason not to.
+```
+
+Add explicit audience and length guidance:
+
+```text
+Write for a senior business audience. Keep the answer under 400 words. Use short paragraphs and only include bullets when they improve scannability. Prioritize the conclusion first, then the reasoning, then caveats.
+```
+
+For editing, rewriting, summaries, or customer-facing messages, tell the model what to preserve before asking it to improve style. This pattern is useful when you want polish without expansion.
+
+```text
+Preserve the requested artifact, length, structure, and genre first. Quietly improve clarity, flow, and correctness. Do not add new claims, extra sections, or a more promotional tone unless explicitly requested.
+```
+
+## Grounding, citations, and retrieval budgets
+
+For grounded answers, citation behavior should be part of the prompt. Define what needs support, what counts as enough evidence, and how the model should behave when evidence is missing. Absence of evidence shouldn't automatically become a factual "no." For more details and examples, see the [citation formatting guide](/api/docs/guides/citation-formatting).
+
+### Add an explicit retrieval budget
+
+Retrieval budgets are stopping rules for search. They tell the model when enough evidence is enough.
+
+```text
+For ordinary Q&A, start with one broad search using short, discriminative keywords. If the top results contain enough citable support for the core request, answer from those results instead of searching again.
+
+Make another retrieval call only when:
+- The top results do not answer the core question.
+- A required fact, parameter, owner, date, ID, or source is missing.
+- The user asked for exhaustive coverage, a comparison, or a comprehensive list.
+- A specific document, URL, email, meeting, record, or code artifact must be read.
+- The answer would otherwise contain an important unsupported factual claim.
+
+Do not search again to improve phrasing, add examples, cite nonessential details, or support wording that can safely be made more generic.
+```
+
+## Creative drafting guardrails
+
+For drafting tasks, tell the model which claims must come from sources and which parts may be creatively written. This is especially important for slides, launch copy, customer summaries, talk tracks, leadership blurbs, and narrative framing.
+
+```text
+For creative or generative requests such as slides, leadership blurbs, outbound copy, summaries for sharing, talk tracks, or narrative framing, distinguish source-backed facts from creative wording.
+
+- Use retrieved or provided facts for concrete product, customer, metric, roadmap, date, capability, and competitive claims, and cite those claims.
+- Do not invent specific names, first-party data claims, metrics, roadmap status, customer outcomes, or product capabilities to make the draft sound stronger.
+- If there is little or no citable support, write a useful generic draft with placeholders or clearly labeled assumptions rather than unsupported specifics.
+```
+
+## Frontend engineering and visual taste
+
+For frontend work, refer to the [example instructions](/api/docs/guides/frontend-prompt) for practical ways to steer UI quality. They cover product and user context, design-system alignment, first-screen usability, familiar controls, expected states, responsive behavior, and common generated-UI defaults to avoid, such as generic heroes, nested cards, decorative gradients, visible instructional text, and broken layouts.
+
+## Prompt the model to check its work
+
+Give GPT-5.5 access to tools that let it check outputs when validation is possible.
+
+For coding agents, ask for concrete validation commands:
+
+```text
+After making changes, run the most relevant validation available:
+- targeted unit tests for changed behavior
+- type checks or lint checks when applicable
+- build checks for affected packages
+- a minimal smoke test when full validation is too expensive
+
+If validation cannot be run, explain why and describe the next best check.
+```
+
+For visual artifacts, ask for inspection after rendering:
+
+```text
+Render the artifact before finalizing. Inspect the rendered output for layout, clipping, spacing, missing content, and visual consistency. Revise until the rendered output matches the requirements.
+```
+
+For engineering and planning tasks, make implementation plans traceable:
+
+```text
+For implementation plans, include:
+- requirements and where each is addressed
+- named resources, files, APIs, or systems involved
+- state transitions or data flow where relevant
+- validation commands or checks
+- failure behavior
+- privacy and security considerations
+- open questions that materially affect implementation
+```
+
+## Phase parameter
+
+Starting with GPT-5.4, long-running or tool-heavy Responses workflows can use assistant-item `phase` values to distinguish intermediate updates from final answers. GPT-5.5 uses the same pattern.
+
+If you use `previous_response_id`, the API preserves prior assistant state automatically. If your application manually replays assistant output items into the next request, preserve each original `phase` value and pass it back unchanged. This matters most when a response includes preambles, repeated tool calls, or a final answer after intermediate assistant updates.
+
+```text
+If manually replaying assistant items:
+- Preserve assistant `phase` values exactly.
+- Use `phase: "commentary"` for intermediate user-visible updates.
+- Use `phase: "final_answer"` for the completed answer.
+- Do not add `phase` to user messages.
+```
+
+## Suggested prompt structure
+
+Use this structure as a starting point for complex prompts. Keep each section short. Add detail only where it changes behavior.
+
+```text
+Role: [1-2 sentences defining the model's function, context, and job]
+
+# Personality
+[tone, demeanor, and collaboration style]
+
+# Goal
+[user-visible outcome]
+
+# Success criteria
+[what must be true before the final answer]
+
+# Constraints
+[policy, safety, business, evidence, and side-effect limits]
+
+# Output
+[sections, length, and tone]
+
+# Stop rules
+[when to retry, fallback, abstain, ask, or stop]
+```
diff --git a/skills/openai-docs/references/upgrade-guide.md b/skills/openai-docs/references/upgrade-guide.md
new file mode 100644
index 0000000..b29f137
--- /dev/null
+++ b/skills/openai-docs/references/upgrade-guide.md
@@ -0,0 +1,181 @@
+# Upgrading to GPT-5.5
+
+Use this guide when the user explicitly asks to upgrade an existing integration to GPT-5.5. Pair it with current OpenAI docs lookups. The default target string is `gpt-5.5`.
+
+## Freshness check
+
+Before applying this bundled guide for a latest/current/default model upgrade, run `node scripts/resolve-latest-model-info.js` from the OpenAI Docs skill directory.
+
+- If the command returns `modelSlug: "gpt-5p5"`, continue with this bundled guide and use `references/prompting-guide.md` when prompt updates are needed.
+- If the command returns a different `modelSlug`, fetch both the returned `migrationGuideUrl` and `promptingGuideUrl` and use them as the current source of truth instead of the bundled references.
+- If the command fails, metadata is missing, or either remote guide cannot be fetched, continue with bundled fallback references and say the remote freshness check was unavailable.
+- If the user explicitly named a target model, preserve that target and use current docs only to check compatibility or caveats.
+
+## Upgrade posture
+
+Upgrade with the narrowest safe change set:
+
+- replace the model string first
+- update only the prompts that are directly tied to that model usage
+- do not automatically upgrade older or ambiguous model usages that may be intentionally pinned, such as historical docs, examples, tests, eval baselines, comparison code, or low-cost fallback/routing paths. Unless the user explicitly asks to upgrade all model usage, leave those sites unchanged and list them as confirmation-needed
+- prefer prompt-only upgrades when possible
+- if the upgrade would require API-surface changes, parameter rewrites, tool rewiring, provider migration, or broader code edits, mark it as blocked instead of stretching the scope
+
+## Upgrade workflow
+
+1. Inventory current model usage.
+   - Search for model strings, client calls, and prompt-bearing files.
+   - Include inline prompts, prompt templates, YAML or JSON configs, Markdown docs, and saved prompts when they are clearly tied to a model usage site.
+2. Pair each model usage with its prompt surface.
+   - Prefer the closest prompt surface first: inline system or developer text, then adjacent prompt files, then shared templates.
+   - If you cannot confidently tie a prompt to the model usage, say so instead of guessing.
+3. Classify the source model family.
+   - Common buckets: GPT-5.4, GPT-5.3-Codex or GPT-5.2-Codex, earlier GPT-5.x, GPT-4o or GPT-4.1, reasoning models such as o1 or o3 or o4-mini, third-party model, or mixed and unclear.
+4. Decide the upgrade class.
+   - `model string only`
+   - `model string + light prompt rewrite`
+   - `blocked without code changes`
+5. Run the compatibility gate.
+   - Check whether the current integration can accept `gpt-5.5` without API-surface changes or implementation changes.
+   - Check whether structured outputs, tool schemas, function names, and downstream parsers can remain unchanged.
+   - For long-running Responses or tool-heavy agents, check whether `phase` is already preserved or round-tripped when the host replays assistant items or uses preambles.
+   - If compatibility depends on code changes, return `blocked`.
+   - If compatibility is unclear, return `unknown` rather than improvising.
+6. Apply the upgrade when it is in scope.
+   - Default replacement string: `gpt-5.5`.
+   - Keep the intervention small and behavior-preserving.
+   - Start from the current reasoning effort when it is visible unless there is a measured reason to change it.
+   - For in-scope changes, update the model string and directly related prompts.
+   - For blocked or unknown changes, do not edit; report the blocker or uncertainty.
+7. Summarize the result.
+   - `Current model usage`
+   - `Model-string updates`
+   - `Reasoning-effort handling`
+   - `Prompt updates`
+   - `Structured output and formatting assessment`
+   - `Tool-use assessment` when the flow uses tools, retrieval, or terminal actions
+   - `Phase assessment` when the flow is long-running, replayed, or tool-heavy
+   - `Compatibility check`
+   - `Validation performed`
+
+Output rule:
+
+- For each usage site, state the starting reasoning-effort recommendation.
+- If the repo exposes the current reasoning setting, recommend preserving it first unless current OpenAI docs say otherwise.
+- If the repo does not expose the current setting, recommend not adding one unless current OpenAI docs require it.
+
+## Upgrade outcomes
+
+### `model string only`
+
+Choose this when:
+
+- the source model is GPT-5.4
+- the existing prompts are already short, explicit, and task-bounded
+- the workflow does not rely on strict output formats, tool-call behavior, batch completeness, or long-horizon execution that should be validated after the upgrade
+- there are no obvious compatibility blockers
+
+Default action:
+
+- replace the model string with `gpt-5.5`
+- preserve the current reasoning effort
+- keep prompts unchanged
+- validate behavior with existing tests, realistic spot checks, or an existing eval suite when one is already available
+
+### `model string + light prompt rewrite`
+
+Choose this when:
+
+- the task needs stronger completeness, citation discipline, verification, or dependency handling
+- the upgraded model becomes too verbose, too dense, or hard to scan unless formatting is constrained
+- the workflow has strict output shape requirements and lacks an explicit format contract, schema, or parser validation
+- the workflow is research-heavy and needs stronger handling of sparse or empty retrieval results
+- the workflow is coding-oriented, terminal-based, tool-heavy, or multi-agent, but the existing API surface and tool definitions can remain unchanged
+
+Default action:
+
+- replace the model string with `gpt-5.5`
+- preserve the current reasoning effort for the first pass
+- make only the smallest prompt edits needed for the observed workflow risk
+- read the [GPT-5.5 prompting guide](/api/docs/guides/prompt-guidance?model=gpt-5.5) to choose the smallest prompt changes that recover or improve behavior
+- avoid broad prompt cleanup unrelated to the upgrade
+- for research workflows, add citation rules, retrieval budgets, missing-evidence behavior, and validation guidance from the prompting guide
+- for dependency-aware or tool-heavy workflows, add prerequisite checks, missing-context handling, explicit tool budgets, stop conditions, and validation guidance
+- for coding or terminal workflows, add repo-specific constraints, acceptance criteria, and concrete validation commands
+- for multi-agent support or triage workflows, add task ownership, handoff, completeness, and stopping criteria
+- for long-running Responses agents with preambles or multiple assistant messages, explicitly review whether `phase` is already handled; if adding or preserving `phase` would require code edits, mark the path as `blocked`
+- do not classify a coding or tool-using Responses workflow as `blocked` just because the visible snippet is minimal; prefer `model string + light prompt rewrite` unless the repo clearly shows that a safe GPT-5.5 path would require host-side code changes
+
+### `blocked`
+
+Choose this when:
+
+- the upgrade appears to require API-surface changes
+- the upgrade appears to require parameter rewrites or reasoning-setting changes that are not exposed outside implementation code
+- the upgrade would require changing tool definitions, tool handler wiring, or schema contracts
+- the user is asking for a tooling, IDE, plugin, shell, or environment migration rather than a model and prompt migration
+- the integration depends on provider-specific APIs that do not map to the current OpenAI API surface without implementation work
+- you cannot confidently identify the prompt surface tied to the model usage
+
+Default action:
+
+- do not improvise a broader upgrade
+- report the blocker and explain that the fix is out of scope for this guide
+- if useful, describe the smallest follow-up implementation task that would unblock the migration
+
+## Compatibility checklist
+
+Before applying or recommending a model-and-prompt-only upgrade, check:
+
+1. Can the current host accept the `gpt-5.5` model string without changing client code or API surface?
+2. Are the related prompts identifiable and editable?
+3. Does the host depend on behavior that likely needs API-surface changes, parameter rewrites, provider migration, or tool rewiring?
+4. Would the likely fix be prompt-only, or would it need implementation changes?
+5. Is the prompt surface close enough to the model usage that you can make a targeted change instead of a broad cleanup?
+6. Do strict structured outputs, schemas, or downstream parsers still have an explicit contract?
+7. For long-running Responses or tool-heavy agents, is `phase` already preserved if the host relies on preambles, replayed assistant items, or multiple assistant messages?
+8. Are latency, token, or price assumptions validated by tests, realistic spot checks, or an existing eval suite rather than inferred from general model positioning?
+
+If item 1 is no, items 3 through 4 point to implementation work, or item 7 is no and the fix needs code changes, return `blocked`.
+
+If item 2 is no, return `unknown` unless the user can point to the prompt location.
+
+Important:
+
+- Existing use of tools, agents, or multiple usage sites is not by itself a blocker.
+- If the current host can keep the same API surface and the same tool definitions, prefer `model string + light prompt rewrite` over `blocked`.
+- Reserve `blocked` for cases that truly require implementation changes, not cases that only need stronger prompt steering.
+- Do not claim token savings without task-level validation.
+
+## Scope boundaries
+
+This guide may:
+
+- update or recommend updated model strings
+- update or recommend updated prompts
+- inspect code and prompt files to understand where those changes belong
+- inspect whether existing Responses flows already preserve `phase`
+- flag compatibility blockers
+- propose validation with existing tests, realistic spot checks, or existing eval suites
+
+This guide may not:
+
+- move Chat Completions code to Responses
+- move Responses code to another API surface
+- migrate SDKs, APIs, IDE configuration, shell hooks, plugins, or provider-specific tooling
+- rewrite parameter shapes
+- change tool definitions or tool-call handling
+- change structured-output wiring
+- add or retrofit `phase` handling in implementation code
+- edit business logic, orchestration logic, SDK usage, IDE configuration, shell hooks, or plugin integration behavior except for model-string replacements and directly related prompt edits
+
+If a safe GPT-5.5 upgrade requires any of those changes, mark the path as blocked and out of scope.
+
+## Validation plan
+
+- Validate each upgraded usage site with existing tests, realistic spot checks, or an existing eval suite when one is already available.
+- Compare against the current GPT-5.4 baseline when available.
+- Check task success, retry count, tool-call count, total tokens, latency, output shape, and user-visible quality.
+- For specialized workflows, validate the contract that matters most instead of judging only general output quality.
+- If prompt edits were added, confirm each block is doing real work instead of adding noise.
+- If the workflow has downstream impact, add a lightweight verification pass before finalization.
diff --git a/skills/openai-docs/scripts/fetch-codex-manual.mjs b/skills/openai-docs/scripts/fetch-codex-manual.mjs
new file mode 100644
index 0000000..b260552
--- /dev/null
+++ b/skills/openai-docs/scripts/fetch-codex-manual.mjs
@@ -0,0 +1,598 @@
+#!/usr/bin/env node
+import {
+  access,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { inspect, promisify } from "node:util";
+
+const DEFAULT_MANUAL_URL = "https://developers.openai.com/codex/codex-manual.md";
+const DEFAULT_CACHE_DIR_NAME = "openai-docs-cache";
+const CACHE_FILE_NAME = "codex-manual.md";
+const OUTLINE_FILE_NAME = "codex-manual.outline.md";
+const HASH_HEADER = "x-content-sha256";
+const USER_AGENT = "codex-openai-docs";
+const execFileAsync = promisify(execFile);
+
+class ManualFetchError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ManualFetchError";
+  }
+}
+
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+
+const withTimeout = async (promiseFactory, timeoutMs) => {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await promiseFactory(controller.signal);
+  } finally {
+    clearTimeout(timeout);
+  }
+};
+
+const proxyConfigured = () =>
+  process.env.HTTP_PROXY ||
+  process.env.HTTPS_PROXY ||
+  process.env.http_proxy ||
+  process.env.https_proxy;
+
+const responseHeaders = (headers) => ({
+  get(name) {
+    return headers.get(name.toLowerCase()) ?? null;
+  },
+});
+
+const makeResponse = ({ body, headers, status }) => ({
+  headers: responseHeaders(headers),
+  ok: status >= 200 && status < 300,
+  status,
+  async text() {
+    return body;
+  },
+});
+
+const parseCurlHeaders = (rawHeaders) => {
+  const normalized = rawHeaders.replace(/\r\n/g, "\n").trim();
+  const blocks = normalized.split(/\n\n+/).filter(Boolean);
+  const headerBlock = [...blocks]
+    .reverse()
+    .find((block) => block.startsWith("HTTP/"));
+
+  if (!headerBlock) {
+    throw new ManualFetchError("curl did not return HTTP response headers.");
+  }
+
+  const [statusLine, ...lines] = headerBlock.split("\n");
+  const statusMatch = /^HTTP\/\S+\s+(\d{3})/.exec(statusLine);
+  if (!statusMatch) {
+    throw new ManualFetchError(
+      `Could not parse HTTP status from curl response: ${statusLine}`
+    );
+  }
+
+  const headers = new Map();
+  lines.forEach((line) => {
+    const separator = line.indexOf(":");
+    if (separator === -1) return;
+    const name = line.slice(0, separator).trim().toLowerCase();
+    const value = line.slice(separator + 1).trim();
+    headers.set(name, value);
+  });
+
+  return {
+    headers,
+    status: Number(statusMatch[1]),
+  };
+};
+
+const tempFilePath = (cacheDir, suffix) =>
+  path.join(
+    cacheDir,
+    `.fetch-codex-manual-${process.pid}-${Date.now()}-${Math.random()
+      .toString(16)
+      .slice(2)}${suffix}`
+  );
+
+const requestManualWithCurl = async (url, { cacheDir, method, timeoutMs }) => {
+  const headerPath = tempFilePath(cacheDir, ".headers");
+  const bodyPath = tempFilePath(cacheDir, ".body");
+  const curlNames =
+    process.platform === "win32" ? ["curl.exe", "curl"] : ["curl"];
+  const args = [
+    "--silent",
+    "--show-error",
+    "--location",
+    "--dump-header",
+    headerPath,
+    "--output",
+    bodyPath,
+    "--user-agent",
+    USER_AGENT,
+    "--max-time",
+    String(Math.max(1, Math.ceil(timeoutMs / 1000))),
+  ];
+
+  if (method === "HEAD") {
+    args.push("--head");
+  } else {
+    args.push("--request", method);
+  }
+  args.push(url);
+
+  let lastError;
+  for (const curlName of curlNames) {
+    try {
+      await execFileAsync(curlName, args, { windowsHide: true });
+      const [rawHeaders, body] = await Promise.all([
+        readFile(headerPath, "utf8"),
+        readFile(bodyPath, "utf8"),
+      ]);
+      const { headers, status } = parseCurlHeaders(rawHeaders);
+      return makeResponse({ body, headers, status });
+    } catch (error) {
+      lastError = error;
+      if (error?.code !== "ENOENT") break;
+    } finally {
+      await Promise.all([
+        rm(headerPath, { force: true }),
+        rm(bodyPath, { force: true }),
+      ]);
+    }
+  }
+
+  if (lastError?.code === "ENOENT") {
+    throw new ManualFetchError("curl is unavailable in this environment.", {
+      cause: lastError,
+    });
+  }
+  throw new ManualFetchError(`${method} ${url} could not be fetched.`, {
+    cause: lastError,
+  });
+};
+
+const requestManualWithFetch = async (url, { method, timeoutMs }) => {
+  if (typeof fetch !== "function") {
+    throw new ManualFetchError(
+      "Native fetch is unavailable in this Node runtime."
+    );
+  }
+
+  return withTimeout(
+    (signal) =>
+      fetch(url, {
+        method,
+        headers: { "User-Agent": USER_AGENT },
+        signal,
+      }),
+    timeoutMs
+  );
+};
+
+const requestManual = async (url, { cacheDir, method, timeoutMs }) => {
+  const preferCurl = Boolean(proxyConfigured()) || typeof fetch !== "function";
+  const transports = preferCurl
+    ? [
+        () => requestManualWithCurl(url, { cacheDir, method, timeoutMs }),
+        () => requestManualWithFetch(url, { method, timeoutMs }),
+      ]
+    : [
+        () => requestManualWithFetch(url, { method, timeoutMs }),
+        () => requestManualWithCurl(url, { cacheDir, method, timeoutMs }),
+      ];
+
+  let lastError;
+  for (const transport of transports) {
+    try {
+      const response = await transport();
+      if (!response.ok) {
+        throw new ManualFetchError(
+          `${method} ${url} failed with HTTP ${response.status}.`
+        );
+      }
+      return response;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  throw new ManualFetchError(`${method} ${url} could not be fetched.`, {
+    cause: lastError,
+  });
+};
+
+const readHeaderSha = (response) => {
+  const value = response.headers.get(HASH_HEADER);
+  if (!value || !/^[a-f0-9]{64}$/i.test(value)) {
+    throw new ManualFetchError(`Manual response is missing ${HASH_HEADER}.`);
+  }
+  return value.toLowerCase();
+};
+
+const nearestExistingParent = async (target) => {
+  let current = target;
+  while (true) {
+    try {
+      const info = await stat(current);
+      return info.isDirectory() ? current : null;
+    } catch (error) {
+      if (error?.code !== "ENOENT") return null;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+};
+
+const usableCacheDir = async (cacheDir) => {
+  if (!cacheDir) return null;
+  const resolved = path.resolve(cacheDir);
+
+  try {
+    const info = await stat(resolved);
+    if (!info.isDirectory()) return null;
+  } catch (error) {
+    if (error?.code !== "ENOENT") return null;
+  }
+
+  const parent = await nearestExistingParent(resolved);
+  if (!parent) return null;
+
+  try {
+    await access(parent, fsConstants.W_OK | fsConstants.X_OK);
+  } catch {
+    return null;
+  }
+
+  return resolved;
+};
+
+const defaultCacheDirCandidates = () => {
+  const candidates = [];
+  const seen = new Set();
+  const pushCandidate = (candidate) => {
+    if (!candidate || seen.has(candidate)) return;
+    seen.add(candidate);
+    candidates.push(candidate);
+  };
+
+  [process.env.TMPDIR, process.env.TEMP, process.env.TMP].forEach((baseDir) => {
+    if (baseDir) {
+      pushCandidate(path.join(baseDir, DEFAULT_CACHE_DIR_NAME));
+    }
+  });
+
+  if (process.platform !== "win32") {
+    pushCandidate(`/private/tmp/${DEFAULT_CACHE_DIR_NAME}`);
+    pushCandidate(`/tmp/${DEFAULT_CACHE_DIR_NAME}`);
+  }
+
+  return candidates;
+};
+
+const resolveCacheDir = async (cacheDir) => {
+  if (cacheDir) {
+    return usableCacheDir(cacheDir);
+  }
+
+  for (const candidate of defaultCacheDirCandidates()) {
+    const usable = await usableCacheDir(candidate);
+    if (usable) return usable;
+  }
+
+  return null;
+};
+
+const cacheFilePath = (cacheDir) => path.join(cacheDir, CACHE_FILE_NAME);
+
+const outlineFilePath = (cacheDir) => path.join(cacheDir, OUTLINE_FILE_NAME);
+
+const manualLines = (manual) => {
+  const lines = manual.replace(/\r\n/g, "\n").split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines;
+};
+
+const sectionTitle = (rawTitle) =>
+  rawTitle.replace(/\s+#+\s*$/, "").replace(/\s+/g, " ").trim();
+
+const buildOutline = (manual) => {
+  const lines = manualLines(manual);
+  const headings = [];
+  let inFence = false;
+
+  lines.forEach((line, index) => {
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      return;
+    }
+    if (inFence) return;
+
+    const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (!match) return;
+
+    const level = match[1].length;
+    if (level < 2 || level > 3) return;
+
+    headings.push({
+      level,
+      title: sectionTitle(match[2]),
+      startLine: index + 1,
+      endLine: lines.length,
+    });
+  });
+
+  for (let index = 0; index < headings.length; index += 1) {
+    const heading = headings[index];
+    const nextPeer = headings
+      .slice(index + 1)
+      .find((candidate) => candidate.level <= heading.level);
+    if (nextPeer) {
+      heading.endLine = nextPeer.startLine - 1;
+    }
+  }
+
+  if (headings.length === 0) {
+    return {
+      headingCount: 0,
+      lineCount: lines.length,
+      text: "No markdown headings found.",
+    };
+  }
+
+  const minLevel = Math.min(...headings.map((heading) => heading.level));
+  return {
+    headingCount: headings.length,
+    lineCount: lines.length,
+    text: headings
+      .map((heading) => {
+        const indent = "  ".repeat(heading.level - minLevel);
+        return `${indent}- ${heading.title} (lines ${heading.startLine}-${heading.endLine})`;
+      })
+      .join("\n"),
+  };
+};
+
+const outlineMarkdown = (outline) => `# Codex Manual Outline\n\n${outline.text}\n`;
+
+const manualStatusLine = (status) =>
+  status.cacheStatus === "hit"
+    ? "Manual status: local manual was already current."
+    : "Manual status: local manual was updated.";
+
+const formatResult = ({ status, outlineText }) =>
+  [
+    `Manual path: ${status.manualPath}`,
+    `Outline path: ${status.outlinePath}`,
+    manualStatusLine(status),
+    "",
+    outlineText,
+  ].join("\n");
+
+const readCachedManual = async (cacheDir, expectedSha256) => {
+  try {
+    const manual = await readFile(cacheFilePath(cacheDir), "utf8");
+    return sha256(manual) === expectedSha256 ? manual : null;
+  } catch {
+    return null;
+  }
+};
+
+const writeCachedManual = async (cacheDir, manual) => {
+  await mkdir(cacheDir, { recursive: true });
+  const tmpPath = tempFilePath(cacheDir, `.${CACHE_FILE_NAME}.tmp`);
+  await writeFile(tmpPath, manual, "utf8");
+  await rename(tmpPath, cacheFilePath(cacheDir));
+};
+
+const writeOutline = async (cacheDir, outlineText) => {
+  await mkdir(cacheDir, { recursive: true });
+  const tmpPath = tempFilePath(cacheDir, `.${OUTLINE_FILE_NAME}.tmp`);
+  await writeFile(tmpPath, outlineText, "utf8");
+  await rename(tmpPath, outlineFilePath(cacheDir));
+};
+
+const fetchCodexManual = async ({
+  manualUrl = DEFAULT_MANUAL_URL,
+  cacheDir,
+  timeoutMs = 30000,
+} = {}) => {
+  const resolvedCacheDir = await resolveCacheDir(cacheDir);
+  if (!resolvedCacheDir) {
+    throw new ManualFetchError(
+      "Manual cache directory is unavailable; pass --cache-dir to override or use OpenAI Docs MCP fallback."
+    );
+  }
+  await mkdir(resolvedCacheDir, { recursive: true });
+
+  const headResponse = await requestManual(manualUrl, {
+    cacheDir: resolvedCacheDir,
+    method: "HEAD",
+    timeoutMs,
+  });
+  const expectedSha256 = readHeaderSha(headResponse);
+  const manualPath = cacheFilePath(resolvedCacheDir);
+  const outlinePath = outlineFilePath(resolvedCacheDir);
+  const checkedAt = new Date().toISOString();
+
+  const cachedManual = await readCachedManual(resolvedCacheDir, expectedSha256);
+  if (cachedManual !== null) {
+    const outline = buildOutline(cachedManual);
+    const outlineText = outlineMarkdown(outline);
+    await writeOutline(resolvedCacheDir, outlineText);
+
+    return {
+      outlineText,
+      status: {
+        manualUrl,
+        headerSha256: expectedSha256,
+        fetchedManualSha256: expectedSha256,
+        manualHashMatches: true,
+        cacheStatus: "hit",
+        cacheDir: resolvedCacheDir,
+        manualPath,
+        outlinePath,
+        checkedAt,
+        lineCount: outline.lineCount,
+        headingCount: outline.headingCount,
+      },
+    };
+  }
+
+  const getResponse = await requestManual(manualUrl, {
+    cacheDir: resolvedCacheDir,
+    method: "GET",
+    timeoutMs,
+  });
+  const getHeaderSha256 = readHeaderSha(getResponse);
+  if (getHeaderSha256 !== expectedSha256) {
+    throw new ManualFetchError(
+      `${HASH_HEADER} changed between HEAD and GET for ${manualUrl}.`
+    );
+  }
+
+  const manualText = await getResponse.text();
+  const actualSha256 = sha256(manualText);
+  const manualHashMatches = actualSha256 === expectedSha256;
+  if (!manualHashMatches) {
+    throw new ManualFetchError(
+      `${HASH_HEADER} did not match the fetched manual body for ${manualUrl}.`
+    );
+  }
+
+  await writeCachedManual(resolvedCacheDir, manualText);
+  const outline = buildOutline(manualText);
+  const outlineText = outlineMarkdown(outline);
+  await writeOutline(resolvedCacheDir, outlineText);
+
+  return {
+    outlineText,
+    status: {
+      manualUrl,
+      headerSha256: expectedSha256,
+      fetchedManualSha256: actualSha256,
+      manualHashMatches,
+      cacheStatus: "updated",
+      cacheDir: resolvedCacheDir,
+      manualPath,
+      outlinePath,
+      checkedAt,
+      lineCount: outline.lineCount,
+      headingCount: outline.headingCount,
+    },
+  };
+};
+
+const parseArgs = (argv) => {
+  const args = {
+    manualUrl: DEFAULT_MANUAL_URL,
+    cacheDir: undefined,
+    timeoutMs: 30000,
+    statusJson: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--manual-url") {
+      args.manualUrl = argv[++index];
+    } else if (arg === "--cache-dir") {
+      args.cacheDir = argv[++index];
+    } else if (arg === "--timeout-ms") {
+      args.timeoutMs = Number(argv[++index]);
+    } else if (arg === "--status-json") {
+      args.statusJson = true;
+    } else {
+      throw new ManualFetchError(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!args.manualUrl) {
+    throw new ManualFetchError("--manual-url cannot be empty.");
+  }
+  if (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0) {
+    throw new ManualFetchError("--timeout-ms must be a positive number.");
+  }
+
+  return args;
+};
+
+const main = async () => {
+  const args = parseArgs(process.argv.slice(2));
+  const { outlineText, status } = await fetchCodexManual(args);
+
+  process.stdout.write(formatResult({ status, outlineText }));
+
+  if (args.statusJson) {
+    console.error(JSON.stringify(status));
+  }
+};
+
+const envProxyHint = () => {
+  if (proxyConfigured()) {
+    return "Hint: proxy env vars are present. This helper prefers `curl` in proxied sessions; if requests still fail, verify `curl` is installed and the proxy configuration is valid.";
+  }
+  if (typeof fetch !== "function") {
+    return "Hint: native fetch is unavailable in this Node runtime. Install `curl` or use a newer Node version to fetch the manual.";
+  }
+  if (process.platform === "win32") {
+    return "Hint: on Windows, pass a cache dir under `%TEMP%` or `%TMP%`.";
+  }
+  return null;
+};
+
+const formatErrorDetails = (error) => {
+  const details = inspect(error, {
+    breakLength: 120,
+    colors: false,
+    compact: false,
+    depth: 8,
+  });
+  if (!error?.cause) {
+    return details;
+  }
+
+  return `${details}\n\nCause:\n${inspect(error.cause, {
+    breakLength: 120,
+    colors: false,
+    compact: false,
+    depth: 8,
+  })}`;
+};
+
+const isCliEntrypoint = () => {
+  const entrypoint = process.argv[1];
+  if (!entrypoint) {
+    return false;
+  }
+
+  return pathToFileURL(entrypoint).href === import.meta.url;
+};
+
+if (isCliEntrypoint()) {
+  main().catch((error) => {
+    console.error(`Error: ${error.message}`);
+    const hint = envProxyHint();
+    if (hint) {
+      console.error(hint);
+    }
+    console.error("");
+    console.error("Details:");
+    console.error(formatErrorDetails(error));
+    process.exitCode = 1;
+  });
+}
+
+export { DEFAULT_MANUAL_URL, fetchCodexManual };
diff --git a/skills/openai-docs/scripts/resolve-latest-model-info.js b/skills/openai-docs/scripts/resolve-latest-model-info.js
new file mode 100644
index 0000000..1bd16ac
--- /dev/null
+++ b/skills/openai-docs/scripts/resolve-latest-model-info.js
@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+const DEFAULT_URL =
+  "https://developers.openai.com/api/docs/guides/latest-model.md";
+const DEFAULT_BASE_URL = "https://developers.openai.com";
+
+function parseArgs(argv) {
+  const args = {
+    source: process.env.LATEST_MODEL_URL || DEFAULT_URL,
+    baseUrl: process.env.LATEST_MODEL_BASE_URL || DEFAULT_BASE_URL,
+  };
+
+  for (let i = 2; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--source" || arg === "--url") {
+      args.source = argv[i + 1];
+      i += 1;
+    } else if (arg === "--base-url") {
+      args.baseUrl = argv[i + 1];
+      i += 1;
+    }
+  }
+
+  return args;
+}
+
+async function readSource(source) {
+  if (source.startsWith("file://")) {
+    return fs.readFile(new URL(source), "utf8");
+  }
+
+  if (!/^https?:\/\//.test(source)) {
+    return fs.readFile(path.resolve(source), "utf8");
+  }
+
+  const response = await fetch(source, {
+    headers: { accept: "text/markdown,text/plain,*/*" },
+  });
+
+  if (!response.ok) {
+    throw new Error(`failed to fetch ${source}: ${response.status}`);
+  }
+
+  return response.text();
+}
+
+function parseIndentedInfo(lines, startIndex) {
+  const info = {};
+
+  for (let i = startIndex + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line.trim()) {
+      continue;
+    }
+
+    const match = line.match(/^ {2}([A-Za-z][A-Za-z0-9_-]*):\s*(.+?)\s*$/);
+    if (!match) {
+      break;
+    }
+
+    info[match[1]] = match[2].replace(/^["']|["']$/g, "");
+  }
+
+  return info;
+}
+
+function parseFlatInfo(block) {
+  const info = {};
+
+  for (const line of block.split(/\r?\n/)) {
+    const match = line.match(/^\s*([A-Za-z][A-Za-z0-9_-]*):\s*(.+?)\s*$/);
+    if (match) {
+      info[match[1]] = match[2].replace(/^["']|["']$/g, "");
+    }
+  }
+
+  return info;
+}
+
+function extractLatestModelInfo(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  const latestModelInfoIndex = lines.findIndex((line) =>
+    /^latestModelInfo:\s*$/.test(line)
+  );
+
+  if (latestModelInfoIndex >= 0) {
+    return parseIndentedInfo(lines, latestModelInfoIndex);
+  }
+
+  const commentMatch = markdown.match(
+    /<!--\s*latestModelInfo\s*\n([\s\S]*?)\n\s*-->/m
+  );
+  if (commentMatch) {
+    return parseFlatInfo(commentMatch[1]);
+  }
+
+  return undefined;
+}
+
+function modelToSkillSlug(model) {
+  return model.trim().replace(/\./g, "p");
+}
+
+function absoluteUrl(baseUrl, value) {
+  return new URL(value, baseUrl).toString();
+}
+
+function normalizeInfo(info, baseUrl) {
+  const model = info?.model?.trim();
+  const migrationGuide = info?.migrationGuide?.trim();
+  const promptingGuide = info?.promptingGuide?.trim();
+
+  if (!model || !migrationGuide || !promptingGuide) {
+    throw new Error(
+      "latestModelInfo must include model, migrationGuide, and promptingGuide"
+    );
+  }
+
+  return {
+    model,
+    modelSlug: modelToSkillSlug(model),
+    migrationGuideUrl: absoluteUrl(baseUrl, migrationGuide),
+    promptingGuideUrl: absoluteUrl(baseUrl, promptingGuide),
+  };
+}
+
+async function main() {
+  const { source, baseUrl } = parseArgs(process.argv);
+  const markdown = await readSource(source);
+  const info = extractLatestModelInfo(markdown);
+
+  if (!info) {
+    throw new Error(`latestModelInfo block not found in ${source}`);
+  }
+
+  process.stdout.write(
+    `${JSON.stringify(normalizeInfo(info, baseUrl), null, 2)}\n`
+  );
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});
diff --git a/skills/plugin-creator/SKILL.md b/skills/plugin-creator/SKILL.md
new file mode 100644
index 0000000..af960ec
--- /dev/null
+++ b/skills/plugin-creator/SKILL.md
@@ -0,0 +1,243 @@
+---
+name: plugin-creator
+description: Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.
+---
+
+# Plugin Creator
+
+## Quick Start
+
+1. Run the scaffold script:
+
+```bash
+# Plugin names are normalized to lower-case hyphen-case and must be <= 64 chars.
+# The generated folder and plugin.json name are always the same.
+# Run from the skill root (the directory containing this `SKILL.md`).
+# By default creates in `~/plugins/<plugin-name>`.
+python3 scripts/create_basic_plugin.py <plugin-name>
+```
+
+2. Edit `<plugin-path>/.codex-plugin/plugin.json` when the request gives specific metadata.
+   The scaffold starts with valid defaults and must not contain `[TODO: ...]` placeholders.
+
+3. Generate or update the personal marketplace entry when the plugin should appear in Codex UI ordering:
+
+```bash
+# Personal marketplace entries default to `~/.agents/plugins/marketplace.json`.
+python3 scripts/create_basic_plugin.py my-plugin --with-marketplace
+```
+
+Only specify `--marketplace-name <name>` when the default `personal` marketplace name is already
+taken or installed and you need to seed a different new marketplace file:
+
+```bash
+python3 scripts/create_basic_plugin.py my-plugin \
+  --with-marketplace \
+  --marketplace-name team-local
+```
+
+Only use a repo/team marketplace when the user specifically asks for that destination:
+
+```bash
+python3 scripts/create_basic_plugin.py my-plugin \
+  --path <repo-root>/plugins \
+  --marketplace-path <repo-root>/.agents/plugins/marketplace.json \
+  --with-marketplace
+```
+
+When the user specifies a marketplace path, make sure that marketplace is actually installed before
+telling the user to reinstall from it. The default personal marketplace file at
+`~/.agents/plugins/marketplace.json` is discovered implicitly, but other marketplace paths are not.
+On Windows, use the equivalent path under the user profile.
+
+4. Generate/adjust optional companion folders as needed:
+
+```bash
+python3 scripts/create_basic_plugin.py my-plugin \
+  --path <parent-plugin-directory> \
+  --marketplace-path <marketplace-json-path> \
+  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace
+```
+
+`<parent-plugin-directory>` is the directory where the plugin folder `<plugin-name>` will be
+created (for example `~/plugins`).
+
+5. Before handing back a generated plugin, run:
+
+```bash
+python3 scripts/validate_plugin.py <plugin-path>
+```
+
+For updates to an existing local plugin during development, keep the scaffold flow as-is and use the
+reference instead of hand-editing marketplace files:
+
+```bash
+python3 scripts/update_plugin_cachebuster.py <plugin-path>
+```
+
+Prefer the helper default cachebuster unless the user explicitly asks for a specific override.
+See `references/installing-and-updating.md` for the expected cachebuster and reinstall flow while iterating on an existing local plugin.
+
+## What this skill creates
+
+- Default marketplace-backed scaffolds use the personal marketplace file at
+  `~/.agents/plugins/marketplace.json`, with plugins generally being stored in
+  `~/plugins/<plugin-name>/`.
+- Creates plugin root at `/<parent-plugin-directory>/<plugin-name>/`.
+- Always creates `/<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json`.
+- Fills the manifest with the validated schema shape that the ingestion path accepts.
+- Creates or updates `~/.agents/plugins/marketplace.json` when `--with-marketplace` is set.
+  - If the marketplace file does not exist yet, seed a personal marketplace root before adding the first plugin entry.
+- `<plugin-name>` is normalized using skill-creator naming rules:
+  - `My Plugin` → `my-plugin`
+  - `My--Plugin` → `my-plugin`
+  - underscores, spaces, and punctuation are converted to `-`
+  - result is lower-case hyphen-delimited with consecutive hyphens collapsed
+- Supports optional creation of:
+  - `skills/`
+  - `hooks/`
+  - `scripts/`
+  - `assets/`
+  - `.mcp.json`
+  - `.app.json`
+
+## Marketplace workflow
+
+- Personal-marketplace creation defaults to `~/.agents/plugins/marketplace.json`. Here,
+  "personal marketplace" means the marketplace whose file is at that path.
+- Repo/team marketplace creation is opt-in through both `--path` and `--marketplace-path`, only
+  when the user specifically requests it.
+- `--marketplace-name` is an exception path. Use it only when the default `personal` marketplace
+  name is already taken and you need to seed a different new marketplace file.
+- Do not use `--marketplace-name` to rename an existing marketplace file in place. If the file
+  already exists, its top-level `name` must already match.
+- If the user specifies a different marketplace path, treat that marketplace as needing explicit installation via `codex plugin marketplace add`.
+- Prefer `scripts/read_marketplace_name.py` when you need the marketplace name from any
+  `marketplace.json` file. With no argument it reads the default personal marketplace; with an
+  explicit path it works for repo/team marketplaces too.
+- In either location, the generated source path remains `./plugins/<plugin-name>`.
+- Marketplace root metadata supports top-level `name` plus optional `interface.displayName`.
+- Treat plugin order in `plugins[]` as render order in Codex. Append new entries unless a user explicitly asks to reorder the list.
+- `displayName` belongs inside the marketplace `interface` object, not individual `plugins[]` entries.
+- Each generated marketplace entry must include all of:
+  - `policy.installation`
+  - `policy.authentication`
+  - `category`
+- Default new entries to:
+  - `policy.installation: "AVAILABLE"`
+  - `policy.authentication: "ON_INSTALL"`
+- Override defaults only when the user explicitly specifies another allowed value.
+- Allowed `policy.installation` values:
+  - `NOT_AVAILABLE`
+  - `AVAILABLE`
+  - `INSTALLED_BY_DEFAULT`
+- Allowed `policy.authentication` values:
+  - `ON_INSTALL`
+  - `ON_USE`
+- Treat `policy.products` as an override. Omit it unless the user explicitly requests product gating.
+- The generated plugin entry shape is:
+
+```json
+{
+  "name": "plugin-name",
+  "source": {
+    "source": "local",
+    "path": "./plugins/plugin-name"
+  },
+  "policy": {
+    "installation": "AVAILABLE",
+    "authentication": "ON_INSTALL"
+  },
+  "category": "Productivity"
+}
+```
+
+- Use `--force` only when intentionally replacing an existing marketplace entry for the same plugin name.
+- If the target marketplace file does not exist yet, create it with top-level `"name"`, an `"interface"` object containing `"displayName"`, and a `plugins` array, then add the new entry.
+
+- For a brand-new marketplace file, the root object should look like:
+
+```json
+{
+  "name": "personal",
+  "interface": {
+    "displayName": "Personal"
+  },
+  "plugins": [
+    {
+      "name": "plugin-name",
+      "source": {
+        "source": "local",
+        "path": "./plugins/plugin-name"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+```
+
+## Required behavior
+
+- Outer folder name and `plugin.json` `"name"` are always the same normalized plugin name.
+- Do not remove required structure; keep `.codex-plugin/plugin.json` present.
+- Do not leave `[TODO: ...]` placeholders in plugin manifests.
+- Keep `apps` and `mcpServers` out of `plugin.json` unless their companion files are actually created.
+- Omit unsupported plugin manifest fields that validation rejects, including `hooks`.
+- If creating files inside an existing plugin path, use `--force` only when overwrite is intentional.
+- Preserve any existing marketplace `interface.displayName`.
+- When generating marketplace entries, always write `policy.installation`, `policy.authentication`, and `category` even if their values are defaults.
+- Add `policy.products` only when the user explicitly asks for that override.
+- Keep marketplace `source.path` relative to the selected marketplace root as `./plugins/<plugin-name>`.
+- Only use `--marketplace-name` when creating a new marketplace file whose name should not be
+  `personal` because that name is already taken or installed elsewhere.
+- If Codex would need approval to write the marketplace file, ask for that approval before
+  proceeding. If the user prefers to run the write themselves, provide the exact scaffold command
+  and then continue from validation or subsequent plugin edits instead of leaving the workflow
+  vague.
+- For updates to an existing local plugin during development, do not hand-edit marketplace config
+  or `marketplace.json`. Use the update flow documented in
+  `references/installing-and-updating.md` and `scripts/update_plugin_cachebuster.py`.
+- Do not tell the user to run `codex plugin marketplace add` for the default personal-marketplace
+  flow. That command is for explicit non-default marketplace configuration, not for the standard
+  `~/.agents/plugins/marketplace.json` path.
+- If the user provided a non-default `--marketplace-path`, make sure that marketplace is installed
+  before giving reinstall instructions. Use `codex plugin marketplace add <path-to-marketplace-root>`
+  when that explicit marketplace has not been configured yet.
+- When the workflow created or updated a marketplace-backed plugin, end the final user-facing
+  response with a short Codex app handoff. Say `To view this in the Codex app:` and write
+  `View <normalized plugin name>` and `Share <normalized plugin name>` as Markdown links, not raw
+  URLs or code spans.
+- The View deeplink uses `codex://plugins/<normalized plugin name>?marketplacePath=<absolute marketplace.json path>`.
+  The Share deeplink uses the same URL with `&mode=share`.
+- Replace the placeholders with the real normalized plugin name and absolute `marketplace.json`
+  path from the scaffolded plugin. URL-encode the path segment and query value when needed.
+- Do not add `pluginName` or `hostId` query parameters to these deeplinks. Codex derives both after
+  the user clicks the link.
+- Do not emit the `View <normalized plugin name>` or `Share <normalized plugin name>` links when no marketplace entry was
+  created or updated.
+
+## Reference to exact spec sample
+
+For the exact canonical sample JSON for both plugin manifests and marketplace entries, use:
+
+- `references/plugin-json-spec.md`
+- `references/installing-and-updating.md` for update/reinstall guidance while
+  iterating on an existing local plugin, plus the new-thread pickup behavior after reinstall
+
+## Validation
+
+After editing `SKILL.md`, run:
+
+```bash
+python3 ../skill-creator/scripts/quick_validate.py .
+```
+
+Before handing back a generated plugin, run:
+
+```bash
+python3 scripts/validate_plugin.py <plugin-path>
+```
diff --git a/skills/plugin-creator/agents/openai.yaml b/skills/plugin-creator/agents/openai.yaml
new file mode 100644
index 0000000..19a9a6f
--- /dev/null
+++ b/skills/plugin-creator/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Plugin Creator"
+  short_description: "Scaffold plugins and marketplace entries"
+  default_prompt: "Use $plugin-creator to scaffold a valid plugin in the personal marketplace, then validate it before handing it back."
+  icon_small: "./assets/plugin-creator-small.svg"
+  icon_large: "./assets/plugin-creator.png"
diff --git a/skills/plugin-creator/assets/plugin-creator-small.svg b/skills/plugin-creator/assets/plugin-creator-small.svg
new file mode 100644
index 0000000..c6e4f67
--- /dev/null
+++ b/skills/plugin-creator/assets/plugin-creator-small.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 20 20">
+  <path fill="#0D0D0D" d="M12.03 4.113a3.612 3.612 0 0 1 5.108 5.108l-6.292 6.29c-.324.324-.56.561-.791.752l-.235.176c-.205.14-.422.261-.65.36l-.229.093a4.136 4.136 0 0 1-.586.16l-.764.134-2.394.4c-.142.024-.294.05-.423.06-.098.007-.232.01-.378-.026l-.149-.05a1.081 1.081 0 0 1-.521-.474l-.046-.093a1.104 1.104 0 0 1-.075-.527c.01-.129.035-.28.06-.422l.398-2.394c.1-.602.162-.987.295-1.35l.093-.23c.1-.228.22-.445.36-.65l.176-.235c.19-.232.428-.467.751-.79l6.292-6.292Zm-5.35 7.232c-.35.35-.534.535-.66.688l-.11.147a2.67 2.67 0 0 0-.24.433l-.062.154c-.08.22-.124.462-.232 1.112l-.398 2.394-.001.001h.003l2.393-.399.717-.126a2.63 2.63 0 0 0 .394-.105l.154-.063a2.65 2.65 0 0 0 .433-.24l.147-.11c.153-.126.339-.31.688-.66l4.988-4.988-3.227-3.226-4.987 4.988Zm9.517-6.291a2.281 2.281 0 0 0-3.225 0l-.364.362 3.226 3.227.363-.364c.89-.89.89-2.334 0-3.225ZM4.583 1.783a.3.3 0 0 1 .294.241c.117.585.347 1.092.707 1.48.357.385.859.668 1.549.783a.3.3 0 0 1 0 .592c-.69.115-1.192.398-1.549.783-.315.34-.53.77-.657 1.265l-.05.215a.3.3 0 0 1-.588 0c-.117-.585-.347-1.092-.707-1.48-.357-.384-.859-.668-1.549-.783a.3.3 0 0 1 0-.592c.69-.115 1.192-.398 1.549-.783.36-.388.59-.895.707-1.48l.015-.05a.3.3 0 0 1 .279-.19Z"/>
+</svg>
diff --git a/skills/plugin-creator/assets/plugin-creator.png b/skills/plugin-creator/assets/plugin-creator.png
new file mode 100644
index 0000000..4f3d6d8
Binary files /dev/null and b/skills/plugin-creator/assets/plugin-creator.png differ
diff --git a/skills/plugin-creator/references/installing-and-updating.md b/skills/plugin-creator/references/installing-and-updating.md
new file mode 100644
index 0000000..28b3b88
--- /dev/null
+++ b/skills/plugin-creator/references/installing-and-updating.md
@@ -0,0 +1,143 @@
+# Updating Existing Local Plugins
+
+Use this reference when a plugin already exists and the request is about updating the plugin during 
+local development.
+
+All scripts here are specified relative to the skill root. Update the path for running the scripts
+depending on your current working directory.
+
+## When To Use This Flow
+
+Use this flow when all of the following are true:
+
+- the plugin already exists locally
+- the marketplace entry already points at the plugin source you are editing
+- the user wants Codex to see the updated plugin without manually editing marketplace files
+
+If the user still needs the initial plugin entry or marketplace structure created, use the scaffold
+flow first and only then switch to this reinstall flow.
+
+## Update Loop
+
+1. Update the plugin manifest to a single Codex cachebuster suffix:
+
+```bash
+python3 scripts/update_plugin_cachebuster.py \
+  <plugin-path>
+```
+
+Prefer the default helper behavior here. If you omit `--cachebuster`, the helper uses a UTC
+timestamp down to seconds, which is the recommended path for routine local iteration.
+
+Only use a manual cachebuster override when the user explicitly asks for one or when a workflow
+outside Codex depends on a specific token:
+
+```bash
+python3 scripts/update_plugin_cachebuster.py \
+  <plugin-path> \
+  --cachebuster local-20260519-184516
+```
+
+2. For the default scaffolded flow, read the marketplace name from the personal marketplace file:
+
+```bash
+python3 scripts/read_marketplace_name.py
+```
+
+Here, "personal marketplace" means the marketplace whose file is at
+`~/.agents/plugins/marketplace.json`. On Windows, use the equivalent path under the user profile.
+The helper uses Python's home-directory resolution and prints the marketplace name to use when
+constructing the install command.
+
+To read the name from a different marketplace file, pass the path directly:
+
+```bash
+python3 scripts/read_marketplace_name.py --marketplace-path <path-to-marketplace.json>
+```
+
+3. Reinstall from that marketplace name:
+
+```bash
+codex plugin add <plugin-name>@<marketplace-name-from-marketplace-json>
+```
+
+The default personal marketplace is discovered implicitly from
+`~/.agents/plugins/marketplace.json`. You do not need `codex plugin marketplace add` for that
+path, and `codex plugin marketplace list` is not the right check for whether that default
+marketplace exists.
+
+4. If the plugin is not using the personal marketplace file, check which configured local
+   marketplace is actually surfacing that plugin:
+
+```bash
+codex plugin list
+```
+
+If the plugin is not in the personal marketplace file, confirm which marketplace entry points at
+the plugin source you are editing and make sure that marketplace is still local. If it is a
+different local marketplace, reinstall from that marketplace name instead of forcing the personal
+marketplace flow. If it is not local, stop and help the user resolve the mismatch before
+continuing.
+
+5. If the plugin lives in a different confirmed local marketplace, substitute that marketplace
+   name:
+
+```bash
+codex plugin add <plugin-name>@<local-marketplace>
+```
+
+6. Prompt the user to use a new thread to try the updated plugin, so that Codex picks up new skills
+   and tools.
+
+## Cachebuster Policy
+
+- Preserve the existing version prefix and replace only the suffix.
+- Treat the preserved prefix as everything before `+`.
+- Use the format:
+
+```text
+<base-version>+codex.<cachebuster>
+```
+
+Examples:
+
+- `0.1.0` → `0.1.0+codex.local-20260519-184516`
+- `0.1.0+codex.old-token` → `0.1.0+codex.local-20260519-184516`
+- `1.2.3-beta.1+codex.prev` → `1.2.3-beta.1+codex.local-20260519-184516`
+- `dev-build+other-tag` → `dev-build+codex.local-20260519-184516`
+
+Replace the existing Codex cachebuster instead of appending another one. Do not keep incrementing
+numeric version components just to trigger reinstall behavior.
+
+## Marketplace Rules
+
+- Marketplace manipulation should happen through commands, not by hand-editing `marketplace.json`
+  or `config.toml` during this update/reinstall flow.
+- Prefer the personal marketplace file for the default scaffolded flow.
+- Read the personal marketplace name with
+  `python3 scripts/read_marketplace_name.py` and use the printed value when constructing
+  `codex plugin add <plugin-name>@<marketplace-name>`.
+- For non-default marketplace files, use
+  `python3 scripts/read_marketplace_name.py --marketplace-path <path-to-marketplace.json>` to read
+  the name before constructing reinstall commands.
+- Do not tell the user to run `codex plugin marketplace add` for the default personal-marketplace
+  flow. That marketplace is discovered implicitly by Codex.
+- If the user specified a different marketplace path, make sure that marketplace is installed
+  before giving install or reinstall instructions. Non-default marketplace paths are not
+  discovered implicitly.
+- Use `codex plugin list` when the plugin lives in a different configured marketplace and you need
+  to confirm which marketplace is surfacing that plugin.
+- If a non-default local marketplace has not been configured yet, install it with
+  `codex plugin marketplace add <path-to-marketplace-root>` before telling the user to run
+  `codex plugin add <plugin-name>@<marketplace-name>`.
+- If the plugin is not in the personal marketplace file, confirm that the selected marketplace is
+  local before telling the user to reinstall from it.
+- If the selected marketplace is not local, stop and help the user resolve that mismatch rather
+  than pretending the normal local reinstall flow applies.
+- If the plugin source is not already the source referenced by the chosen marketplace entry, stop
+  and fix that first. This update flow does not rewrite marketplace entries.
+
+## After Reinstall
+
+After reinstalling, prompt the user to start a new thread for testing. That is the safe boundary for
+picking up the updated plugin and its MCP tools.
diff --git a/skills/plugin-creator/references/plugin-json-spec.md b/skills/plugin-creator/references/plugin-json-spec.md
new file mode 100644
index 0000000..5eb2251
--- /dev/null
+++ b/skills/plugin-creator/references/plugin-json-spec.md
@@ -0,0 +1,194 @@
+# Plugin JSON sample spec
+
+```json
+{
+  "name": "plugin-name",
+  "version": "1.2.0",
+  "description": "Brief plugin description",
+  "author": {
+    "name": "Author Name",
+    "email": "author@example.com",
+    "url": "https://github.com/author"
+  },
+  "homepage": "https://docs.example.com/plugin",
+  "repository": "https://github.com/author/plugin",
+  "license": "MIT",
+  "keywords": ["keyword1", "keyword2"],
+  "skills": "./skills/",
+  "hooks": "./hooks.json",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "Plugin Display Name",
+    "shortDescription": "Short description for subtitle",
+    "longDescription": "Long description for details page",
+    "developerName": "OpenAI",
+    "category": "Productivity",
+    "capabilities": ["Interactive", "Write"],
+    "websiteURL": "https://openai.com/",
+    "privacyPolicyURL": "https://openai.com/policies/row-privacy-policy/",
+    "termsOfServiceURL": "https://openai.com/policies/row-terms-of-use/",
+    "defaultPrompt": [
+      "Summarize my inbox and draft replies for me.",
+      "Find open bugs and turn them into Linear tickets.",
+      "Review today's meetings and flag scheduling gaps."
+    ],
+    "brandColor": "#3B82F6",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/logo.png",
+    "screenshots": [
+      "./assets/screenshot1.png",
+      "./assets/screenshot2.png",
+      "./assets/screenshot3.png"
+    ]
+  }
+}
+```
+
+## Field guide
+
+### Top-level fields
+
+- `name` (`string`): Plugin identifier (kebab-case, no spaces). Required if `plugin.json` is provided and used as manifest name and component namespace.
+- `version` (`string`): Plugin semantic version.
+- `description` (`string`): Short purpose summary.
+- `author` (`object`): Publisher identity.
+  - `name` (`string`): Author or team name.
+  - `email` (`string`): Contact email.
+  - `url` (`string`): Author/team homepage or profile URL.
+- `homepage` (`string`): Documentation URL for plugin usage.
+- `repository` (`string`): Source code URL.
+- `license` (`string`): License identifier (for example `MIT`, `Apache-2.0`).
+- `keywords` (`array` of `string`): Search/discovery tags.
+- `skills` (`string`): Relative path to skill directories/files.
+- `hooks` (`string`): Hook config path.
+- `mcpServers` (`string`): MCP config path.
+- `apps` (`string`): App manifest path for plugin integrations.
+- `interface` (`object`): Interface/UX metadata block for plugin presentation.
+
+### `interface` fields
+
+- `displayName` (`string`): User-facing title shown for the plugin.
+- `shortDescription` (`string`): Brief subtitle used in compact views.
+- `longDescription` (`string`): Longer description used on details screens.
+- `developerName` (`string`): Human-readable publisher name.
+- `category` (`string`): Plugin category bucket.
+- `capabilities` (`array` of `string`): Capability list from implementation.
+- `websiteURL` (`string`): Public website for the plugin.
+- `privacyPolicyURL` (`string`): Privacy policy URL.
+- `termsOfServiceURL` (`string`): Terms of service URL.
+- `defaultPrompt` (`array` of `string`): Starter prompts shown in composer/UX context.
+  - Include at most 3 strings. Entries after the first 3 are ignored and will not be included.
+  - Each string is capped at 128 characters. Longer entries are truncated.
+  - Prefer short starter prompts around 50 characters so they scan well in the UI.
+- `brandColor` (`string`): Theme color for the plugin card.
+- `composerIcon` (`string`): Path to icon asset.
+- `logo` (`string`): Path to logo asset.
+- `screenshots` (`array` of `string`): List of screenshot asset paths.
+  - Screenshot entries must be PNG filenames and stored under `./assets/`.
+  - Keep file paths relative to plugin root.
+
+### Path conventions and defaults
+
+- Path values should be relative and begin with `./`.
+- `skills`, `hooks`, and `mcpServers` are supplemented on top of default component discovery; they do not replace defaults.
+- Custom path values must follow the plugin root convention and naming/namespacing rules.
+- This repo’s scaffold writes `.codex-plugin/plugin.json`; treat that as the manifest location this skill generates.
+
+# Marketplace JSON sample spec
+
+`marketplace.json` depends on where the plugin should live. New plugin creation defaults to the
+personal marketplace unless the caller explicitly requests a repo-local destination:
+
+- Personal plugin: `~/.agents/plugins/marketplace.json`
+- Repo/team plugin: `<repo-root>/.agents/plugins/marketplace.json`
+
+```json
+{
+  "name": "openai-curated",
+  "interface": {
+    "displayName": "ChatGPT Official"
+  },
+  "plugins": [
+    {
+      "name": "linear",
+      "source": {
+        "source": "local",
+        "path": "./plugins/linear"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+```
+
+## Marketplace field guide
+
+### Top-level fields
+
+- `name` (`string`): Marketplace identifier or catalog name.
+- `interface` (`object`, optional): Marketplace presentation metadata.
+- `plugins` (`array`): Ordered plugin entries. This order determines how Codex renders plugins.
+
+### `interface` fields
+
+- `displayName` (`string`, optional): User-facing marketplace title.
+
+### Plugin entry fields
+
+- `name` (`string`): Plugin identifier. Match the plugin folder name and `plugin.json` `name`.
+- `source` (`object`): Plugin source descriptor.
+  - `source` (`string`): Use `local` for this repo workflow.
+  - `path` (`string`): Relative plugin path based on the marketplace root.
+    - Personal plugin in `~/.agents/plugins/marketplace.json`: `./plugins/<plugin-name>`
+    - Repo/team plugin: `./plugins/<plugin-name>`
+  - The same relative path convention is used for both personal and repo/team marketplaces.
+    - Example: with `~/.agents/plugins/marketplace.json`, `./plugins/<plugin-name>` resolves to
+      `~/plugins/<plugin-name>`.
+- `policy` (`object`): Marketplace policy block. Always include it.
+  - `installation` (`string`): Availability policy.
+    - Allowed values: `NOT_AVAILABLE`, `AVAILABLE`, `INSTALLED_BY_DEFAULT`
+    - Default for new entries: `AVAILABLE`
+  - `authentication` (`string`): Authentication timing policy.
+    - Allowed values: `ON_INSTALL`, `ON_USE`
+    - Default for new entries: `ON_INSTALL`
+  - `products` (`array` of `string`, optional): Product override for this plugin entry. Omit it unless product gating is explicitly requested.
+- `category` (`string`): Display category bucket. Always include it.
+
+### Marketplace generation rules
+
+- `displayName` belongs under the top-level `interface` object, not individual plugin entries.
+- When creating a new marketplace file from scratch, seed `interface.displayName` alongside top-level `name`.
+- Always include `policy.installation`, `policy.authentication`, and `category` on every generated or updated plugin entry.
+- Treat `policy.products` as an override and omit it unless explicitly requested.
+- Append new entries unless the user explicitly requests reordering.
+- Replace an existing entry for the same plugin only when overwrite is intentional.
+- Default new plugin creation to the personal marketplace.
+- Use a repo/team marketplace only when the user specifically requests that destination.
+- Only override the marketplace `name` when the default `personal` name is already taken or
+  installed and you need to seed a different new marketplace file.
+- Choose marketplace location to match the selected destination:
+  - Personal plugin: `~/.agents/plugins/marketplace.json`
+  - Repo/team plugin: `<repo-root>/.agents/plugins/marketplace.json`
+
+### Plugin validation notes
+
+- The validator mirrors the workspace plugin ingestion schema so generated plugins follow the same
+  manifest contract from the start.
+- Plugin manifests must include real values for `name`, `version`, `description`,
+  `author.name`, and the required `interface` fields.
+- `version` must use strict semver.
+- `websiteURL`, `privacyPolicyURL`, and `termsOfServiceURL` must be absolute `https://` URLs when
+  present.
+- `composerIcon`, `logo`, and `screenshots` must point to real files inside the plugin archive when
+  present.
+- `apps` and `mcpServers` should appear in `plugin.json` only when `.app.json` and `.mcp.json`
+  actually exist.
+- Validation rejects unsupported manifest fields such as `hooks`, so the scaffold keeps them out of
+  generated manifests.
+- Run `scripts/validate_plugin.py <plugin-path>` before handing back a generated plugin. It adds one
+  intentional preflight check that rejects leftover `[TODO: ...]` placeholders.
diff --git a/skills/plugin-creator/scripts/create_basic_plugin.py b/skills/plugin-creator/scripts/create_basic_plugin.py
new file mode 100644
index 0000000..78b9fca
--- /dev/null
+++ b/skills/plugin-creator/scripts/create_basic_plugin.py
@@ -0,0 +1,324 @@
+#!/usr/bin/env python3
+"""Scaffold a plugin directory and optionally update marketplace.json."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+MAX_PLUGIN_NAME_LENGTH = 64
+DEFAULT_INSTALL_POLICY = "AVAILABLE"
+DEFAULT_AUTH_POLICY = "ON_INSTALL"
+DEFAULT_CATEGORY = "Productivity"
+DEFAULT_MARKETPLACE_NAME = "personal"
+VALID_INSTALL_POLICIES = {"NOT_AVAILABLE", "AVAILABLE", "INSTALLED_BY_DEFAULT"}
+VALID_AUTH_POLICIES = {"ON_INSTALL", "ON_USE"}
+DEFAULT_PLUGIN_PARENT = Path.home() / "plugins"
+DEFAULT_MARKETPLACE_PATH = Path.home() / ".agents" / "plugins" / "marketplace.json"
+
+
+def normalize_plugin_name(plugin_name: str) -> str:
+    """Normalize a plugin name to lowercase hyphen-case."""
+    normalized = plugin_name.strip().lower()
+    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
+    normalized = normalized.strip("-")
+    normalized = re.sub(r"-{2,}", "-", normalized)
+    return normalized
+
+
+def validate_plugin_name(plugin_name: str) -> None:
+    if not plugin_name:
+        raise ValueError("Plugin name must include at least one letter or digit.")
+    if len(plugin_name) > MAX_PLUGIN_NAME_LENGTH:
+        raise ValueError(
+            f"Plugin name '{plugin_name}' is too long ({len(plugin_name)} characters). "
+            f"Maximum is {MAX_PLUGIN_NAME_LENGTH} characters."
+        )
+
+
+def validate_marketplace_name(marketplace_name: str) -> None:
+    if not marketplace_name:
+        raise ValueError("Marketplace name must include at least one letter or digit.")
+    if re.fullmatch(r"[A-Za-z0-9_-]+", marketplace_name) is None:
+        raise ValueError(
+            "Marketplace name may only contain ASCII letters, digits, `_`, and `-`."
+        )
+
+
+def display_name_from_plugin_name(plugin_name: str) -> str:
+    return " ".join(part.capitalize() for part in re.split(r"[-_]+", plugin_name))
+
+
+def build_plugin_json(plugin_name: str, *, with_mcp: bool, with_apps: bool) -> dict[str, Any]:
+    display_name = display_name_from_plugin_name(plugin_name)
+    payload: dict[str, Any] = {
+        "name": plugin_name,
+        "version": "0.1.0",
+        "description": f"{display_name} plugin",
+        "author": {
+            "name": "Local developer",
+        },
+        "skills": "./skills/",
+        "interface": {
+            "displayName": display_name,
+            "shortDescription": f"Use {display_name} in Codex.",
+            "longDescription": f"{display_name} adds a local Codex plugin scaffold.",
+            "developerName": "Local developer",
+            "category": DEFAULT_CATEGORY,
+            "capabilities": [],
+            "defaultPrompt": f"Help me use {display_name}.",
+        },
+    }
+    if with_mcp:
+        payload["mcpServers"] = "./.mcp.json"
+    if with_apps:
+        payload["apps"] = "./.app.json"
+    return payload
+
+
+def build_marketplace_entry(
+    plugin_name: str,
+    install_policy: str,
+    auth_policy: str,
+    category: str,
+) -> dict[str, Any]:
+    return {
+        "name": plugin_name,
+        "source": {
+            "source": "local",
+            "path": f"./plugins/{plugin_name}",
+        },
+        "policy": {
+            "installation": install_policy,
+            "authentication": auth_policy,
+        },
+        "category": category,
+    }
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    with path.open() as handle:
+        return json.load(handle)
+
+
+def build_default_marketplace(marketplace_name: str) -> dict[str, Any]:
+    return {
+        "name": marketplace_name,
+        "interface": {
+            "displayName": display_name_from_plugin_name(marketplace_name),
+        },
+        "plugins": [],
+    }
+
+
+def validate_marketplace_interface(payload: dict[str, Any]) -> None:
+    interface = payload.get("interface")
+    if interface is not None and not isinstance(interface, dict):
+        raise ValueError("marketplace.json field 'interface' must be an object.")
+
+
+def update_marketplace_json(
+    marketplace_path: Path,
+    marketplace_name: str | None,
+    plugin_name: str,
+    install_policy: str,
+    auth_policy: str,
+    category: str,
+    force: bool,
+) -> None:
+    if marketplace_path.exists():
+        payload = load_json(marketplace_path)
+    else:
+        payload = build_default_marketplace(marketplace_name or DEFAULT_MARKETPLACE_NAME)
+
+    if not isinstance(payload, dict):
+        raise ValueError(f"{marketplace_path} must contain a JSON object.")
+
+    validate_marketplace_interface(payload)
+
+    existing_marketplace_name = payload.get("name")
+    if marketplace_name is not None:
+        if not isinstance(existing_marketplace_name, str) or not existing_marketplace_name.strip():
+            raise ValueError(f"{marketplace_path} must contain a non-empty string 'name'.")
+        if existing_marketplace_name != marketplace_name:
+            raise ValueError(
+                f"{marketplace_path} already uses marketplace name "
+                f"'{existing_marketplace_name}'. Create a new marketplace file to use "
+                f"'{marketplace_name}' instead."
+            )
+
+    plugins = payload.setdefault("plugins", [])
+    if not isinstance(plugins, list):
+        raise ValueError(f"{marketplace_path} field 'plugins' must be an array.")
+
+    new_entry = build_marketplace_entry(plugin_name, install_policy, auth_policy, category)
+
+    for index, entry in enumerate(plugins):
+        if isinstance(entry, dict) and entry.get("name") == plugin_name:
+            if not force:
+                raise FileExistsError(
+                    f"Marketplace entry '{plugin_name}' already exists in {marketplace_path}. "
+                    "Use --force to overwrite that entry."
+                )
+            plugins[index] = new_entry
+            break
+    else:
+        plugins.append(new_entry)
+
+    write_json(marketplace_path, payload, force=True)
+
+
+def write_json(path: Path, data: dict, force: bool) -> None:
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} already exists. Use --force to overwrite.")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w") as handle:
+        json.dump(data, handle, indent=2)
+        handle.write("\n")
+
+
+def create_stub_file(path: Path, payload: dict, force: bool) -> None:
+    if path.exists() and not force:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w") as handle:
+        json.dump(payload, handle, indent=2)
+        handle.write("\n")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Create a plugin skeleton with a validation-ready plugin.json."
+    )
+    parser.add_argument("plugin_name")
+    parser.add_argument(
+        "--path",
+        default=str(DEFAULT_PLUGIN_PARENT),
+        help=(
+            "Parent directory for plugin creation (defaults to <home>/plugins). "
+            "Pass an explicit repo path only when a repo/team plugin is intended."
+        ),
+    )
+    parser.add_argument("--with-skills", action="store_true", help="Create skills/ directory")
+    parser.add_argument("--with-hooks", action="store_true", help="Create hooks/ directory")
+    parser.add_argument("--with-scripts", action="store_true", help="Create scripts/ directory")
+    parser.add_argument("--with-assets", action="store_true", help="Create assets/ directory")
+    parser.add_argument("--with-mcp", action="store_true", help="Create .mcp.json placeholder")
+    parser.add_argument("--with-apps", action="store_true", help="Create .app.json placeholder")
+    parser.add_argument(
+        "--with-marketplace",
+        action="store_true",
+        help=(
+            "Create or update <home>/.agents/plugins/marketplace.json by default. "
+            "Marketplace entries always point to ./plugins/<plugin-name> relative to the "
+            "marketplace root."
+        ),
+    )
+    parser.add_argument(
+        "--marketplace-path",
+        default=str(DEFAULT_MARKETPLACE_PATH),
+        help=(
+            "Path to marketplace.json (defaults to <home>/.agents/plugins/marketplace.json). "
+            "Pass a repo-rooted marketplace path only when a repo/team plugin is intended."
+        ),
+    )
+    parser.add_argument(
+        "--marketplace-name",
+        help=(
+            "Marketplace name to seed into a new marketplace.json. Use this only when the default "
+            "'personal' marketplace name is already taken and you need a different new marketplace."
+        ),
+    )
+    parser.add_argument(
+        "--install-policy",
+        default=DEFAULT_INSTALL_POLICY,
+        choices=sorted(VALID_INSTALL_POLICIES),
+        help="Marketplace policy.installation value",
+    )
+    parser.add_argument(
+        "--auth-policy",
+        default=DEFAULT_AUTH_POLICY,
+        choices=sorted(VALID_AUTH_POLICIES),
+        help="Marketplace policy.authentication value",
+    )
+    parser.add_argument(
+        "--category",
+        default=DEFAULT_CATEGORY,
+        help="Marketplace category value",
+    )
+    parser.add_argument("--force", action="store_true", help="Overwrite existing files")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    raw_plugin_name = args.plugin_name
+    plugin_name = normalize_plugin_name(raw_plugin_name)
+    if plugin_name != raw_plugin_name:
+        print(f"Note: Normalized plugin name from '{raw_plugin_name}' to '{plugin_name}'.")
+    validate_plugin_name(plugin_name)
+    marketplace_name = None
+    if args.marketplace_name is not None:
+        marketplace_name = args.marketplace_name.strip()
+        validate_marketplace_name(marketplace_name)
+
+    plugin_root = (Path(args.path).expanduser().resolve() / plugin_name)
+    plugin_root.mkdir(parents=True, exist_ok=True)
+
+    plugin_json_path = plugin_root / ".codex-plugin" / "plugin.json"
+    write_json(
+        plugin_json_path,
+        build_plugin_json(plugin_name, with_mcp=args.with_mcp, with_apps=args.with_apps),
+        args.force,
+    )
+
+    optional_directories = {
+        "skills": args.with_skills,
+        "hooks": args.with_hooks,
+        "scripts": args.with_scripts,
+        "assets": args.with_assets,
+    }
+    for folder, enabled in optional_directories.items():
+        if enabled:
+            (plugin_root / folder).mkdir(parents=True, exist_ok=True)
+
+    if args.with_mcp:
+        create_stub_file(
+            plugin_root / ".mcp.json",
+            {"mcpServers": {}},
+            args.force,
+        )
+
+    if args.with_apps:
+        create_stub_file(
+            plugin_root / ".app.json",
+            {
+                "apps": {},
+            },
+            args.force,
+        )
+
+    if args.with_marketplace:
+        marketplace_path = Path(args.marketplace_path).expanduser().resolve()
+        update_marketplace_json(
+            marketplace_path,
+            marketplace_name,
+            plugin_name,
+            args.install_policy,
+            args.auth_policy,
+            args.category,
+            args.force,
+        )
+
+    print(f"Created plugin scaffold: {plugin_root}")
+    print(f"plugin manifest: {plugin_json_path}")
+    if args.with_marketplace:
+        print(f"marketplace manifest: {marketplace_path}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/skills/plugin-creator/scripts/read_marketplace_name.py b/skills/plugin-creator/scripts/read_marketplace_name.py
new file mode 100644
index 0000000..597e9f7
--- /dev/null
+++ b/skills/plugin-creator/scripts/read_marketplace_name.py
@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Print the top-level marketplace name from any marketplace.json file."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def default_marketplace_path() -> Path:
+    return Path.home() / ".agents" / "plugins" / "marketplace.json"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Print the top-level marketplace name from marketplace.json. Defaults to the personal "
+            "marketplace path under the current home directory."
+        )
+    )
+    parser.add_argument(
+        "--marketplace-path",
+        default=str(default_marketplace_path()),
+        help="Path to marketplace.json",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    marketplace_path = Path(args.marketplace_path).expanduser().resolve()
+    payload = json.loads(marketplace_path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError(f"{marketplace_path} must contain a JSON object.")
+    name = payload.get("name")
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError(f"{marketplace_path} must contain a non-empty string 'name'.")
+    print(name.strip())
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as err:  # noqa: BLE001 - CLI should surface a single clear message.
+        print(str(err), file=sys.stderr)
+        raise SystemExit(1) from err
diff --git a/skills/plugin-creator/scripts/update_plugin_cachebuster.py b/skills/plugin-creator/scripts/update_plugin_cachebuster.py
new file mode 100644
index 0000000..82d19e5
--- /dev/null
+++ b/skills/plugin-creator/scripts/update_plugin_cachebuster.py
@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Rewrite a local plugin version to a single Codex cachebuster suffix."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+CACHEBUSTER_PREFIX = "codex"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Rewrite a local plugin's version so it preserves everything before '+' and uses "
+            "a single +codex.<cachebuster> suffix."
+        )
+    )
+    parser.add_argument("plugin_path", help="Path to the plugin root directory")
+    parser.add_argument(
+        "--cachebuster",
+        help="Optional cachebuster token to embed in the plugin version",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    plugin_root = Path(args.plugin_path).expanduser().resolve()
+    manifest_path = plugin_root / ".codex-plugin" / "plugin.json"
+    manifest = load_manifest(manifest_path)
+
+    version = manifest.get("version")
+    if not isinstance(version, str) or not version.strip():
+        raise ValueError(f"{manifest_path} must contain a non-empty string 'version'.")
+    cachebuster = sanitize_cachebuster(args.cachebuster or default_cachebuster())
+    next_version = with_cachebuster(version, cachebuster)
+    manifest["version"] = next_version
+    manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
+    print(f"Updated plugin version: {version} -> {next_version}")
+
+
+def load_manifest(manifest_path: Path) -> dict[str, object]:
+    if not manifest_path.is_file():
+        raise FileNotFoundError(f"missing manifest: {manifest_path}")
+    payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError(f"{manifest_path} must contain a JSON object.")
+    return payload
+def sanitize_cachebuster(value: str) -> str:
+    sanitized = re.sub(r"[^a-z0-9-]+", "-", value.strip().lower())
+    sanitized = re.sub(r"-{2,}", "-", sanitized).strip("-")
+    if not sanitized:
+        raise ValueError("Cachebuster must contain at least one letter or digit.")
+    return sanitized
+
+
+def default_cachebuster() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+
+
+def with_cachebuster(version: str, cachebuster: str) -> str:
+    version_prefix = version.split("+", 1)[0]
+    return f"{version_prefix}+{CACHEBUSTER_PREFIX}.{cachebuster}"
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as err:  # noqa: BLE001 - CLI should surface a single clear message.
+        print(str(err), file=sys.stderr)
+        raise SystemExit(1) from err
diff --git a/skills/plugin-creator/scripts/validate_plugin.py b/skills/plugin-creator/scripts/validate_plugin.py
new file mode 100644
index 0000000..6f49cb0
--- /dev/null
+++ b/skills/plugin-creator/scripts/validate_plugin.py
@@ -0,0 +1,593 @@
+#!/usr/bin/env python3
+"""Validate a generated plugin against the plugin ingestion contract."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path, PurePosixPath
+from typing import Any
+from urllib.parse import urlparse
+
+import yaml
+
+
+TODO_MARKER = "[TODO:"
+SEMVER_RE = re.compile(
+    r"^(0|[1-9]\d*)\."
+    r"(0|[1-9]\d*)\."
+    r"(0|[1-9]\d*)"
+    r"(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\."
+    r"(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?"
+    r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$"
+)
+HEX_COLOR_RE = re.compile(r"^#[0-9A-F]{6}$", re.IGNORECASE)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Validate a local Codex plugin.")
+    parser.add_argument("plugin_path", help="Path to the plugin root directory")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    plugin_root = Path(args.plugin_path).expanduser().resolve()
+    errors = validate_plugin(plugin_root)
+    if errors:
+        print("Plugin validation failed:")
+        for error in errors:
+            print(f"- {error}")
+        raise SystemExit(1)
+    print(f"Plugin validation passed: {plugin_root}")
+
+
+def validate_plugin(plugin_root: Path) -> list[str]:
+    errors: list[str] = []
+    manifest_path = plugin_root / ".codex-plugin" / "plugin.json"
+    manifest = load_json_object(manifest_path, errors)
+    if manifest is None:
+        return errors
+
+    reject_todo_markers(manifest, "$", errors)
+    validate_manifest_shape(plugin_root, manifest, errors)
+    return errors
+
+
+def load_json_object(path: Path, errors: list[str]) -> dict[str, Any] | None:
+    if not path.is_file():
+        errors.append("missing `.codex-plugin/plugin.json`")
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except OSError:
+        errors.append("unable to read `.codex-plugin/plugin.json`")
+        return None
+    except json.JSONDecodeError:
+        errors.append("`.codex-plugin/plugin.json` must be valid JSON")
+        return None
+    if not isinstance(payload, dict):
+        errors.append("`.codex-plugin/plugin.json` must contain a JSON object")
+        return None
+    return payload
+
+
+def reject_todo_markers(value: Any, path: str, errors: list[str]) -> None:
+    if isinstance(value, str):
+        if TODO_MARKER in value:
+            errors.append(f"{path} still contains a `[TODO: ...]` placeholder")
+        return
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            reject_todo_markers(item, f"{path}[{index}]", errors)
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            reject_todo_markers(item, f"{path}.{key}", errors)
+
+
+def validate_manifest_shape(
+    plugin_root: Path,
+    manifest: dict[str, Any],
+    errors: list[str],
+) -> None:
+    allowed_keys = {
+        "id",
+        "name",
+        "version",
+        "description",
+        "skills",
+        "apps",
+        "mcpServers",
+        "interface",
+        "author",
+        "homepage",
+        "repository",
+        "license",
+        "keywords",
+    }
+    for key in sorted(set(manifest) - allowed_keys):
+        errors.append(f"plugin.json field `{key}` is not accepted by plugin validation")
+
+    validate_optional_non_empty_string(manifest, "id", errors)
+    require_non_empty_string(manifest, "name", errors)
+    version = require_non_empty_string(manifest, "version", errors)
+    if version is not None and SEMVER_RE.fullmatch(version) is None:
+        errors.append("plugin.json field `version` must be strict semver")
+    require_non_empty_string(manifest, "description", errors)
+
+    author = require_object(manifest, "author", errors)
+    if author is not None:
+        reject_unknown_fields(author, {"name", "email", "url"}, "author", errors)
+        require_non_empty_string(author, "name", errors, prefix="author")
+        validate_optional_non_empty_string(author, "email", errors, prefix="author")
+        validate_optional_https_url(author, "url", errors, prefix="author")
+
+    validate_optional_contract_path(manifest, "skills", "skills", errors)
+    validate_optional_contract_path(manifest, "apps", ".app.json", errors)
+    validate_optional_contract_path(manifest, "mcpServers", ".mcp.json", errors)
+
+    if manifest.get("apps") is not None:
+        validate_app_manifest(
+            plugin_root / ".app.json",
+            errors,
+        )
+    if manifest.get("mcpServers") is not None:
+        validate_mcp_manifest(
+            plugin_root / ".mcp.json",
+            errors,
+        )
+    validate_skill_manifests(plugin_root, errors)
+
+    interface = require_object(manifest, "interface", errors)
+    if interface is None:
+        return
+    reject_unknown_fields(
+        interface,
+        {
+            "displayName",
+            "shortDescription",
+            "longDescription",
+            "developerName",
+            "category",
+            "capabilities",
+            "websiteURL",
+            "privacyPolicyURL",
+            "termsOfServiceURL",
+            "brandColor",
+            "composerIcon",
+            "logo",
+            "screenshots",
+            "defaultPrompt",
+            "default_prompt",
+        },
+        "interface",
+        errors,
+    )
+    for field in (
+        "displayName",
+        "shortDescription",
+        "longDescription",
+        "developerName",
+        "category",
+    ):
+        require_non_empty_string(interface, field, errors, prefix="interface")
+    if "defaultPrompt" not in interface and "default_prompt" not in interface:
+        errors.append(
+            "plugin.json field `interface.defaultPrompt` or `interface.default_prompt` is required"
+        )
+    capabilities = interface.get("capabilities")
+    if not isinstance(capabilities, list) or not all(
+        isinstance(value, str) and value.strip() for value in capabilities
+    ):
+        errors.append("plugin.json field `interface.capabilities` must be an array of strings")
+    for field in ("websiteURL", "privacyPolicyURL", "termsOfServiceURL"):
+        validate_optional_https_url(interface, field, errors, prefix="interface")
+    brand_color = interface.get("brandColor")
+    if brand_color is not None and (
+        not isinstance(brand_color, str) or HEX_COLOR_RE.fullmatch(brand_color) is None
+    ):
+        errors.append("plugin.json field `interface.brandColor` must use `#RRGGBB`")
+    for field in ("composerIcon", "logo"):
+        validate_optional_asset_path(plugin_root, plugin_root, interface, field, errors)
+    screenshots = interface.get("screenshots", [])
+    if not isinstance(screenshots, list):
+        errors.append("plugin.json field `interface.screenshots` must be an array")
+    else:
+        for index, raw_path in enumerate(screenshots):
+            validate_asset_path(
+                plugin_root,
+                plugin_root,
+                raw_path,
+                f"interface.screenshots[{index}]",
+                errors,
+            )
+
+
+def require_object(
+    payload: dict[str, Any],
+    key: str,
+    errors: list[str],
+) -> dict[str, Any] | None:
+    value = payload.get(key)
+    if not isinstance(value, dict):
+        errors.append(f"plugin.json field `{key}` must be an object")
+        return None
+    return value
+
+
+def require_non_empty_string(
+    payload: dict[str, Any],
+    key: str,
+    errors: list[str],
+    *,
+    prefix: str | None = None,
+) -> str | None:
+    value = payload.get(key)
+    field = f"{prefix}.{key}" if prefix is not None else key
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"plugin.json field `{field}` must be a non-empty string")
+        return None
+    return value
+
+
+def validate_optional_non_empty_string(
+    payload: dict[str, Any],
+    key: str,
+    errors: list[str],
+    *,
+    prefix: str | None = None,
+) -> None:
+    value = payload.get(key)
+    if value is None:
+        return
+    field = f"{prefix}.{key}" if prefix is not None else key
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"plugin.json field `{field}` must be a non-empty string")
+
+
+def reject_unknown_fields(
+    payload: dict[str, Any],
+    allowed_keys: set[str],
+    prefix: str,
+    errors: list[str],
+) -> None:
+    for key in sorted(set(payload) - allowed_keys):
+        errors.append(f"plugin.json field `{prefix}.{key}` is not accepted by plugin validation")
+
+
+def validate_optional_https_url(
+    payload: dict[str, Any],
+    key: str,
+    errors: list[str],
+    *,
+    prefix: str,
+) -> None:
+    value = payload.get(key)
+    if value is None:
+        return
+    parsed = urlparse(value) if isinstance(value, str) else None
+    if parsed is None or parsed.scheme != "https" or not parsed.netloc:
+        errors.append(f"plugin.json field `{prefix}.{key}` must be an absolute `https://` URL")
+
+
+def validate_optional_contract_path(
+    payload: dict[str, Any],
+    key: str,
+    expected: str,
+    errors: list[str],
+) -> None:
+    value = payload.get(key)
+    if value is None:
+        return
+    normalized = normalize_contract_path(value) if isinstance(value, str) else None
+    if normalized != expected:
+        errors.append(f"plugin.json field `{key}` must resolve to `{expected}`")
+
+
+def normalize_contract_path(raw_path: str) -> str | None:
+    path = Path(raw_path)
+    if path.is_absolute():
+        return None
+    normalized = path.as_posix().rstrip("/")
+    return normalized or None
+
+
+def validate_app_manifest(path: Path, errors: list[str]) -> None:
+    payload = load_companion_json_object(path, "`.app.json`", errors)
+    if payload is None:
+        return
+    reject_companion_unknown_fields(payload, {"apps"}, "`.app.json`", errors)
+    apps = payload.get("apps")
+    if not isinstance(apps, dict):
+        errors.append("`.app.json` field `apps` must be an object")
+        return
+    for key, value in apps.items():
+        if not isinstance(value, dict):
+            errors.append(f"`.app.json` app `{key}` must be an object")
+            continue
+        reject_companion_unknown_fields(
+            value, {"id", "category"}, f"`.app.json` app `{key}`", errors
+        )
+        app_id = value.get("id")
+        if not isinstance(app_id, str) or not app_id.strip():
+            errors.append(f"`.app.json` app `{key}` field `id` must be a non-empty string")
+        category = value.get("category")
+        if category is not None and (not isinstance(category, str) or not category.strip()):
+            errors.append(
+                f"`.app.json` app `{key}` field `category` must be a non-empty string"
+            )
+
+
+def validate_mcp_manifest(path: Path, errors: list[str]) -> None:
+    payload = load_companion_json_object(path, "`.mcp.json`", errors)
+    if payload is None:
+        return
+    reject_companion_unknown_fields(payload, {"mcpServers"}, "`.mcp.json`", errors)
+    servers = payload.get("mcpServers")
+    if not isinstance(servers, dict):
+        errors.append("`.mcp.json` field `mcpServers` must be an object")
+        return
+    for key, value in servers.items():
+        if not isinstance(key, str) or not key.strip():
+            errors.append("`.mcp.json` server names must be non-empty strings")
+        if not isinstance(value, dict):
+            errors.append(f"`.mcp.json` server `{key}` must be an object")
+
+
+def load_companion_json_object(
+    path: Path,
+    label: str,
+    errors: list[str],
+) -> dict[str, Any] | None:
+    if not path.is_file():
+        errors.append(f"{label} is required when its plugin.json field is present")
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        errors.append(f"{label} must contain valid JSON")
+        return None
+    if not isinstance(payload, dict):
+        errors.append(f"{label} must contain a JSON object")
+        return None
+    return payload
+
+
+def reject_companion_unknown_fields(
+    payload: dict[str, Any],
+    allowed_keys: set[str],
+    prefix: str,
+    errors: list[str],
+) -> None:
+    for key in sorted(set(payload) - allowed_keys):
+        errors.append(f"{prefix} field `{key}` is not accepted by plugin validation")
+
+
+def validate_skill_manifests(plugin_root: Path, errors: list[str]) -> None:
+    skills_root = plugin_root / "skills"
+    if not skills_root.is_dir():
+        return
+    for skill_root in sorted(skills_root.iterdir(), key=lambda path: path.name):
+        if skill_root.name.startswith(".") or not skill_root.is_dir():
+            continue
+        validate_skill_manifest(skill_root, errors)
+
+
+def validate_skill_manifest(skill_root: Path, errors: list[str]) -> None:
+    skill_md_path = skill_root / "SKILL.md"
+    if not skill_md_path.is_file():
+        errors.append(f"skill `{skill_root.name}` is missing `SKILL.md`")
+        return
+    try:
+        contents = skill_md_path.read_text(encoding="utf-8")
+    except OSError:
+        errors.append(f"unable to read skill `{skill_root.name}`")
+        return
+    if not contents.startswith("---\n"):
+        errors.append(f"skill `{skill_root.name}` must start with YAML frontmatter")
+        return
+    frontmatter_end = contents.find("\n---", 4)
+    if frontmatter_end == -1:
+        errors.append(f"skill `{skill_root.name}` frontmatter is not closed")
+        return
+    try:
+        frontmatter = yaml.safe_load(contents[4:frontmatter_end])
+    except yaml.YAMLError:
+        errors.append(f"skill `{skill_root.name}` frontmatter must be valid YAML")
+        return
+    if not isinstance(frontmatter, dict):
+        errors.append(f"skill `{skill_root.name}` frontmatter must be an object")
+        return
+    skill_name = frontmatter.get("name")
+    if not isinstance(skill_name, str) or not skill_name.strip():
+        errors.append(f"skill `{skill_root.name}` frontmatter field `name` must be non-empty")
+    description = frontmatter.get("description")
+    if not isinstance(description, str) or not description.strip():
+        errors.append(
+            f"skill `{skill_root.name}` frontmatter field `description` must be non-empty"
+        )
+    disable_model_invocation = frontmatter.get("disable-model-invocation")
+    if disable_model_invocation is None:
+        disable_model_invocation = frontmatter.get("disable_model_invocation")
+    if disable_model_invocation not in (None, False):
+        errors.append(
+            f"skill `{skill_root.name}` frontmatter field `disable-model-invocation` must be false"
+        )
+    agent_yaml_path = skill_root / "agents" / "openai.yaml"
+    if agent_yaml_path.is_file():
+        validate_skill_agent_manifest(
+            plugin_root=skill_root.parent.parent,
+            skill_root=skill_root,
+            agent_yaml_path=agent_yaml_path,
+            errors=errors,
+        )
+
+
+def validate_skill_agent_manifest(
+    *,
+    plugin_root: Path,
+    skill_root: Path,
+    agent_yaml_path: Path,
+    errors: list[str],
+) -> None:
+    try:
+        payload = yaml.safe_load(agent_yaml_path.read_text(encoding="utf-8"))
+    except OSError:
+        errors.append(f"unable to read skill `{skill_root.name}` agent YAML")
+        return
+    except yaml.YAMLError:
+        errors.append(f"skill `{skill_root.name}` agent YAML must be valid YAML")
+        return
+    if not isinstance(payload, dict):
+        errors.append(f"skill `{skill_root.name}` agent YAML must be an object")
+        return
+
+    reject_skill_agent_unknown_fields(
+        payload,
+        {"interface", "policy", "dependencies"},
+        skill_root,
+        errors,
+    )
+    interface = payload.get("interface")
+    if not isinstance(interface, dict):
+        errors.append(f"skill `{skill_root.name}` agent field `interface` must be an object")
+        return
+    reject_skill_agent_unknown_fields(
+        interface,
+        {
+            "display_name",
+            "short_description",
+            "icon_small",
+            "icon_large",
+            "brand_color",
+            "default_prompt",
+        },
+        skill_root,
+        errors,
+        prefix="interface",
+    )
+    for field in ("display_name", "short_description"):
+        value = interface.get(field)
+        if not isinstance(value, str) or not value.strip():
+            errors.append(
+                f"skill `{skill_root.name}` agent field `interface.{field}` must be non-empty"
+            )
+    for field in ("icon_small", "icon_large"):
+        validate_optional_asset_path(
+            skill_root,
+            plugin_root,
+            interface,
+            field,
+            errors,
+            prefix=f"skill `{skill_root.name}` agent field `interface",
+        )
+    brand_color = interface.get("brand_color")
+    if brand_color is not None and (
+        not isinstance(brand_color, str) or HEX_COLOR_RE.fullmatch(brand_color) is None
+    ):
+        errors.append(
+            f"skill `{skill_root.name}` agent field `interface.brand_color` must use `#RRGGBB`"
+        )
+    default_prompt = interface.get("default_prompt")
+    if default_prompt is not None and (
+        not isinstance(default_prompt, str) or not default_prompt.strip()
+    ):
+        errors.append(
+            f"skill `{skill_root.name}` agent field `interface.default_prompt` must be non-empty"
+        )
+
+    policy = payload.get("policy")
+    if policy is not None:
+        if not isinstance(policy, dict):
+            errors.append(f"skill `{skill_root.name}` agent field `policy` must be an object")
+        else:
+            reject_skill_agent_unknown_fields(
+                policy,
+                {"allow_implicit_invocation"},
+                skill_root,
+                errors,
+                prefix="policy",
+            )
+            allow_implicit_invocation = policy.get("allow_implicit_invocation")
+            if allow_implicit_invocation is not None and not isinstance(
+                allow_implicit_invocation,
+                bool,
+            ):
+                errors.append(
+                    f"skill `{skill_root.name}` agent field "
+                    "`policy.allow_implicit_invocation` must be a boolean"
+                )
+
+    dependencies = payload.get("dependencies")
+    if dependencies is not None:
+        if not isinstance(dependencies, dict):
+            errors.append(
+                f"skill `{skill_root.name}` agent field `dependencies` must be an object"
+            )
+        else:
+            reject_skill_agent_unknown_fields(
+                dependencies,
+                {"tools"},
+                skill_root,
+                errors,
+                prefix="dependencies",
+            )
+
+
+def reject_skill_agent_unknown_fields(
+    payload: dict[str, Any],
+    allowed_keys: set[str],
+    skill_root: Path,
+    errors: list[str],
+    *,
+    prefix: str | None = None,
+) -> None:
+    for key in sorted(set(payload) - allowed_keys):
+        field = f"{prefix}.{key}" if prefix is not None else key
+        errors.append(
+            f"skill `{skill_root.name}` agent field `{field}` is not accepted by plugin validation"
+        )
+
+
+def validate_optional_asset_path(
+    base_dir: Path,
+    allowed_root: Path,
+    payload: dict[str, Any],
+    key: str,
+    errors: list[str],
+    *,
+    prefix: str = "interface",
+) -> None:
+    raw_path = payload.get(key)
+    if raw_path is None:
+        return
+    validate_asset_path(base_dir, allowed_root, raw_path, f"{prefix}.{key}", errors)
+
+
+def validate_asset_path(
+    base_dir: Path,
+    allowed_root: Path,
+    raw_path: Any,
+    field: str,
+    errors: list[str],
+) -> None:
+    label = field if field.startswith("skill `") else f"plugin.json field `{field}`"
+    if not isinstance(raw_path, str) or not raw_path.strip():
+        errors.append(f"{label} must be a non-empty relative path")
+        return
+    candidate = PurePosixPath(raw_path.replace("\\", "/"))
+    if candidate.is_absolute() or any(part in {"", ".", ".."} for part in candidate.parts):
+        errors.append(f"{label} must stay inside the plugin archive")
+        return
+    resolved_path = (base_dir / candidate.as_posix()).resolve()
+    if not resolved_path.is_relative_to(allowed_root.resolve()):
+        errors.append(f"{label} must stay inside the plugin archive")
+        return
+    if not resolved_path.is_file():
+        errors.append(f"{label} points to a missing file")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/skills/prompt-0ca565e9-3d44-45f1-832d-caa438aceddb/SKILL.md b/skills/prompt-0ca565e9-3d44-45f1-832d-caa438aceddb/SKILL.md
new file mode 100644
index 0000000..859b6e9
--- /dev/null
+++ b/skills/prompt-0ca565e9-3d44-45f1-832d-caa438aceddb/SKILL.md
@@ -0,0 +1,11 @@
+---
+name: "prompt-0ca565e9-3d44-45f1-832d-caa438aceddb"
+description: "文档编辑"
+metadata:
+  short-description: "文档编辑"
+---
+
+# 文档编辑
+
+**规约：定义型修改先找单一权威，禁止外挂补丁。**
+当修改 prompt/schema/状态机/协议语义时，先定位“唯一权威定义区”，优先直接重写该定义；如果改动只是往附近追加说明、例外或补充规则，而没有收束原定义，默认视为错误方案。提交前必须自问：我是在降低信息熵，还是在制造第二套语义。
diff --git a/skills/prompt-0ca565e9-3d44-45f1-832d-caa438aceddb/agents/openai.yaml b/skills/prompt-0ca565e9-3d44-45f1-832d-caa438aceddb/agents/openai.yaml
new file mode 100644
index 0000000..80922d4
--- /dev/null
+++ b/skills/prompt-0ca565e9-3d44-45f1-832d-caa438aceddb/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "文档编辑"
+  short_description: "文档编辑"
+  default_prompt: "Use $prompt-0ca565e9-3d44-45f1-832d-caa438aceddb."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-1309ed22-5b5e-4774-9b85-41bb1b7cc971/SKILL.md b/skills/prompt-1309ed22-5b5e-4774-9b85-41bb1b7cc971/SKILL.md
new file mode 100644
index 0000000..3cf610f
--- /dev/null
+++ b/skills/prompt-1309ed22-5b5e-4774-9b85-41bb1b7cc971/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-1309ed22-5b5e-4774-9b85-41bb1b7cc971"
+description: "始终批判自己"
+metadata:
+  short-description: "始终批判自己"
+---
+
+# 始终批判自己
+
+始终批判自己，批判性思维，做了若干决策后，他们会综合作用产生效果，需要批判其中每一项，最终按优先级和最终预期收益看情况保留
diff --git a/skills/prompt-1309ed22-5b5e-4774-9b85-41bb1b7cc971/agents/openai.yaml b/skills/prompt-1309ed22-5b5e-4774-9b85-41bb1b7cc971/agents/openai.yaml
new file mode 100644
index 0000000..26b71cf
--- /dev/null
+++ b/skills/prompt-1309ed22-5b5e-4774-9b85-41bb1b7cc971/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "始终批判自己"
+  short_description: "始终批判自己"
+  default_prompt: "Use $prompt-1309ed22-5b5e-4774-9b85-41bb1b7cc971."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-1323c8c8-88a0-40d2-89df-14fc9533a122/SKILL.md b/skills/prompt-1323c8c8-88a0-40d2-89df-14fc9533a122/SKILL.md
new file mode 100644
index 0000000..ef1315d
--- /dev/null
+++ b/skills/prompt-1323c8c8-88a0-40d2-89df-14fc9533a122/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-1323c8c8-88a0-40d2-89df-14fc9533a122"
+description: "尽量减少确认项"
+metadata:
+  short-description: "尽量减少确认项"
+---
+
+# 尽量减少确认项
+
+实现情况不要找用户确认，因为看代码就可以知道了，得自己看
diff --git a/skills/prompt-1323c8c8-88a0-40d2-89df-14fc9533a122/agents/openai.yaml b/skills/prompt-1323c8c8-88a0-40d2-89df-14fc9533a122/agents/openai.yaml
new file mode 100644
index 0000000..2010a57
--- /dev/null
+++ b/skills/prompt-1323c8c8-88a0-40d2-89df-14fc9533a122/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "尽量减少确认项"
+  short_description: "尽量减少确认项"
+  default_prompt: "Use $prompt-1323c8c8-88a0-40d2-89df-14fc9533a122."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-144929a0-ae69-404b-9f58-a8696378e4e3/SKILL.md b/skills/prompt-144929a0-ae69-404b-9f58-a8696378e4e3/SKILL.md
new file mode 100644
index 0000000..dc879e8
--- /dev/null
+++ b/skills/prompt-144929a0-ae69-404b-9f58-a8696378e4e3/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-144929a0-ae69-404b-9f58-a8696378e4e3"
+description: "Patch 式改动审阅"
+metadata:
+  short-description: "Patch 式改动审阅"
+---
+
+# Patch 式改动审阅
+
+对于代码改动，你需要在我最终同意"落盘 diff"前，仅能 告知我 改动 位置 以及 代码 diff 详情，为我按 hunks 力度解释其修改动机和服务对象，并在 最终落盘时还要观察 最新状态代码一致性
diff --git a/skills/prompt-144929a0-ae69-404b-9f58-a8696378e4e3/agents/openai.yaml b/skills/prompt-144929a0-ae69-404b-9f58-a8696378e4e3/agents/openai.yaml
new file mode 100644
index 0000000..2d610b2
--- /dev/null
+++ b/skills/prompt-144929a0-ae69-404b-9f58-a8696378e4e3/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Patch 式改动审阅"
+  short_description: "Patch 式改动审阅"
+  default_prompt: "Use $prompt-144929a0-ae69-404b-9f58-a8696378e4e3."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-15d9a907-a363-4ec7-81ad-806f9418ad72/SKILL.md b/skills/prompt-15d9a907-a363-4ec7-81ad-806f9418ad72/SKILL.md
new file mode 100644
index 0000000..3c935ad
--- /dev/null
+++ b/skills/prompt-15d9a907-a363-4ec7-81ad-806f9418ad72/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-15d9a907-a363-4ec7-81ad-806f9418ad72"
+description: "pua严肃设计"
+metadata:
+  short-description: "pua严肃设计"
+---
+
+# pua严肃设计
+
+请严肃设计，我们在设计一套精密仪器，跨时代产品
diff --git a/skills/prompt-15d9a907-a363-4ec7-81ad-806f9418ad72/agents/openai.yaml b/skills/prompt-15d9a907-a363-4ec7-81ad-806f9418ad72/agents/openai.yaml
new file mode 100644
index 0000000..d6bc16b
--- /dev/null
+++ b/skills/prompt-15d9a907-a363-4ec7-81ad-806f9418ad72/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "pua严肃设计"
+  short_description: "pua严肃设计"
+  default_prompt: "Use $prompt-15d9a907-a363-4ec7-81ad-806f9418ad72."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-193dd3cd-2722-413b-b88c-12c2af645f80/SKILL.md b/skills/prompt-193dd3cd-2722-413b-b88c-12c2af645f80/SKILL.md
new file mode 100644
index 0000000..6b7f96d
--- /dev/null
+++ b/skills/prompt-193dd3cd-2722-413b-b88c-12c2af645f80/SKILL.md
@@ -0,0 +1,16 @@
+---
+name: "prompt-193dd3cd-2722-413b-b88c-12c2af645f80"
+description: "使用 agent-browser 排查运行时状态"
+metadata:
+  short-description: "使用 agent-browser 排查运行时状态"
+---
+
+# 使用 agent-browser 排查运行时状态
+
+使用 agent-browser 排查运行时状态，
+# 业务指引
+请你 操作 agent-browser 打开 https://10.126.126.231:8111/ 然后通过侧栏进入 HY workspace， 打开 dever_for_dev 项目
+## 运行时 worknote 目录 
+- 我给予你 /opt/store_team_dev/zyc/dever_for_dev/attic/.agent-browser-runtime-workdir 这个工作目录 ，在每个 节点 把你 阶段性 的 操作截图 给我检查，截图 请 前缀 添加时间轴，格式为 <date>-<time>-<截图名称>.<图片文件格式>
+## 开发日常情况适应
+- 需要你去记忆这个情况: 我们在 不断迭代着 界面，所以有时候界面一下子 崩掉了是因为有其他组件在热更新，你要 适应这个情况，当你感觉 遇到了这个问题，你向我 确认 刚刚 是否 出现热更新，我往往 会 回答 "对,是的" 或者 "我不确定"，这种 情况 就希望 你不要被之前 状态误导，请你 重新 排查我们关注的 问题。
diff --git a/skills/prompt-193dd3cd-2722-413b-b88c-12c2af645f80/agents/openai.yaml b/skills/prompt-193dd3cd-2722-413b-b88c-12c2af645f80/agents/openai.yaml
new file mode 100644
index 0000000..fa510bd
--- /dev/null
+++ b/skills/prompt-193dd3cd-2722-413b-b88c-12c2af645f80/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "使用 agent-browser 排查运行时状态"
+  short_description: "使用 agent-browser 排查运行时状态"
+  default_prompt: "Use $prompt-193dd3cd-2722-413b-b88c-12c2af645f80."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-2793a3a4-310f-40c8-ba5d-bc7f5c1cafd7/SKILL.md b/skills/prompt-2793a3a4-310f-40c8-ba5d-bc7f5c1cafd7/SKILL.md
new file mode 100644
index 0000000..c380b4c
--- /dev/null
+++ b/skills/prompt-2793a3a4-310f-40c8-ba5d-bc7f5c1cafd7/SKILL.md
@@ -0,0 +1,27 @@
+---
+name: "prompt-2793a3a4-310f-40c8-ba5d-bc7f5c1cafd7"
+description: "状态机正确性"
+metadata:
+  short-description: "状态机正确性"
+---
+
+# 状态机正确性
+
+高度抽象规约（公式级）
+任何副作用（发请求/写缓存/写 store/patch UI）都必须是一个纯函数式映射：Effect = f(ActorIdentity, IntentId, TargetIdentity, Payload)
+禁止让 Effect 依赖任何隐式上下文：currentXxx/globalXxx/数组下标对齐/默认回退对象/闭包里过期的 selectedXxx；因为这些在“列表重排 + 异步回写 + 流式并发”下会漂移，导致“写对了 payload，但写错了容器”。
+落地要点（必须同时满足）
+ActorIdentity（我是谁/谁在做）：谁发起这次 effect（组件/Hook/Stream/Workspace），用于界定权限与并发域（如 workspaceId、agentKey/machineKey）。
+IntentId（我这次想做什么）：一次用户意图/事务的稳定编号（如 click/open 的 seq），用于丢弃过期回写。
+TargetIdentity（我对谁做）：被操作对象的最小不可歧义闭包（按场景至少包含：machineKey/agentId + projectId + bucket/filterKey + sessionId/cursor）。
+写入前校验：在真正 setQueryData/setState 前，二次校验 Actor/Intent/Target 仍匹配当前上下文；不匹配就丢弃/重取，不能“凑合写”。
+具体例子（对照）
+1) TanStack Query 列表/分页
+正确：queryKey 与返回数据都绑定 machineKey+projectId+bucket+filterKey(+cursor)；渲染/回写前校验这些字段一致。
+错误：useQueries 用 i * buckets + j 取结果，projects 列表一重排就把 A 项目的结果读成 B 项目的。
+2) SSE/Stream patch
+正确：patch 必须携带 agentId/machineKey + projectId + sessionId，并且只允许更新对应 identity 的 queryKey 容器。
+错误：只带 sessionId 就去更新“当前项目的 sessions 列表”（TargetIdentity 缺失）。
+3) UI 选择态（跨 await）
+正确：点击会话生成 intentSeq，await 返回后如果 intentSeq 已变化则不写入（IntentId 防过期回写）；并且写入的目标必须是同一个 agentId+projectId+sessionId。
+错误：await 回来直接 setSelectedSession(x)，同时依赖“当前 selectedProject”作为目标（隐式 current 指针）。
diff --git a/skills/prompt-2793a3a4-310f-40c8-ba5d-bc7f5c1cafd7/agents/openai.yaml b/skills/prompt-2793a3a4-310f-40c8-ba5d-bc7f5c1cafd7/agents/openai.yaml
new file mode 100644
index 0000000..2d1858c
--- /dev/null
+++ b/skills/prompt-2793a3a4-310f-40c8-ba5d-bc7f5c1cafd7/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "状态机正确性"
+  short_description: "状态机正确性"
+  default_prompt: "Use $prompt-2793a3a4-310f-40c8-ba5d-bc7f5c1cafd7."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-2d53cebd-afd4-4d35-94e9-74436da3148a/SKILL.md b/skills/prompt-2d53cebd-afd4-4d35-94e9-74436da3148a/SKILL.md
new file mode 100644
index 0000000..a8dad69
--- /dev/null
+++ b/skills/prompt-2d53cebd-afd4-4d35-94e9-74436da3148a/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-2d53cebd-afd4-4d35-94e9-74436da3148a"
+description: "关注收束"
+metadata:
+  short-description: "关注收束"
+---
+
+# 关注收束
+
+关注收束，如果当前实现可以复用一些东西，优先复用
diff --git a/skills/prompt-2d53cebd-afd4-4d35-94e9-74436da3148a/agents/openai.yaml b/skills/prompt-2d53cebd-afd4-4d35-94e9-74436da3148a/agents/openai.yaml
new file mode 100644
index 0000000..e95a2ae
--- /dev/null
+++ b/skills/prompt-2d53cebd-afd4-4d35-94e9-74436da3148a/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "关注收束"
+  short_description: "关注收束"
+  default_prompt: "Use $prompt-2d53cebd-afd4-4d35-94e9-74436da3148a."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-2eaed145-d789-4b27-93b9-8ea990830b3a/SKILL.md b/skills/prompt-2eaed145-d789-4b27-93b9-8ea990830b3a/SKILL.md
new file mode 100644
index 0000000..d381fe9
--- /dev/null
+++ b/skills/prompt-2eaed145-d789-4b27-93b9-8ea990830b3a/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-2eaed145-d789-4b27-93b9-8ea990830b3a"
+description: "提示词模板位置"
+metadata:
+  short-description: "提示词模板位置"
+---
+
+# 提示词模板位置
+
+dever项目所有提示词模板都应该放在独立的ts源码文件中，这样分离的更清楚，更好做提示词版本管理
diff --git a/skills/prompt-2eaed145-d789-4b27-93b9-8ea990830b3a/agents/openai.yaml b/skills/prompt-2eaed145-d789-4b27-93b9-8ea990830b3a/agents/openai.yaml
new file mode 100644
index 0000000..15fea0c
--- /dev/null
+++ b/skills/prompt-2eaed145-d789-4b27-93b9-8ea990830b3a/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "提示词模板位置"
+  short_description: "提示词模板位置"
+  default_prompt: "Use $prompt-2eaed145-d789-4b27-93b9-8ea990830b3a."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-345530e6-2736-42c3-9d4e-da5f14b8b8cb/SKILL.md b/skills/prompt-345530e6-2736-42c3-9d4e-da5f14b8b8cb/SKILL.md
new file mode 100644
index 0000000..b8f8bf8
--- /dev/null
+++ b/skills/prompt-345530e6-2736-42c3-9d4e-da5f14b8b8cb/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-345530e6-2736-42c3-9d4e-da5f14b8b8cb"
+description: "长期主义"
+metadata:
+  short-description: "长期主义"
+---
+
+# 长期主义
+
+长期主义，解决一个问题时，要往上递归思考根因，想一下能不能做让未来更复利的事情，宁愿早期breakchange，也不要长期埋雷，做简单的缝缝补补
diff --git a/skills/prompt-345530e6-2736-42c3-9d4e-da5f14b8b8cb/agents/openai.yaml b/skills/prompt-345530e6-2736-42c3-9d4e-da5f14b8b8cb/agents/openai.yaml
new file mode 100644
index 0000000..7237bab
--- /dev/null
+++ b/skills/prompt-345530e6-2736-42c3-9d4e-da5f14b8b8cb/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "长期主义"
+  short_description: "长期主义"
+  default_prompt: "Use $prompt-345530e6-2736-42c3-9d4e-da5f14b8b8cb."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-566905c8-0ad8-4d7e-857a-1c38ac7e54ca/SKILL.md b/skills/prompt-566905c8-0ad8-4d7e-857a-1c38ac7e54ca/SKILL.md
new file mode 100644
index 0000000..b9417ca
--- /dev/null
+++ b/skills/prompt-566905c8-0ad8-4d7e-857a-1c38ac7e54ca/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-566905c8-0ad8-4d7e-857a-1c38ac7e54ca"
+description: "更改前需要用户 review"
+metadata:
+  short-description: "更改前需要用户 review"
+---
+
+# 更改前需要用户 review
+
+要执行内容改动，需要先输出计划，待用户 review 并回复后执行
diff --git a/skills/prompt-566905c8-0ad8-4d7e-857a-1c38ac7e54ca/agents/openai.yaml b/skills/prompt-566905c8-0ad8-4d7e-857a-1c38ac7e54ca/agents/openai.yaml
new file mode 100644
index 0000000..10dda57
--- /dev/null
+++ b/skills/prompt-566905c8-0ad8-4d7e-857a-1c38ac7e54ca/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "更改前需要用户 review"
+  short_description: "更改前需要用户 review"
+  default_prompt: "Use $prompt-566905c8-0ad8-4d7e-857a-1c38ac7e54ca."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-5e80deb4-c278-4424-a0f4-a3df4f3443d8/SKILL.md b/skills/prompt-5e80deb4-c278-4424-a0f4-a3df4f3443d8/SKILL.md
new file mode 100644
index 0000000..c699703
--- /dev/null
+++ b/skills/prompt-5e80deb4-c278-4424-a0f4-a3df4f3443d8/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-5e80deb4-c278-4424-a0f4-a3df4f3443d8"
+description: "变更简洁重设计"
+metadata:
+  short-description: "变更简洁重设计"
+---
+
+# 变更简洁重设计
+
+变更不要像修补丁一样增量修改，每次补一块，要考虑尽量的复用，必要时重新设计，来达到更简洁的结构，次要的才是说让变化比较少，我们宁愿breakchange，也不要留下丑陋冗余的代码结构
diff --git a/skills/prompt-5e80deb4-c278-4424-a0f4-a3df4f3443d8/agents/openai.yaml b/skills/prompt-5e80deb4-c278-4424-a0f4-a3df4f3443d8/agents/openai.yaml
new file mode 100644
index 0000000..291eaad
--- /dev/null
+++ b/skills/prompt-5e80deb4-c278-4424-a0f4-a3df4f3443d8/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "变更简洁重设计"
+  short_description: "变更简洁重设计"
+  default_prompt: "Use $prompt-5e80deb4-c278-4424-a0f4-a3df4f3443d8."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-615e1231-fe33-47f8-bf35-29fdf3766d98/SKILL.md b/skills/prompt-615e1231-fe33-47f8-bf35-29fdf3766d98/SKILL.md
new file mode 100644
index 0000000..63fbb03
--- /dev/null
+++ b/skills/prompt-615e1231-fe33-47f8-bf35-29fdf3766d98/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-615e1231-fe33-47f8-bf35-29fdf3766d98"
+description: "悬浮菜单组件复用"
+metadata:
+  short-description: "悬浮菜单组件复用"
+---
+
+# 悬浮菜单组件复用
+
+组件复用，悬浮菜单，我觉得是完全可以复用一个的，现在出现在 右键菜单，会话选择模型，等地方，其他的你也得找，得收束成一套原始组件，这样代码冗余就小很多；决策者请定位已有核心组件，并逐步把大家收束到一起
diff --git a/skills/prompt-615e1231-fe33-47f8-bf35-29fdf3766d98/agents/openai.yaml b/skills/prompt-615e1231-fe33-47f8-bf35-29fdf3766d98/agents/openai.yaml
new file mode 100644
index 0000000..aea2244
--- /dev/null
+++ b/skills/prompt-615e1231-fe33-47f8-bf35-29fdf3766d98/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "悬浮菜单组件复用"
+  short_description: "悬浮菜单组件复用"
+  default_prompt: "Use $prompt-615e1231-fe33-47f8-bf35-29fdf3766d98."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-7ae16163-92c9-4fde-a74f-7c61eddd62f2/SKILL.md b/skills/prompt-7ae16163-92c9-4fde-a74f-7c61eddd62f2/SKILL.md
new file mode 100644
index 0000000..561a4f6
--- /dev/null
+++ b/skills/prompt-7ae16163-92c9-4fde-a74f-7c61eddd62f2/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-7ae16163-92c9-4fde-a74f-7c61eddd62f2"
+description: "dever_canvas仅做参考"
+metadata:
+  short-description: "dever_canvas仅做参考"
+---
+
+# dever_canvas仅做参考
+
+dever_canvas 那一套是给你参考的，不是拿来直接用的
diff --git a/skills/prompt-7ae16163-92c9-4fde-a74f-7c61eddd62f2/agents/openai.yaml b/skills/prompt-7ae16163-92c9-4fde-a74f-7c61eddd62f2/agents/openai.yaml
new file mode 100644
index 0000000..4b8c732
--- /dev/null
+++ b/skills/prompt-7ae16163-92c9-4fde-a74f-7c61eddd62f2/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "dever_canvas仅做参考"
+  short_description: "dever_canvas仅做参考"
+  default_prompt: "Use $prompt-7ae16163-92c9-4fde-a74f-7c61eddd62f2."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-8c5cc431-635c-4c94-9deb-a502e77160eb/SKILL.md b/skills/prompt-8c5cc431-635c-4c94-9deb-a502e77160eb/SKILL.md
new file mode 100644
index 0000000..f2b1ec4
--- /dev/null
+++ b/skills/prompt-8c5cc431-635c-4c94-9deb-a502e77160eb/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-8c5cc431-635c-4c94-9deb-a502e77160eb"
+description: "关注 dever_yew 开发"
+metadata:
+  short-description: "关注 dever_yew 开发"
+---
+
+# 关注 dever_yew 开发
+
+目前 dever 项目 使用和开发的 UI 界面是由 dever_yew 提供的，原 react 实现 dever_ui 目前是历史工程，不要改动，仅做参考
diff --git a/skills/prompt-8c5cc431-635c-4c94-9deb-a502e77160eb/agents/openai.yaml b/skills/prompt-8c5cc431-635c-4c94-9deb-a502e77160eb/agents/openai.yaml
new file mode 100644
index 0000000..8d3b586
--- /dev/null
+++ b/skills/prompt-8c5cc431-635c-4c94-9deb-a502e77160eb/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "关注 dever_yew 开发"
+  short_description: "关注 dever_yew 开发"
+  default_prompt: "Use $prompt-8c5cc431-635c-4c94-9deb-a502e77160eb."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-a7fb4e43-d1eb-4739-93b3-646d7a1c072c/SKILL.md b/skills/prompt-a7fb4e43-d1eb-4739-93b3-646d7a1c072c/SKILL.md
new file mode 100644
index 0000000..6464ddb
--- /dev/null
+++ b/skills/prompt-a7fb4e43-d1eb-4739-93b3-646d7a1c072c/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-a7fb4e43-d1eb-4739-93b3-646d7a1c072c"
+description: "对话信息对接参考 codex 源码"
+metadata:
+  short-description: "对话信息对接参考 codex 源码"
+---
+
+# 对话信息对接参考 codex 源码
+
+对话信息对接参考 codex 源码，工程内 attic/codex 存放了 codex cli 的源码，对接 app-server 等 codex app-server 给予的能力对接参考该工程代码
diff --git a/skills/prompt-a7fb4e43-d1eb-4739-93b3-646d7a1c072c/agents/openai.yaml b/skills/prompt-a7fb4e43-d1eb-4739-93b3-646d7a1c072c/agents/openai.yaml
new file mode 100644
index 0000000..a8ca1af
--- /dev/null
+++ b/skills/prompt-a7fb4e43-d1eb-4739-93b3-646d7a1c072c/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "对话信息对接参考 codex 源码"
+  short_description: "对话信息对接参考 codex 源码"
+  default_prompt: "Use $prompt-a7fb4e43-d1eb-4739-93b3-646d7a1c072c."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-ac42abf9-6df8-4539-99c7-e402e905a03b/SKILL.md b/skills/prompt-ac42abf9-6df8-4539-99c7-e402e905a03b/SKILL.md
new file mode 100644
index 0000000..6f96d9c
--- /dev/null
+++ b/skills/prompt-ac42abf9-6df8-4539-99c7-e402e905a03b/SKILL.md
@@ -0,0 +1,15 @@
+---
+name: "prompt-ac42abf9-6df8-4539-99c7-e402e905a03b"
+description: "逻辑收束到agent"
+metadata:
+  short-description: "逻辑收束到agent"
+---
+
+# 逻辑收束到agent
+
+规约：Manager/Agent 边界（强制收束）
+
+前端只允许访问 manager：所有 API 必须走 /api/router/:agentId/...（local 也一样）。
+manager 只负责：请求转发（router）、agent registry、（未来）登录鉴权、（可选）静态资源托管；严禁在 manager 实现任何业务能力与持久化。
+大部分“后端能力 + 数据落盘”（projects/sessions/chat/fs/git/terminal/notifications/uiState/uiWorkspaces/uiDock/uiScroll 等）必须在 agent 内实现与持久化；manager 不得读写 .dever/agent_data.json 或任何业务数据文件。
+发现 manager 出现新增 /api/* 实现模块或 store/JSON 持久化代码，一律视为架构违规：要么迁到 agent，要么删除并改为转发。
diff --git a/skills/prompt-ac42abf9-6df8-4539-99c7-e402e905a03b/agents/openai.yaml b/skills/prompt-ac42abf9-6df8-4539-99c7-e402e905a03b/agents/openai.yaml
new file mode 100644
index 0000000..1d669e7
--- /dev/null
+++ b/skills/prompt-ac42abf9-6df8-4539-99c7-e402e905a03b/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "逻辑收束到agent"
+  short_description: "逻辑收束到agent"
+  default_prompt: "Use $prompt-ac42abf9-6df8-4539-99c7-e402e905a03b."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-ae9ff67b-09d8-4848-bbde-aac1fb6e1315/SKILL.md b/skills/prompt-ae9ff67b-09d8-4848-bbde-aac1fb6e1315/SKILL.md
new file mode 100644
index 0000000..b0743b2
--- /dev/null
+++ b/skills/prompt-ae9ff67b-09d8-4848-bbde-aac1fb6e1315/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-ae9ff67b-09d8-4848-bbde-aac1fb6e1315"
+description: "mvp"
+metadata:
+  short-description: "mvp"
+---
+
+# mvp
+
+dever_doc/mvp/target.md  我移动到了这里，作为我们的工作目标，现在我们就开始工作，过程记录按照步骤记录在 mvp文件夹里就行，合理拆分成文件
diff --git a/skills/prompt-ae9ff67b-09d8-4848-bbde-aac1fb6e1315/agents/openai.yaml b/skills/prompt-ae9ff67b-09d8-4848-bbde-aac1fb6e1315/agents/openai.yaml
new file mode 100644
index 0000000..86a71f3
--- /dev/null
+++ b/skills/prompt-ae9ff67b-09d8-4848-bbde-aac1fb6e1315/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "mvp"
+  short_description: "mvp"
+  default_prompt: "Use $prompt-ae9ff67b-09d8-4848-bbde-aac1fb6e1315."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/prompt-f118ab91-390b-48e2-a962-3abe4d54211e/SKILL.md b/skills/prompt-f118ab91-390b-48e2-a962-3abe4d54211e/SKILL.md
new file mode 100644
index 0000000..8901c6e
--- /dev/null
+++ b/skills/prompt-f118ab91-390b-48e2-a962-3abe4d54211e/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: "prompt-f118ab91-390b-48e2-a962-3abe4d54211e"
+description: "完美主义"
+metadata:
+  short-description: "完美主义"
+---
+
+# 完美主义
+
+完成之前，核对下有没有问题，设计上有没有不完善，尽量一次性做到完美；完美不代表复杂，完美是刚好在简单和复杂直接达到平衡
diff --git a/skills/prompt-f118ab91-390b-48e2-a962-3abe4d54211e/agents/openai.yaml b/skills/prompt-f118ab91-390b-48e2-a962-3abe4d54211e/agents/openai.yaml
new file mode 100644
index 0000000..9600439
--- /dev/null
+++ b/skills/prompt-f118ab91-390b-48e2-a962-3abe4d54211e/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "完美主义"
+  short_description: "完美主义"
+  default_prompt: "Use $prompt-f118ab91-390b-48e2-a962-3abe4d54211e."
+policy:
+  allow_implicit_invocation: false
diff --git a/skills/rs-skill-smoke-09e1daf7/SKILL.md b/skills/rs-skill-smoke-09e1daf7/SKILL.md
new file mode 100644
index 0000000..eb9b22f
--- /dev/null
+++ b/skills/rs-skill-smoke-09e1daf7/SKILL.md
@@ -0,0 +1,8 @@
+---
+name: rs-skill-smoke-09e1daf7
+description: Used by project_contract_smoke.
+---
+
+# RS Skill Smoke
+
+Used by project_contract_smoke.
diff --git a/skills/rs-skill-smoke-529efbc9/SKILL.md b/skills/rs-skill-smoke-529efbc9/SKILL.md
new file mode 100644
index 0000000..85c8a95
--- /dev/null
+++ b/skills/rs-skill-smoke-529efbc9/SKILL.md
@@ -0,0 +1,8 @@
+---
+name: rs-skill-smoke-529efbc9
+description: Used by project_contract_smoke.
+---
+
+# rs-skill-smoke-529efbc9
+
+Used by project_contract_smoke.
diff --git a/skills/rs-skill-smoke-cde1029f/SKILL.md b/skills/rs-skill-smoke-cde1029f/SKILL.md
new file mode 100644
index 0000000..4611722
--- /dev/null
+++ b/skills/rs-skill-smoke-cde1029f/SKILL.md
@@ -0,0 +1,8 @@
+---
+name: rs-skill-smoke-cde1029f
+description: Used by project_contract_smoke.
+---
+
+# RS Skill Smoke
+
+Used by project_contract_smoke.
diff --git a/skills/skill-creator/SKILL.md b/skills/skill-creator/SKILL.md
new file mode 100644
index 0000000..57f4e58
--- /dev/null
+++ b/skills/skill-creator/SKILL.md
@@ -0,0 +1,416 @@
+---
+name: skill-creator
+description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations.
+metadata:
+  short-description: Create or update a skill
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained folders that extend Codex's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform Codex from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share the context window with everything else Codex needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
+
+**Default assumption: Codex is already very smart.** Only add context Codex doesn't already have. Challenge each piece of information: "Does Codex really need this explanation?" and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Set Appropriate Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability:
+
+**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
+
+**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
+
+**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
+
+Think of Codex as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
+
+### Protect Validation Integrity
+
+You may use subagents during iteration to validate whether a skill works on realistic tasks or whether a suspected problem is real. This is most useful when you want an independent pass on the skill's behavior, outputs, or failure modes after a revision.  Only do this when it is possible to start new subagents.
+
+When using subagents for validation, treat that as an evaluation surface. The goal is to learn whether the skill generalizes, not whether another agent can reconstruct the answer from leaked context.
+
+Prefer raw artifacts such as example prompts, outputs, diffs, logs, or traces. Give the minimum task-local context needed to perform the validation. Avoid passing the intended answer, suspected bug, intended fix, or your prior conclusions unless the validation explicitly requires them.
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   └── description: (required)
+│   └── Markdown instructions (required)
+├── agents/ (recommended)
+│   └── openai.yaml - UI metadata for skill lists and chips
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation intended to be loaded into context as needed
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+Every SKILL.md consists of:
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Codex reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
+
+#### Agents metadata (recommended)
+
+- UI-facing metadata for skill lists and chips
+- Read references/openai_yaml.md before generating values and follow its descriptions and constraints
+- Create: human-facing `display_name`, `short_description`, and `default_prompt` by reading the skill
+- Generate deterministically by passing the values as `--interface key=value` to `scripts/generate_openai_yaml.py` or `scripts/init_skill.py`
+- On updates: validate `agents/openai.yaml` still matches SKILL.md; regenerate if stale
+- Only include other optional interface fields (icons, brand color) if explicitly provided
+- See references/openai_yaml.md for field definitions and examples
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+- **Note**: Scripts may still need to be read by Codex for patching or environment-specific adjustments
+
+##### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context to inform Codex's process and thinking.
+
+- **When to include**: For documentation that Codex should reference while working
+- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
+- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
+- **Benefits**: Keeps SKILL.md lean, loaded only when Codex determines it's needed
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output Codex produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
+- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
+- **Benefits**: Separates output resources from documentation, enables Codex to use files without loading them into context
+
+#### What to Not Include in a Skill
+
+A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
+
+- README.md
+- INSTALLATION_GUIDE.md
+- QUICK_REFERENCE.md
+- CHANGELOG.md
+- etc.
+
+The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
+
+### Progressive Disclosure Design Principle
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by Codex (Unlimited because scripts can be executed without reading into context window)
+
+#### Progressive Disclosure Patterns
+
+Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
+
+**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+
+## Quick start
+
+Extract text with pdfplumber:
+[code example]
+
+## Advanced features
+
+- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
+- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
+- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
+```
+
+Codex loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
+
+**Pattern 2: Domain-specific organization**
+
+For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+    ├── finance.md (revenue, billing metrics)
+    ├── sales.md (opportunities, pipeline)
+    ├── product.md (API usage, features)
+    └── marketing.md (campaigns, attribution)
+```
+
+When a user asks about sales metrics, Codex only reads sales.md.
+
+Similarly, for skills supporting multiple frameworks or variants, organize by variant:
+
+```
+cloud-deploy/
+├── SKILL.md (workflow + provider selection)
+└── references/
+    ├── aws.md (AWS deployment patterns)
+    ├── gcp.md (GCP deployment patterns)
+    └── azure.md (Azure deployment patterns)
+```
+
+When the user chooses AWS, Codex only reads aws.md.
+
+**Pattern 3: Conditional details**
+
+Show basic content, link to advanced content:
+
+```markdown
+# DOCX Processing
+
+## Creating documents
+
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+
+## Editing documents
+
+For simple edits, modify the XML directly.
+
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+**For OOXML details**: See [OOXML.md](OOXML.md)
+```
+
+Codex reads REDLINING.md or OOXML.md only when the user needs those features.
+
+**Important guidelines:**
+
+- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
+- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Codex can see the full scope when previewing.
+
+## Skill Creation Process
+
+Skill creation involves these steps:
+
+1. Understand the skill with concrete examples
+2. Plan reusable skill contents (scripts, references, assets)
+3. Initialize the skill (run init_skill.py)
+4. Edit the skill (implement resources and write SKILL.md)
+5. Validate the skill (run quick_validate.py)
+6. Iterate based on real usage and forward-test complex skills.
+
+Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
+
+### Skill Naming
+
+- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" -> `plan-mode`).
+- When generating names, generate a name under 64 characters (letters, digits, hyphens).
+- Prefer short, verb-led phrases that describe the action.
+- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).
+- Name the skill folder exactly after the skill name.
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
+
+To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+
+For example, when building an image-editor skill, relevant questions include:
+
+- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
+- "Can you give some examples of how this skill would be used?"
+- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
+- "What would a user say that should trigger this skill?"
+- "Where should I create this skill? If you do not have a preference, I will place it in `$CODEX_HOME/skills` (or `~/.codex/skills` when `CODEX_HOME` is unset) so Codex can discover it automatically."
+
+To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+
+Conclude this step when there is a clear sense of the functionality the skill should support.
+
+### Step 2: Planning the Reusable Skill Contents
+
+To turn concrete examples into an effective skill, analyze each example by:
+
+1. Considering how to execute on the example from scratch
+2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
+
+Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
+
+1. Rotating a PDF requires re-writing the same code each time
+2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
+
+Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
+
+1. Writing a frontend webapp requires the same boilerplate HTML/React each time
+2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
+
+Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
+
+1. Querying BigQuery requires re-discovering the table schemas and relationships each time
+2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
+
+To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
+
+### Step 3: Initializing the Skill
+
+At this point, it is time to actually create the skill.
+
+Skip this step only if the skill being developed already exists. In this case, continue to the next step.
+
+Before running `init_skill.py`, ask where the user wants the skill created. If they do not specify a location, default to `$CODEX_HOME/skills`; when `CODEX_HOME` is unset, fall back to `~/.codex/skills` so the skill is auto-discovered.
+
+When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
+
+Usage:
+
+```bash
+scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
+```
+
+Examples:
+
+```bash
+scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills"
+scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills" --resources scripts,references
+scripts/init_skill.py my-skill --path ~/work/skills --resources scripts --examples
+```
+
+The script:
+
+- Creates the skill directory at the specified path
+- Generates a SKILL.md template with proper frontmatter and TODO placeholders
+- Creates `agents/openai.yaml` using agent-generated `display_name`, `short_description`, and `default_prompt` passed via `--interface key=value`
+- Optionally creates resource directories based on `--resources`
+- Optionally adds example files when `--examples` is set
+
+After initialization, customize the SKILL.md and add resources as needed. If you used `--examples`, replace or delete placeholder files.
+
+Generate `display_name`, `short_description`, and `default_prompt` by reading the skill, then pass them as `--interface key=value` to `init_skill.py` or regenerate with:
+
+```bash
+scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value
+```
+
+Only include other optional interface fields when the user explicitly provides them. For full field descriptions and examples, see references/openai_yaml.md.
+
+### Step 4: Edit the Skill
+
+When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Codex to use. Include information that would be beneficial and non-obvious to Codex. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Codex instance execute these tasks more effectively.
+
+After substantial revisions, or if the skill is particularly tricky, you should use subagents to forward-test the skill on realistic tasks or artifacts. When doing so, pass the artifact under validation rather than your diagnosis of what is wrong, and keep the prompt generic enough that success depends on transferable reasoning rather than hidden ground truth.
+
+#### Start with Reusable Skill Contents
+
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+
+Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
+
+If you used `--examples`, delete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.
+
+#### Update SKILL.md
+
+**Writing Guidelines:** Always use imperative/infinitive form.
+
+##### Frontmatter
+
+Write the YAML frontmatter with `name` and `description`:
+
+- `name`: The skill name
+- `description`: This is the primary triggering mechanism for your skill, and helps Codex understand when to use the skill.
+  - Include both what the Skill does and specific triggers/contexts for when to use it.
+  - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Codex.
+  - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Codex needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+
+Do not include any other fields in YAML frontmatter.
+
+##### Body
+
+Write instructions for using the skill and its bundled resources.
+
+### Step 5: Validate the Skill
+
+Once development of the skill is complete, validate the skill folder to catch basic issues early:
+
+```bash
+scripts/quick_validate.py <path/to/skill-folder>
+```
+
+The validation script checks YAML frontmatter format, required fields, and naming rules. If validation fails, fix the reported issues and run the command again.
+
+### Step 6: Iterate
+
+After testing the skill, you may detect the skill is complex enough that it requires forward-testing; or users may request improvements.
+
+User testing often this happens right after using the skill, with fresh context of how the skill performed.
+
+**Forward-testing and iteration workflow:**
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again
+5. Forward-test if it is reasonable and appropriate
+
+## Forward-testing
+
+To forward-test, launch subagents as a way to stress test the skill with minimal context.
+Subagents should *not* know that they are being asked to test the skill.  They should be treated as
+an agent asked to perform a task by the user.  Prompts to subagents should look like:
+  `Use $skill-x at /path/to/skill-x to solve problem y`
+Not:
+  `Review the skill at /path/to/skill-x; pretend a user asks you to...`
+
+Decision rule for forward-testing:
+  - Err on the side of forward-testing
+  - Ask for approval if you think there's a risk that forward-testing would:
+    * take a long time,
+    * require additional approvals from the user, or
+    * modify live production systems
+
+  In these cases, show the user your proposed prompt and request (1) a yes/no decision, and
+  (2) any suggested modifictions.
+
+Considerations when forward-testing:
+   - use fresh threads for independent passes
+   - pass the skill, and a request in a similar way the user would.
+   - pass raw artifacts, not your conclusions
+   - avoid showing expected answers or intended fixes
+   - rebuild context from source artifacts after each iteration
+   - review the subagent's output and reasoning and emitted artifacts
+   - avoid leaving artifacts the agent can find on disk between iterations;
+     clean up subagents' artifacts to avoid additional contamination.
+
+If forward-testing only succeeds when subagents see leaked context, tighten the skill or the
+forward-testing setup before trusting the result.
diff --git a/skills/skill-creator/agents/openai.yaml b/skills/skill-creator/agents/openai.yaml
new file mode 100644
index 0000000..3095c60
--- /dev/null
+++ b/skills/skill-creator/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Skill Creator"
+  short_description: "Create or update a skill"
+  icon_small: "./assets/skill-creator-small.svg"
+  icon_large: "./assets/skill-creator.png"
diff --git a/skills/skill-creator/assets/skill-creator-small.svg b/skills/skill-creator/assets/skill-creator-small.svg
new file mode 100644
index 0000000..c6e4f67
--- /dev/null
+++ b/skills/skill-creator/assets/skill-creator-small.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 20 20">
+  <path fill="#0D0D0D" d="M12.03 4.113a3.612 3.612 0 0 1 5.108 5.108l-6.292 6.29c-.324.324-.56.561-.791.752l-.235.176c-.205.14-.422.261-.65.36l-.229.093a4.136 4.136 0 0 1-.586.16l-.764.134-2.394.4c-.142.024-.294.05-.423.06-.098.007-.232.01-.378-.026l-.149-.05a1.081 1.081 0 0 1-.521-.474l-.046-.093a1.104 1.104 0 0 1-.075-.527c.01-.129.035-.28.06-.422l.398-2.394c.1-.602.162-.987.295-1.35l.093-.23c.1-.228.22-.445.36-.65l.176-.235c.19-.232.428-.467.751-.79l6.292-6.292Zm-5.35 7.232c-.35.35-.534.535-.66.688l-.11.147a2.67 2.67 0 0 0-.24.433l-.062.154c-.08.22-.124.462-.232 1.112l-.398 2.394-.001.001h.003l2.393-.399.717-.126a2.63 2.63 0 0 0 .394-.105l.154-.063a2.65 2.65 0 0 0 .433-.24l.147-.11c.153-.126.339-.31.688-.66l4.988-4.988-3.227-3.226-4.987 4.988Zm9.517-6.291a2.281 2.281 0 0 0-3.225 0l-.364.362 3.226 3.227.363-.364c.89-.89.89-2.334 0-3.225ZM4.583 1.783a.3.3 0 0 1 .294.241c.117.585.347 1.092.707 1.48.357.385.859.668 1.549.783a.3.3 0 0 1 0 .592c-.69.115-1.192.398-1.549.783-.315.34-.53.77-.657 1.265l-.05.215a.3.3 0 0 1-.588 0c-.117-.585-.347-1.092-.707-1.48-.357-.384-.859-.668-1.549-.783a.3.3 0 0 1 0-.592c.69-.115 1.192-.398 1.549-.783.36-.388.59-.895.707-1.48l.015-.05a.3.3 0 0 1 .279-.19Z"/>
+</svg>
diff --git a/skills/skill-creator/assets/skill-creator.png b/skills/skill-creator/assets/skill-creator.png
new file mode 100644
index 0000000..4f3d6d8
Binary files /dev/null and b/skills/skill-creator/assets/skill-creator.png differ
diff --git a/skills/skill-creator/license.txt b/skills/skill-creator/license.txt
new file mode 100644
index 0000000..d645695
--- /dev/null
+++ b/skills/skill-creator/license.txt
@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/skills/skill-creator/references/openai_yaml.md b/skills/skill-creator/references/openai_yaml.md
new file mode 100644
index 0000000..90f9e8e
--- /dev/null
+++ b/skills/skill-creator/references/openai_yaml.md
@@ -0,0 +1,49 @@
+# openai.yaml fields (full example + descriptions)
+
+`agents/openai.yaml` is an extended, product-specific config intended for the machine/harness to read, not the agent. Other product-specific config can also live in the `agents/` folder.
+
+## Full example
+
+```yaml
+interface:
+  display_name: "Optional user-facing name"
+  short_description: "Optional user-facing description"
+  icon_small: "./assets/small-400px.png"
+  icon_large: "./assets/large-logo.svg"
+  brand_color: "#3B82F6"
+  default_prompt: "Optional surrounding prompt to use the skill with"
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "github"
+      description: "GitHub MCP server"
+      transport: "streamable_http"
+      url: "https://api.githubcopilot.com/mcp/"
+
+policy:
+  allow_implicit_invocation: true
+```
+
+## Field descriptions and constraints
+
+Top-level constraints:
+
+- Quote all string values.
+- Keep keys unquoted.
+- For `interface.default_prompt`: generate a helpful, short (typically 1 sentence) example starting prompt based on the skill. It must explicitly mention the skill as `$skill-name` (e.g., "Use $skill-name-here to draft a concise weekly status update.").
+
+- `interface.display_name`: Human-facing title shown in UI skill lists and chips.
+- `interface.short_description`: Human-facing short UI blurb (25–64 chars) for quick scanning.
+- `interface.icon_small`: Path to a small icon asset (relative to skill dir). Default to `./assets/` and place icons in the skill's `assets/` folder.
+- `interface.icon_large`: Path to a larger logo asset (relative to skill dir). Default to `./assets/` and place icons in the skill's `assets/` folder.
+- `interface.brand_color`: Hex color used for UI accents (e.g., badges).
+- `interface.default_prompt`: Default prompt snippet inserted when invoking the skill.
+- `dependencies.tools[].type`: Dependency category. Only `mcp` is supported for now.
+- `dependencies.tools[].value`: Identifier of the tool or dependency.
+- `dependencies.tools[].description`: Human-readable explanation of the dependency.
+- `dependencies.tools[].transport`: Connection type when `type` is `mcp`.
+- `dependencies.tools[].url`: MCP server URL when `type` is `mcp`.
+- `policy.allow_implicit_invocation`: When false, the skill is not injected into
+  the model context by default, but can still be invoked explicitly via `$skill`.
+  Defaults to true.
diff --git a/skills/skill-creator/scripts/generate_openai_yaml.py b/skills/skill-creator/scripts/generate_openai_yaml.py
new file mode 100644
index 0000000..3fd7405
--- /dev/null
+++ b/skills/skill-creator/scripts/generate_openai_yaml.py
@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""
+OpenAI YAML Generator - Creates agents/openai.yaml for a skill folder.
+
+Usage:
+    generate_openai_yaml.py <skill_dir> [--name <skill_name>] [--interface key=value]
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ACRONYMS = {
+    "GH",
+    "MCP",
+    "API",
+    "CI",
+    "CLI",
+    "LLM",
+    "PDF",
+    "PR",
+    "UI",
+    "URL",
+    "SQL",
+}
+
+BRANDS = {
+    "openai": "OpenAI",
+    "openapi": "OpenAPI",
+    "github": "GitHub",
+    "pagerduty": "PagerDuty",
+    "datadog": "DataDog",
+    "sqlite": "SQLite",
+    "fastapi": "FastAPI",
+}
+
+SMALL_WORDS = {"and", "or", "to", "up", "with"}
+
+ALLOWED_INTERFACE_KEYS = {
+    "display_name",
+    "short_description",
+    "icon_small",
+    "icon_large",
+    "brand_color",
+    "default_prompt",
+}
+
+
+def yaml_quote(value):
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+    return f'"{escaped}"'
+
+
+def format_display_name(skill_name):
+    words = [word for word in skill_name.split("-") if word]
+    formatted = []
+    for index, word in enumerate(words):
+        lower = word.lower()
+        upper = word.upper()
+        if upper in ACRONYMS:
+            formatted.append(upper)
+            continue
+        if lower in BRANDS:
+            formatted.append(BRANDS[lower])
+            continue
+        if index > 0 and lower in SMALL_WORDS:
+            formatted.append(lower)
+            continue
+        formatted.append(word.capitalize())
+    return " ".join(formatted)
+
+
+def generate_short_description(display_name):
+    description = f"Help with {display_name} tasks"
+
+    if len(description) < 25:
+        description = f"Help with {display_name} tasks and workflows"
+    if len(description) < 25:
+        description = f"Help with {display_name} tasks with guidance"
+
+    if len(description) > 64:
+        description = f"Help with {display_name}"
+    if len(description) > 64:
+        description = f"{display_name} helper"
+    if len(description) > 64:
+        description = f"{display_name} tools"
+    if len(description) > 64:
+        suffix = " helper"
+        max_name_length = 64 - len(suffix)
+        trimmed = display_name[:max_name_length].rstrip()
+        description = f"{trimmed}{suffix}"
+    if len(description) > 64:
+        description = description[:64].rstrip()
+
+    if len(description) < 25:
+        description = f"{description} workflows"
+        if len(description) > 64:
+            description = description[:64].rstrip()
+
+    return description
+
+
+def read_frontmatter_name(skill_dir):
+    skill_md = Path(skill_dir) / "SKILL.md"
+    if not skill_md.exists():
+        print(f"[ERROR] SKILL.md not found in {skill_dir}")
+        return None
+    content = skill_md.read_text()
+    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+    if not match:
+        print("[ERROR] Invalid SKILL.md frontmatter format.")
+        return None
+    frontmatter_text = match.group(1)
+
+    import yaml
+
+    try:
+        frontmatter = yaml.safe_load(frontmatter_text)
+    except yaml.YAMLError as exc:
+        print(f"[ERROR] Invalid YAML frontmatter: {exc}")
+        return None
+    if not isinstance(frontmatter, dict):
+        print("[ERROR] Frontmatter must be a YAML dictionary.")
+        return None
+    name = frontmatter.get("name", "")
+    if not isinstance(name, str) or not name.strip():
+        print("[ERROR] Frontmatter 'name' is missing or invalid.")
+        return None
+    return name.strip()
+
+
+def parse_interface_overrides(raw_overrides):
+    overrides = {}
+    optional_order = []
+    for item in raw_overrides:
+        if "=" not in item:
+            print(f"[ERROR] Invalid interface override '{item}'. Use key=value.")
+            return None, None
+        key, value = item.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if not key:
+            print(f"[ERROR] Invalid interface override '{item}'. Key is empty.")
+            return None, None
+        if key not in ALLOWED_INTERFACE_KEYS:
+            allowed = ", ".join(sorted(ALLOWED_INTERFACE_KEYS))
+            print(f"[ERROR] Unknown interface field '{key}'. Allowed: {allowed}")
+            return None, None
+        overrides[key] = value
+        if key not in ("display_name", "short_description") and key not in optional_order:
+            optional_order.append(key)
+    return overrides, optional_order
+
+
+def write_openai_yaml(skill_dir, skill_name, raw_overrides):
+    overrides, optional_order = parse_interface_overrides(raw_overrides)
+    if overrides is None:
+        return None
+
+    display_name = overrides.get("display_name") or format_display_name(skill_name)
+    short_description = overrides.get("short_description") or generate_short_description(display_name)
+
+    if not (25 <= len(short_description) <= 64):
+        print(
+            "[ERROR] short_description must be 25-64 characters "
+            f"(got {len(short_description)})."
+        )
+        return None
+
+    interface_lines = [
+        "interface:",
+        f"  display_name: {yaml_quote(display_name)}",
+        f"  short_description: {yaml_quote(short_description)}",
+    ]
+
+    for key in optional_order:
+        value = overrides.get(key)
+        if value is not None:
+            interface_lines.append(f"  {key}: {yaml_quote(value)}")
+
+    agents_dir = Path(skill_dir) / "agents"
+    agents_dir.mkdir(parents=True, exist_ok=True)
+    output_path = agents_dir / "openai.yaml"
+    output_path.write_text("\n".join(interface_lines) + "\n")
+    print(f"[OK] Created agents/openai.yaml")
+    return output_path
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Create agents/openai.yaml for a skill directory.",
+    )
+    parser.add_argument("skill_dir", help="Path to the skill directory")
+    parser.add_argument(
+        "--name",
+        help="Skill name override (defaults to SKILL.md frontmatter)",
+    )
+    parser.add_argument(
+        "--interface",
+        action="append",
+        default=[],
+        help="Interface override in key=value format (repeatable)",
+    )
+    args = parser.parse_args()
+
+    skill_dir = Path(args.skill_dir).resolve()
+    if not skill_dir.exists():
+        print(f"[ERROR] Skill directory not found: {skill_dir}")
+        sys.exit(1)
+    if not skill_dir.is_dir():
+        print(f"[ERROR] Path is not a directory: {skill_dir}")
+        sys.exit(1)
+
+    skill_name = args.name or read_frontmatter_name(skill_dir)
+    if not skill_name:
+        sys.exit(1)
+
+    result = write_openai_yaml(skill_dir, skill_name, args.interface)
+    if result:
+        sys.exit(0)
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/skills/skill-creator/scripts/init_skill.py b/skills/skill-creator/scripts/init_skill.py
new file mode 100644
index 0000000..69673ea
--- /dev/null
+++ b/skills/skill-creator/scripts/init_skill.py
@@ -0,0 +1,400 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+    init_skill.py <skill-name> --path <path> [--resources scripts,references,assets] [--examples] [--interface key=value]
+
+Examples:
+    init_skill.py my-new-skill --path skills/public
+    init_skill.py my-new-skill --path skills/public --resources scripts,references
+    init_skill.py my-api-helper --path skills/private --resources scripts --examples
+    init_skill.py custom-skill --path /custom/location
+    init_skill.py my-skill --path skills/public --interface short_description="Short UI label"
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from generate_openai_yaml import write_openai_yaml
+
+MAX_SKILL_NAME_LENGTH = 64
+ALLOWED_RESOURCES = {"scripts", "references", "assets"}
+
+SKILL_TEMPLATE = """---
+name: {skill_name}
+description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
+---
+
+# {skill_title}
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## Structuring This Skill
+
+[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
+
+**1. Workflow-Based** (best for sequential processes)
+- Works well when there are clear step-by-step procedures
+- Example: DOCX skill with "Workflow Decision Tree" -> "Reading" -> "Creating" -> "Editing"
+- Structure: ## Overview -> ## Workflow Decision Tree -> ## Step 1 -> ## Step 2...
+
+**2. Task-Based** (best for tool collections)
+- Works well when the skill offers different operations/capabilities
+- Example: PDF skill with "Quick Start" -> "Merge PDFs" -> "Split PDFs" -> "Extract Text"
+- Structure: ## Overview -> ## Quick Start -> ## Task Category 1 -> ## Task Category 2...
+
+**3. Reference/Guidelines** (best for standards or specifications)
+- Works well for brand guidelines, coding standards, or requirements
+- Example: Brand styling with "Brand Guidelines" -> "Colors" -> "Typography" -> "Features"
+- Structure: ## Overview -> ## Guidelines -> ## Specifications -> ## Usage...
+
+**4. Capabilities-Based** (best for integrated systems)
+- Works well when the skill provides multiple interrelated features
+- Example: Product Management with "Core Capabilities" -> numbered capability list
+- Structure: ## Overview -> ## Core Capabilities -> ### 1. Feature -> ### 2. Feature...
+
+Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
+
+Delete this entire "Structuring This Skill" section when done - it's just guidance.]
+
+## [TODO: Replace with the first main section based on chosen structure]
+
+[TODO: Add content here. See examples in existing skills:
+- Code samples for technical skills
+- Decision trees for complex workflows
+- Concrete examples with realistic user requests
+- References to scripts/templates/references as needed]
+
+## Resources (optional)
+
+Create only the resource directories this skill actually needs. Delete this section if no resources are required.
+
+### scripts/
+Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
+
+**Examples from other skills:**
+- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
+- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
+
+**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
+
+**Note:** Scripts may be executed without loading into context, but can still be read by Codex for patching or environment adjustments.
+
+### references/
+Documentation and reference material intended to be loaded into context to inform Codex's process and thinking.
+
+**Examples from other skills:**
+- Product management: `communication.md`, `context_building.md` - detailed workflow guides
+- BigQuery: API reference documentation and query examples
+- Finance: Schema documentation, company policies
+
+**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Codex should reference while working.
+
+### assets/
+Files not intended to be loaded into context, but rather used within the output Codex produces.
+
+**Examples from other skills:**
+- Brand styling: PowerPoint template files (.pptx), logo files
+- Frontend builder: HTML/React boilerplate project directories
+- Typography: Font files (.ttf, .woff2)
+
+**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
+
+---
+
+**Not every skill requires all three types of resources.**
+"""
+
+EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
+"""
+Example helper script for {skill_name}
+
+This is a placeholder script that can be executed directly.
+Replace with actual implementation or delete if not needed.
+
+Example real scripts from other skills:
+- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
+- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
+"""
+
+def main():
+    print("This is an example script for {skill_name}")
+    # TODO: Add actual script logic here
+    # This could be data processing, file conversion, API calls, etc.
+
+if __name__ == "__main__":
+    main()
+'''
+
+EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+Example real reference docs from other skills:
+- product-management/references/communication.md - Comprehensive guide for status updates
+- product-management/references/context_building.md - Deep-dive on gathering context
+- bigquery/references/ - API references and query examples
+
+## When Reference Docs Are Useful
+
+Reference docs are ideal for:
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content that's only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+- Rate limits
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+- Best practices
+"""
+
+EXAMPLE_ASSET = """# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
+
+Asset files are NOT intended to be loaded into context, but rather used within
+the output Codex produces.
+
+Example asset files from other skills:
+- Brand guidelines: logo.png, slides_template.pptx
+- Frontend builder: hello-world/ directory with HTML/React boilerplate
+- Typography: custom-font.ttf, font-family.woff2
+- Data: sample_data.csv, test_dataset.json
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg, .gif
+- Fonts: .ttf, .otf, .woff, .woff2
+- Boilerplate code: Project directories, starter files
+- Icons: .ico, .svg
+- Data files: .csv, .json, .xml, .yaml
+
+Note: This is a text placeholder. Actual assets can be any file type.
+"""
+
+
+def normalize_skill_name(skill_name):
+    """Normalize a skill name to lowercase hyphen-case."""
+    normalized = skill_name.strip().lower()
+    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
+    normalized = normalized.strip("-")
+    normalized = re.sub(r"-{2,}", "-", normalized)
+    return normalized
+
+
+def title_case_skill_name(skill_name):
+    """Convert hyphenated skill name to Title Case for display."""
+    return " ".join(word.capitalize() for word in skill_name.split("-"))
+
+
+def parse_resources(raw_resources):
+    if not raw_resources:
+        return []
+    resources = [item.strip() for item in raw_resources.split(",") if item.strip()]
+    invalid = sorted({item for item in resources if item not in ALLOWED_RESOURCES})
+    if invalid:
+        allowed = ", ".join(sorted(ALLOWED_RESOURCES))
+        print(f"[ERROR] Unknown resource type(s): {', '.join(invalid)}")
+        print(f"   Allowed: {allowed}")
+        sys.exit(1)
+    deduped = []
+    seen = set()
+    for resource in resources:
+        if resource not in seen:
+            deduped.append(resource)
+            seen.add(resource)
+    return deduped
+
+
+def create_resource_dirs(skill_dir, skill_name, skill_title, resources, include_examples):
+    for resource in resources:
+        resource_dir = skill_dir / resource
+        resource_dir.mkdir(exist_ok=True)
+        if resource == "scripts":
+            if include_examples:
+                example_script = resource_dir / "example.py"
+                example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
+                example_script.chmod(0o755)
+                print("[OK] Created scripts/example.py")
+            else:
+                print("[OK] Created scripts/")
+        elif resource == "references":
+            if include_examples:
+                example_reference = resource_dir / "api_reference.md"
+                example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
+                print("[OK] Created references/api_reference.md")
+            else:
+                print("[OK] Created references/")
+        elif resource == "assets":
+            if include_examples:
+                example_asset = resource_dir / "example_asset.txt"
+                example_asset.write_text(EXAMPLE_ASSET)
+                print("[OK] Created assets/example_asset.txt")
+            else:
+                print("[OK] Created assets/")
+
+
+def init_skill(skill_name, path, resources, include_examples, interface_overrides):
+    """
+    Initialize a new skill directory with template SKILL.md.
+
+    Args:
+        skill_name: Name of the skill
+        path: Path where the skill directory should be created
+        resources: Resource directories to create
+        include_examples: Whether to create example files in resource directories
+
+    Returns:
+        Path to created skill directory, or None if error
+    """
+    # Determine skill directory path
+    skill_dir = Path(path).resolve() / skill_name
+
+    # Check if directory already exists
+    if skill_dir.exists():
+        print(f"[ERROR] Skill directory already exists: {skill_dir}")
+        return None
+
+    # Create skill directory
+    try:
+        skill_dir.mkdir(parents=True, exist_ok=False)
+        print(f"[OK] Created skill directory: {skill_dir}")
+    except Exception as e:
+        print(f"[ERROR] Error creating directory: {e}")
+        return None
+
+    # Create SKILL.md from template
+    skill_title = title_case_skill_name(skill_name)
+    skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)
+
+    skill_md_path = skill_dir / "SKILL.md"
+    try:
+        skill_md_path.write_text(skill_content)
+        print("[OK] Created SKILL.md")
+    except Exception as e:
+        print(f"[ERROR] Error creating SKILL.md: {e}")
+        return None
+
+    # Create agents/openai.yaml
+    try:
+        result = write_openai_yaml(skill_dir, skill_name, interface_overrides)
+        if not result:
+            return None
+    except Exception as e:
+        print(f"[ERROR] Error creating agents/openai.yaml: {e}")
+        return None
+
+    # Create resource directories if requested
+    if resources:
+        try:
+            create_resource_dirs(skill_dir, skill_name, skill_title, resources, include_examples)
+        except Exception as e:
+            print(f"[ERROR] Error creating resource directories: {e}")
+            return None
+
+    # Print next steps
+    print(f"\n[OK] Skill '{skill_name}' initialized successfully at {skill_dir}")
+    print("\nNext steps:")
+    print("1. Edit SKILL.md to complete the TODO items and update the description")
+    if resources:
+        if include_examples:
+            print("2. Customize or delete the example files in scripts/, references/, and assets/")
+        else:
+            print("2. Add resources to scripts/, references/, and assets/ as needed")
+    else:
+        print("2. Create resource directories only if needed (scripts/, references/, assets/)")
+    print("3. Update agents/openai.yaml if the UI metadata should differ")
+    print("4. Run the validator when ready to check the skill structure")
+    print(
+        "5. Forward-test complex skills with realistic user requests to ensure they work as intended"
+    )
+
+    return skill_dir
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Create a new skill directory with a SKILL.md template.",
+    )
+    parser.add_argument("skill_name", help="Skill name (normalized to hyphen-case)")
+    parser.add_argument("--path", required=True, help="Output directory for the skill")
+    parser.add_argument(
+        "--resources",
+        default="",
+        help="Comma-separated list: scripts,references,assets",
+    )
+    parser.add_argument(
+        "--examples",
+        action="store_true",
+        help="Create example files inside the selected resource directories",
+    )
+    parser.add_argument(
+        "--interface",
+        action="append",
+        default=[],
+        help="Interface override in key=value format (repeatable)",
+    )
+    args = parser.parse_args()
+
+    raw_skill_name = args.skill_name
+    skill_name = normalize_skill_name(raw_skill_name)
+    if not skill_name:
+        print("[ERROR] Skill name must include at least one letter or digit.")
+        sys.exit(1)
+    if len(skill_name) > MAX_SKILL_NAME_LENGTH:
+        print(
+            f"[ERROR] Skill name '{skill_name}' is too long ({len(skill_name)} characters). "
+            f"Maximum is {MAX_SKILL_NAME_LENGTH} characters."
+        )
+        sys.exit(1)
+    if skill_name != raw_skill_name:
+        print(f"Note: Normalized skill name from '{raw_skill_name}' to '{skill_name}'.")
+
+    resources = parse_resources(args.resources)
+    if args.examples and not resources:
+        print("[ERROR] --examples requires --resources to be set.")
+        sys.exit(1)
+
+    path = args.path
+
+    print(f"Initializing skill: {skill_name}")
+    print(f"   Location: {path}")
+    if resources:
+        print(f"   Resources: {', '.join(resources)}")
+        if args.examples:
+            print("   Examples: enabled")
+    else:
+        print("   Resources: none (create as needed)")
+    print()
+
+    result = init_skill(skill_name, path, resources, args.examples, args.interface)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/skills/skill-creator/scripts/quick_validate.py b/skills/skill-creator/scripts/quick_validate.py
new file mode 100644
index 0000000..0547b40
--- /dev/null
+++ b/skills/skill-creator/scripts/quick_validate.py
@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+MAX_SKILL_NAME_LENGTH = 64
+
+
+def validate_skill(skill_path):
+    """Basic validation of a skill"""
+    skill_path = Path(skill_path)
+
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+
+    content = skill_md.read_text()
+    if not content.startswith("---"):
+        return False, "No YAML frontmatter found"
+
+    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+    if not match:
+        return False, "Invalid frontmatter format"
+
+    frontmatter_text = match.group(1)
+
+    try:
+        frontmatter = yaml.safe_load(frontmatter_text)
+        if not isinstance(frontmatter, dict):
+            return False, "Frontmatter must be a YAML dictionary"
+    except yaml.YAMLError as e:
+        return False, f"Invalid YAML in frontmatter: {e}"
+
+    allowed_properties = {"name", "description", "license", "allowed-tools", "metadata"}
+
+    unexpected_keys = set(frontmatter.keys()) - allowed_properties
+    if unexpected_keys:
+        allowed = ", ".join(sorted(allowed_properties))
+        unexpected = ", ".join(sorted(unexpected_keys))
+        return (
+            False,
+            f"Unexpected key(s) in SKILL.md frontmatter: {unexpected}. Allowed properties are: {allowed}",
+        )
+
+    if "name" not in frontmatter:
+        return False, "Missing 'name' in frontmatter"
+    if "description" not in frontmatter:
+        return False, "Missing 'description' in frontmatter"
+
+    name = frontmatter.get("name", "")
+    if not isinstance(name, str):
+        return False, f"Name must be a string, got {type(name).__name__}"
+    name = name.strip()
+    if name:
+        if not re.match(r"^[a-z0-9-]+$", name):
+            return (
+                False,
+                f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)",
+            )
+        if name.startswith("-") or name.endswith("-") or "--" in name:
+            return (
+                False,
+                f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens",
+            )
+        if len(name) > MAX_SKILL_NAME_LENGTH:
+            return (
+                False,
+                f"Name is too long ({len(name)} characters). "
+                f"Maximum is {MAX_SKILL_NAME_LENGTH} characters.",
+            )
+
+    description = frontmatter.get("description", "")
+    if not isinstance(description, str):
+        return False, f"Description must be a string, got {type(description).__name__}"
+    description = description.strip()
+    if description:
+        if "<" in description or ">" in description:
+            return False, "Description cannot contain angle brackets (< or >)"
+        if len(description) > 1024:
+            return (
+                False,
+                f"Description is too long ({len(description)} characters). Maximum is 1024 characters.",
+            )
+
+    return True, "Skill is valid!"
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py <skill_directory>")
+        sys.exit(1)
+
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    sys.exit(0 if valid else 1)
diff --git a/skills/skill-installer/LICENSE.txt b/skills/skill-installer/LICENSE.txt
new file mode 100644
index 0000000..d645695
--- /dev/null
+++ b/skills/skill-installer/LICENSE.txt
@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/skills/skill-installer/SKILL.md b/skills/skill-installer/SKILL.md
new file mode 100644
index 0000000..313626a
--- /dev/null
+++ b/skills/skill-installer/SKILL.md
@@ -0,0 +1,58 @@
+---
+name: skill-installer
+description: Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
+metadata:
+  short-description: Install curated skills from openai/skills or other repos
+---
+
+# Skill Installer
+
+Helps install skills. By default these are from https://github.com/openai/skills/tree/main/skills/.curated, but users can also provide other locations. Experimental skills live in https://github.com/openai/skills/tree/main/skills/.experimental and can be installed the same way.
+
+Use the helper scripts based on the task:
+- List skills when the user asks what is available, or if the user uses this skill without specifying what to do. Default listing is `.curated`, but you can pass `--path skills/.experimental` when they ask about experimental skills.
+- Install from the curated list when the user provides a skill name.
+- Install from another repo when the user provides a GitHub repo/path (including private repos).
+
+Install skills with the helper scripts.
+
+## Communication
+
+When listing skills, output approximately as follows, depending on the context of the user's request. If they ask about experimental skills, list from `.experimental` instead of `.curated` and label the source accordingly:
+"""
+Skills from {repo}:
+1. skill-1
+2. skill-2 (already installed)
+3. ...
+Which ones would you like installed?
+"""
+
+After installing a skill, tell the user: "Restart Codex to pick up new skills."
+
+## Scripts
+
+All of these scripts use network, so when running in the sandbox, request escalation when running them.
+
+- `scripts/list-skills.py` (prints skills list with installed annotations)
+- `scripts/list-skills.py --format json`
+- Example (experimental list): `scripts/list-skills.py --path skills/.experimental`
+- `scripts/install-skill-from-github.py --repo <owner>/<repo> --path <path/to/skill> [<path/to/skill> ...]`
+- `scripts/install-skill-from-github.py --url https://github.com/<owner>/<repo>/tree/<ref>/<path>`
+- Example (experimental skill): `scripts/install-skill-from-github.py --repo openai/skills --path skills/.experimental/<skill-name>`
+
+## Behavior and Options
+
+- Defaults to direct download for public GitHub repos.
+- If download fails with auth/permission errors, falls back to git sparse checkout.
+- Aborts if the destination skill directory already exists.
+- Installs into `$CODEX_HOME/skills/<skill-name>` (defaults to `~/.codex/skills`).
+- Multiple `--path` values install multiple skills in one run, each named from the path basename unless `--name` is supplied.
+- Options: `--ref <ref>` (default `main`), `--dest <path>`, `--method auto|download|git`.
+
+## Notes
+
+- Curated listing is fetched from `https://github.com/openai/skills/tree/main/skills/.curated` via the GitHub API. If it is unavailable, explain the error and exit.
+- Private GitHub repos can be accessed via existing git credentials or optional `GITHUB_TOKEN`/`GH_TOKEN` for download.
+- Git fallback tries HTTPS first, then SSH.
+- The skills at https://github.com/openai/skills/tree/main/skills/.system are preinstalled, so no need to help users install those. If they ask, just explain this. If they insist, you can download and overwrite.
+- Installed annotations come from `$CODEX_HOME/skills`.
diff --git a/skills/skill-installer/agents/openai.yaml b/skills/skill-installer/agents/openai.yaml
new file mode 100644
index 0000000..88d40cd
--- /dev/null
+++ b/skills/skill-installer/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Skill Installer"
+  short_description: "Install curated skills from openai/skills or other repos"
+  icon_small: "./assets/skill-installer-small.svg"
+  icon_large: "./assets/skill-installer.png"
diff --git a/skills/skill-installer/assets/skill-installer-small.svg b/skills/skill-installer/assets/skill-installer-small.svg
new file mode 100644
index 0000000..ccfc034
--- /dev/null
+++ b/skills/skill-installer/assets/skill-installer-small.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
+  <path fill="#0D0D0D" d="M2.145 3.959a2.033 2.033 0 0 1 2.022-1.824h5.966c.551 0 .997 0 1.357.029.367.03.692.093.993.246l.174.098c.397.243.72.593.932 1.01l.053.114c.116.269.168.557.194.878.03.36.03.805.03 1.357v4.3a2.365 2.365 0 0 1-2.366 2.365h-1.312a2.198 2.198 0 0 1-4.377 0H4.167A2.032 2.032 0 0 1 2.135 10.5V9.333l.004-.088A.865.865 0 0 1 3 8.468l.116-.006A1.135 1.135 0 0 0 3 6.199a.865.865 0 0 1-.865-.864V4.167l.01-.208Zm1.054 1.186a2.198 2.198 0 0 1 0 4.376v.98c0 .534.433.967.968.967H6l.089.004a.866.866 0 0 1 .776.861 1.135 1.135 0 0 0 2.27 0c0-.478.387-.865.865-.865h1.5c.719 0 1.301-.583 1.301-1.301v-4.3c0-.57 0-.964-.025-1.27a1.933 1.933 0 0 0-.09-.493L12.642 4a1.47 1.47 0 0 0-.541-.585l-.102-.056c-.126-.065-.295-.11-.596-.135a17.31 17.31 0 0 0-1.27-.025H4.167a.968.968 0 0 0-.968.968v.978Z"/>
+</svg>
diff --git a/skills/skill-installer/assets/skill-installer.png b/skills/skill-installer/assets/skill-installer.png
new file mode 100644
index 0000000..2977cd5
Binary files /dev/null and b/skills/skill-installer/assets/skill-installer.png differ
diff --git a/skills/skill-installer/scripts/github_utils.py b/skills/skill-installer/scripts/github_utils.py
new file mode 100644
index 0000000..711f597
--- /dev/null
+++ b/skills/skill-installer/scripts/github_utils.py
@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Shared GitHub helpers for skill install scripts."""
+
+from __future__ import annotations
+
+import os
+import urllib.request
+
+
+def github_request(url: str, user_agent: str) -> bytes:
+    headers = {"User-Agent": user_agent}
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        headers["Authorization"] = f"token {token}"
+    req = urllib.request.Request(url, headers=headers)
+    with urllib.request.urlopen(req) as resp:
+        return resp.read()
+
+
+def github_api_contents_url(repo: str, path: str, ref: str) -> str:
+    return f"https://api.github.com/repos/{repo}/contents/{path}?ref={ref}"
diff --git a/skills/skill-installer/scripts/install-skill-from-github.py b/skills/skill-installer/scripts/install-skill-from-github.py
new file mode 100644
index 0000000..1c8ce89
--- /dev/null
+++ b/skills/skill-installer/scripts/install-skill-from-github.py
@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""Install a skill from a GitHub repo path into $CODEX_HOME/skills."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.parse
+import zipfile
+
+from github_utils import github_request
+DEFAULT_REF = "main"
+
+
+@dataclass
+class Args:
+    url: str | None = None
+    repo: str | None = None
+    path: list[str] | None = None
+    ref: str = DEFAULT_REF
+    dest: str | None = None
+    name: str | None = None
+    method: str = "auto"
+
+
+@dataclass
+class Source:
+    owner: str
+    repo: str
+    ref: str
+    paths: list[str]
+    repo_url: str | None = None
+
+
+class InstallError(Exception):
+    pass
+
+
+def _codex_home() -> str:
+    return os.environ.get("CODEX_HOME", os.path.expanduser("~/.codex"))
+
+
+def _tmp_root() -> str:
+    base = os.path.join(tempfile.gettempdir(), "codex")
+    os.makedirs(base, exist_ok=True)
+    return base
+
+
+def _request(url: str) -> bytes:
+    return github_request(url, "codex-skill-install")
+
+
+def _parse_github_url(url: str, default_ref: str) -> tuple[str, str, str, str | None]:
+    parsed = urllib.parse.urlparse(url)
+    if parsed.netloc != "github.com":
+        raise InstallError("Only GitHub URLs are supported for download mode.")
+    parts = [p for p in parsed.path.split("/") if p]
+    if len(parts) < 2:
+        raise InstallError("Invalid GitHub URL.")
+    owner, repo = parts[0], parts[1]
+    ref = default_ref
+    subpath = ""
+    if len(parts) > 2:
+        if parts[2] in ("tree", "blob"):
+            if len(parts) < 4:
+                raise InstallError("GitHub URL missing ref or path.")
+            ref = parts[3]
+            subpath = "/".join(parts[4:])
+        else:
+            subpath = "/".join(parts[2:])
+    return owner, repo, ref, subpath or None
+
+
+def _download_repo_zip(owner: str, repo: str, ref: str, dest_dir: str) -> str:
+    zip_url = f"https://codeload.github.com/{owner}/{repo}/zip/{ref}"
+    zip_path = os.path.join(dest_dir, "repo.zip")
+    try:
+        payload = _request(zip_url)
+    except urllib.error.HTTPError as exc:
+        raise InstallError(f"Download failed: HTTP {exc.code}") from exc
+    with open(zip_path, "wb") as file_handle:
+        file_handle.write(payload)
+    with zipfile.ZipFile(zip_path, "r") as zip_file:
+        _safe_extract_zip(zip_file, dest_dir)
+        top_levels = {name.split("/")[0] for name in zip_file.namelist() if name}
+    if not top_levels:
+        raise InstallError("Downloaded archive was empty.")
+    if len(top_levels) != 1:
+        raise InstallError("Unexpected archive layout.")
+    return os.path.join(dest_dir, next(iter(top_levels)))
+
+
+def _run_git(args: list[str]) -> None:
+    result = subprocess.run(args, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    if result.returncode != 0:
+        raise InstallError(result.stderr.strip() or "Git command failed.")
+
+
+def _safe_extract_zip(zip_file: zipfile.ZipFile, dest_dir: str) -> None:
+    dest_root = os.path.realpath(dest_dir)
+    for info in zip_file.infolist():
+        extracted_path = os.path.realpath(os.path.join(dest_dir, info.filename))
+        if extracted_path == dest_root or extracted_path.startswith(dest_root + os.sep):
+            continue
+        raise InstallError("Archive contains files outside the destination.")
+    zip_file.extractall(dest_dir)
+
+
+def _validate_relative_path(path: str) -> None:
+    if os.path.isabs(path) or os.path.normpath(path).startswith(".."):
+        raise InstallError("Skill path must be a relative path inside the repo.")
+
+
+def _validate_skill_name(name: str) -> None:
+    altsep = os.path.altsep
+    if not name or os.path.sep in name or (altsep and altsep in name):
+        raise InstallError("Skill name must be a single path segment.")
+    if name in (".", ".."):
+        raise InstallError("Invalid skill name.")
+
+
+def _git_sparse_checkout(repo_url: str, ref: str, paths: list[str], dest_dir: str) -> str:
+    repo_dir = os.path.join(dest_dir, "repo")
+    clone_cmd = [
+        "git",
+        "clone",
+        "--filter=blob:none",
+        "--depth",
+        "1",
+        "--sparse",
+        "--single-branch",
+        "--branch",
+        ref,
+        repo_url,
+        repo_dir,
+    ]
+    try:
+        _run_git(clone_cmd)
+    except InstallError:
+        _run_git(
+            [
+                "git",
+                "clone",
+                "--filter=blob:none",
+                "--depth",
+                "1",
+                "--sparse",
+                "--single-branch",
+                repo_url,
+                repo_dir,
+            ]
+        )
+    _run_git(["git", "-C", repo_dir, "sparse-checkout", "set", *paths])
+    _run_git(["git", "-C", repo_dir, "checkout", ref])
+    return repo_dir
+
+
+def _validate_skill(path: str) -> None:
+    if not os.path.isdir(path):
+        raise InstallError(f"Skill path not found: {path}")
+    skill_md = os.path.join(path, "SKILL.md")
+    if not os.path.isfile(skill_md):
+        raise InstallError("SKILL.md not found in selected skill directory.")
+
+
+def _copy_skill(src: str, dest_dir: str) -> None:
+    os.makedirs(os.path.dirname(dest_dir), exist_ok=True)
+    if os.path.exists(dest_dir):
+        raise InstallError(f"Destination already exists: {dest_dir}")
+    shutil.copytree(src, dest_dir)
+
+
+def _build_repo_url(owner: str, repo: str) -> str:
+    return f"https://github.com/{owner}/{repo}.git"
+
+
+def _build_repo_ssh(owner: str, repo: str) -> str:
+    return f"git@github.com:{owner}/{repo}.git"
+
+
+def _prepare_repo(source: Source, method: str, tmp_dir: str) -> str:
+    if method in ("download", "auto"):
+        try:
+            return _download_repo_zip(source.owner, source.repo, source.ref, tmp_dir)
+        except InstallError as exc:
+            if method == "download":
+                raise
+            err_msg = str(exc)
+            if "HTTP 401" in err_msg or "HTTP 403" in err_msg or "HTTP 404" in err_msg:
+                pass
+            else:
+                raise
+    if method in ("git", "auto"):
+        repo_url = source.repo_url or _build_repo_url(source.owner, source.repo)
+        try:
+            return _git_sparse_checkout(repo_url, source.ref, source.paths, tmp_dir)
+        except InstallError:
+            repo_url = _build_repo_ssh(source.owner, source.repo)
+            return _git_sparse_checkout(repo_url, source.ref, source.paths, tmp_dir)
+    raise InstallError("Unsupported method.")
+
+
+def _resolve_source(args: Args) -> Source:
+    if args.url:
+        owner, repo, ref, url_path = _parse_github_url(args.url, args.ref)
+        if args.path is not None:
+            paths = list(args.path)
+        elif url_path:
+            paths = [url_path]
+        else:
+            paths = []
+        if not paths:
+            raise InstallError("Missing --path for GitHub URL.")
+        return Source(owner=owner, repo=repo, ref=ref, paths=paths)
+
+    if not args.repo:
+        raise InstallError("Provide --repo or --url.")
+    if "://" in args.repo:
+        return _resolve_source(
+            Args(url=args.repo, repo=None, path=args.path, ref=args.ref)
+        )
+
+    repo_parts = [p for p in args.repo.split("/") if p]
+    if len(repo_parts) != 2:
+        raise InstallError("--repo must be in owner/repo format.")
+    if not args.path:
+        raise InstallError("Missing --path for --repo.")
+    paths = list(args.path)
+    return Source(
+        owner=repo_parts[0],
+        repo=repo_parts[1],
+        ref=args.ref,
+        paths=paths,
+    )
+
+
+def _default_dest() -> str:
+    return os.path.join(_codex_home(), "skills")
+
+
+def _parse_args(argv: list[str]) -> Args:
+    parser = argparse.ArgumentParser(description="Install a skill from GitHub.")
+    parser.add_argument("--repo", help="owner/repo")
+    parser.add_argument("--url", help="https://github.com/owner/repo[/tree/ref/path]")
+    parser.add_argument(
+        "--path",
+        nargs="+",
+        help="Path(s) to skill(s) inside repo",
+    )
+    parser.add_argument("--ref", default=DEFAULT_REF)
+    parser.add_argument("--dest", help="Destination skills directory")
+    parser.add_argument(
+        "--name", help="Destination skill name (defaults to basename of path)"
+    )
+    parser.add_argument(
+        "--method",
+        choices=["auto", "download", "git"],
+        default="auto",
+    )
+    return parser.parse_args(argv, namespace=Args())
+
+
+def main(argv: list[str]) -> int:
+    args = _parse_args(argv)
+    try:
+        source = _resolve_source(args)
+        source.ref = source.ref or args.ref
+        if not source.paths:
+            raise InstallError("No skill paths provided.")
+        for path in source.paths:
+            _validate_relative_path(path)
+        dest_root = args.dest or _default_dest()
+        tmp_dir = tempfile.mkdtemp(prefix="skill-install-", dir=_tmp_root())
+        try:
+            repo_root = _prepare_repo(source, args.method, tmp_dir)
+            installed = []
+            for path in source.paths:
+                skill_name = args.name if len(source.paths) == 1 else None
+                skill_name = skill_name or os.path.basename(path.rstrip("/"))
+                _validate_skill_name(skill_name)
+                if not skill_name:
+                    raise InstallError("Unable to derive skill name.")
+                dest_dir = os.path.join(dest_root, skill_name)
+                if os.path.exists(dest_dir):
+                    raise InstallError(f"Destination already exists: {dest_dir}")
+                skill_src = os.path.join(repo_root, path)
+                _validate_skill(skill_src)
+                _copy_skill(skill_src, dest_dir)
+                installed.append((skill_name, dest_dir))
+        finally:
+            if os.path.isdir(tmp_dir):
+                shutil.rmtree(tmp_dir, ignore_errors=True)
+        for skill_name, dest_dir in installed:
+            print(f"Installed {skill_name} to {dest_dir}")
+        return 0
+    except InstallError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/skills/skill-installer/scripts/list-skills.py b/skills/skill-installer/scripts/list-skills.py
new file mode 100644
index 0000000..0977c29
--- /dev/null
+++ b/skills/skill-installer/scripts/list-skills.py
@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""List skills from a GitHub repo path."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+
+from github_utils import github_api_contents_url, github_request
+
+DEFAULT_REPO = "openai/skills"
+DEFAULT_PATH = "skills/.curated"
+DEFAULT_REF = "main"
+
+
+class ListError(Exception):
+    pass
+
+
+class Args(argparse.Namespace):
+    repo: str
+    path: str
+    ref: str
+    format: str
+
+
+def _request(url: str) -> bytes:
+    return github_request(url, "codex-skill-list")
+
+
+def _codex_home() -> str:
+    return os.environ.get("CODEX_HOME", os.path.expanduser("~/.codex"))
+
+
+def _installed_skills() -> set[str]:
+    root = os.path.join(_codex_home(), "skills")
+    if not os.path.isdir(root):
+        return set()
+    entries = set()
+    for name in os.listdir(root):
+        path = os.path.join(root, name)
+        if os.path.isdir(path):
+            entries.add(name)
+    return entries
+
+
+def _list_skills(repo: str, path: str, ref: str) -> list[str]:
+    api_url = github_api_contents_url(repo, path, ref)
+    try:
+        payload = _request(api_url)
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            raise ListError(
+                "Skills path not found: "
+                f"https://github.com/{repo}/tree/{ref}/{path}"
+            ) from exc
+        raise ListError(f"Failed to fetch skills: HTTP {exc.code}") from exc
+    data = json.loads(payload.decode("utf-8"))
+    if not isinstance(data, list):
+        raise ListError("Unexpected skills listing response.")
+    skills = [item["name"] for item in data if item.get("type") == "dir"]
+    return sorted(skills)
+
+
+def _parse_args(argv: list[str]) -> Args:
+    parser = argparse.ArgumentParser(description="List skills.")
+    parser.add_argument("--repo", default=DEFAULT_REPO)
+    parser.add_argument(
+        "--path",
+        default=DEFAULT_PATH,
+        help="Repo path to list (default: skills/.curated)",
+    )
+    parser.add_argument("--ref", default=DEFAULT_REF)
+    parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format",
+    )
+    return parser.parse_args(argv, namespace=Args())
+
+
+def main(argv: list[str]) -> int:
+    args = _parse_args(argv)
+    try:
+        skills = _list_skills(args.repo, args.path, args.ref)
+        installed = _installed_skills()
+        if args.format == "json":
+            payload = [
+                {"name": name, "installed": name in installed} for name in skills
+            ]
+            print(json.dumps(payload))
+        else:
+            for idx, name in enumerate(skills, start=1):
+                suffix = " (already installed)" if name in installed else ""
+                print(f"{idx}. {name}{suffix}")
+        return 0
+    except ListError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))