openai · caseychow-oai · May 20, 2026 · May 19, 2026 · May 20, 2026
diff --git a/codex-rs/skills/src/assets/samples/plugin-creator/SKILL.md b/codex-rs/skills/src/assets/samples/plugin-creator/SKILL.md
@@ -1,6 +1,6 @@
 ---
 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, or generate or update marketplace entries for plugin ordering and availability metadata.
+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
@@ -10,11 +10,11 @@ description: Create and scaffold plugin directories for Codex with a required `.
 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 repo root (or replace .agents/... with the absolute path to this SKILL).
-# By default creates in ~/plugins/<plugin-name>.
-python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>
+# 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.
@@ -23,40 +23,66 @@ python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-nam
 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 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace
+# 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 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
+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 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
+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 `~/code/plugins`).
+`<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 .agents/skills/plugin-creator/scripts/validate_plugin.py <plugin-path>
+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 are personal: `~/plugins/<plugin-name>/` plus
-  `~/.agents/plugins/marketplace.json`.
+- 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.
@@ -77,9 +103,18 @@ python3 .agents/skills/plugin-creator/scripts/validate_plugin.py <plugin-path>
 
 ## Marketplace workflow
 
-- Personal creation defaults to `~/.agents/plugins/marketplace.json`.
+- 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.
@@ -157,6 +192,21 @@ python3 .agents/skills/plugin-creator/scripts/validate_plugin.py <plugin-path>
 - 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
@@ -175,17 +225,19 @@ python3 .agents/skills/plugin-creator/scripts/validate_plugin.py <plugin-path>
 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 <path-to-skill-creator>/scripts/quick_validate.py .agents/skills/plugin-creator
+python3 ../skill-creator/scripts/quick_validate.py .
 ```
 
 Before handing back a generated plugin, run:
 
 ```bash
-python3 .agents/skills/plugin-creator/scripts/validate_plugin.py <plugin-path>
+python3 scripts/validate_plugin.py <plugin-path>
 ```
diff --git a/.../skills/src/assets/samples/plugin-creator/references/installing-and-updating.md b/.../skills/src/assets/samples/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/codex-rs/skills/src/assets/samples/plugin-creator/references/plugin-json-spec.md b/codex-rs/skills/src/assets/samples/plugin-creator/references/plugin-json-spec.md
@@ -147,7 +147,8 @@ personal marketplace unless the caller explicitly requests a repo-local destinat
     - 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>`.
+    - 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`
@@ -168,6 +169,8 @@ personal marketplace unless the caller explicitly requests a repo-local destinat
 - 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`