22 Commits

• [codex] Update OpenAI Docs skill (#24914)

  ## Summary
  - update the bundled `openai-docs` system skill to match the latest
  `openai-docs-plus` content from `skills-internal`
  - add the cached Codex manual fetch helper and expand the skill routing
  for Codex self-knowledge
  - keep the stable local skill identity and labels as `openai-docs`
  
  ## Why
  The built-in OpenAI Docs skill needed to reflect the current upstream
  guidance from `skills-internal` while preserving the local system-skill
  name used by Codex.
  
  ## Impact
  Codex now ships the newer OpenAI Docs skill behavior for Codex
  self-knowledge and manual-first documentation lookups.
  
  ## Validation
  - `just test -p codex-skills`
  - exact directory diff against transformed `skills-internal`
  `origin/main` was clean

  Vaibhav Srivastav · 2026-05-28 15:11:11 +00:00
  a4ed6c5aa0
• [skills] Create a personal update flow for plugin creator (#23542)

  ## Summary
  Creates a personal-marketplace update flow for the plugin-creator skill
  when iterating on an existing local plugin.
  
  ## Context
  Plugin creation already had a scaffold path, but the follow-up story for
  updating an existing local plugin during development was not explicit.
  The goal of this change is to make that default personal-marketplace
  update loop legible at the point of use instead of leaving it implied or
  hidden behind a larger helper.
  
  ## Decision
  Keep the scaffold flow intact, add a dedicated update/reinstall
  reference centered on the personal marketplace, document the actual
  `codex plugin add` and marketplace-check commands directly, and keep
  helper automation narrowly scoped to the repetitive local-update steps.
  
  ## Changes
  - update plugin-creator to point existing-plugin iteration at a
  personal-marketplace update flow
  - add `references/installing-and-updating.md` with the explicit
  marketplace check and reinstall sequence
  - add small helper scripts for reading marketplace names and updating
  plugin versions during local iteration
  
  ## Tests
  - `python3
  codex-rs/skills/src/assets/samples/skill-creator/scripts/quick_validate.py
  codex-rs/skills/src/assets/samples/plugin-creator`
  - `python3 -m py_compile
  codex-rs/skills/src/assets/samples/plugin-creator/scripts/create_basic_plugin.py
  codex-rs/skills/src/assets/samples/plugin-creator/scripts/read_marketplace_name.py
  codex-rs/skills/src/assets/samples/plugin-creator/scripts/update_plugin_cachebuster.py`

  Casey Chow · 2026-05-20 16:44:41 -04:00
  9265701b7f
• fix: harden plugin creator sharing validation (#22893)

  # Summary
  
  Before this change, the sample plugin creator could emit
  placeholder-heavy manifests that fail workspace sharing, and it chose a
  repo-local marketplace implicitly whenever it ran from inside a git
  checkout.
  
  This PR makes generated plugins share-ready by default. It switches
  creation to the personal marketplace unless the caller explicitly opts
  into repo-local paths, adds a validator that mirrors the workspace
  plugin ingestion contract, and updates the skill prompt and docs to
  describe the real flow.
  
  The goal is to stop malformed generated plugins before they reach
  sharing and to make the default placement match the personal marketplace
  behavior users expect.
  
  ## Changes
  
  - Generate share-safe plugin manifests instead of `[TODO: ...]`
  placeholder payloads.
  - Default plugin and marketplace creation to `~/plugins` and
  `~/.agents/plugins/marketplace.json`.
  - Keep repo-local marketplace creation available through explicit
  `--path` and `--marketplace-path` arguments.
  - Add `validate_plugin.py` to check manifests, companion files, skill
  frontmatter, skill agent YAML, asset paths, and backend-shaped contracts
  before sharing.
  - Refresh the plugin creator skill text, reference docs, and default
  prompt to describe validation and the personal default.
  
  ## Design decisions
  
  - The validator tracks the workspace ingestion schema directly,
  including the required `defaultPrompt` alias handling and skill
  `agents/openai.yaml` checks.
  - The validator keeps one intentional extra preflight rule: leftover
  `[TODO: ...]` placeholders are rejected before sharing even when a
  single placeholder would not independently violate backend type
  validation.
  - Repo-local creation stays possible, but it is now explicit instead of
  cwd-sensitive.
  
  ## Testing
  
  Tests: targeted Python syntax checks, plugin skill validation, staged
  diff whitespace validation, 15 generated plugin smoke runs, backend
  manifest-schema acceptance for all 15 generated bundles, and a git-repo
  cwd regression proving the creator still writes to the personal
  marketplace by default.

  efrazer-oai · 2026-05-18 11:22:42 -07:00
  d32cb2c6ac
• docs(skills): simplify plugin creator deeplink shape (#22240)

  ## Summary
  
  Plugin Creator now documents the shorter local-plugin handoff URL that
  the app can interpret directly.
  [#22221](https://github.com/openai/codex/pull/22221) teaches the skill
  to end marketplace-backed creation flows with named View and Share
  links; this follow-up updates those examples so the skill only emits the
  normalized plugin name, the absolute marketplace path, and optional
  share mode.
  
  The documented shape is:
  
  ```txt
  codex://plugins/<normalized-plugin-name>?marketplacePath=<absolute-marketplace-json-path>
  codex://plugins/<normalized-plugin-name>?marketplacePath=<absolute-marketplace-json-path>&mode=share
  ```
  
  The skill text now states exactly where the normalized plugin name
  belongs, exactly where the absolute marketplace path belongs, and that
  it should not add `pluginName` or `hostId` query parameters.
  
  ## Testing
  
  Tests: plugin-creator skill validation.

  efrazer-oai · 2026-05-13 00:54:52 +00:00
  01b4817bac
• feat(skills): default plugin creator to personal share flow (#22221)

  ## Summary
  Plugin creation now defaults to the personal marketplace path and ends
  with a readable handoff back into Codex after a marketplace-backed
  scaffold.
  
  Before this change, `plugin-creator` centered repo-local marketplace
  updates and did not clearly guide the agent to return the user to the
  created plugin afterward. This PR updates the bundled system skill so
  marketplace-backed scaffolds default to `~/plugins/<plugin-name>` plus
  `~/.agents/plugins/marketplace.json`, ask for user intent only when an
  existing repo marketplace makes personal vs team scope ambiguous, and
  end with named Markdown deeplinks labeled `View <plugin-name>` and
  `Share <plugin-name>`.
  
  ## What changed
  - default marketplace-backed creation to the personal plugin location
  - document the explicit repo/team override path for codebases that
  should own the plugin entry
  - ask personal vs team only when the current Git repo already has
  `.agents/plugins/marketplace.json` and the user has not stated scope
  - require named Markdown deeplinks after marketplace-backed creation so
  the final response returns the user to the exact plugin cleanly
  - keep the deeplink targets precise with real absolute `marketplacePath`
  and normalized `pluginName` values
  - align the bundled prompt, scaffold help text, and marketplace
  reference spec with the new default
  
  ## Testing
  Tests: targeted skill validation, Python compile checks,
  personal-default scaffold smoke, repo-override scaffold smoke, and
  whitespace checks.

  efrazer-oai · 2026-05-11 17:58:48 -07:00
  fd24c00b0b
• [codex] Coordinate OpenAI docs sample with API key setup (#21263)

  ## Summary
  - Add the same API key setup coordination guidance to the embedded
  OpenAI Docs sample skill in `codex-rs/skills`.
  - Keep the skill description/frontmatter unchanged; the coordination
  lives only in the body.
  - Preserve direct OpenAI Docs routing for docs-only questions,
  citations, model/API guidance, conceptual explanations, and non-building
  examples.
  
  ## Why
  The Codex repo carries its own OpenAI Docs skill variant under
  `codex-rs/skills/src/assets/samples`. This keeps that embedded sample
  aligned with the other OpenAI Docs variants patched in the related PRs.
  
  ## Validation
  - `cargo test -p codex-skills`
  - `git diff --check`

  mifan-oai · 2026-05-06 13:46:15 -04:00
  f2f5d6f6c7
• Clarify bundled OpenAI Docs upgrade guide wording (#19422)

  ## Summary
  - Mirrors the OpenAI Docs skill cleanup in the bundled Codex skill copy
  - Clarifies reasoning-effort recommendation wording
  - Replaces internal snake_case prompt block names with natural-language
  guidance aligned to the prompting guide
  
  ## Test plan
  - `git diff --check`
  - Verified the old snake_case prompt block names no longer appear in the
  bundled upgrade guide

  Konstantine Kahadze · 2026-04-24 22:35:52 +00:00
  3c6e2638ac
• Add gpt-image-2 to bundled OpenAI Docs skill (#19443)

  ## Summary
  - Mirrors openai/skills#374 in the Codex bundled OpenAI Docs skill
  - Adds `gpt-image-2` as the best image generation/edit model
  - Updates `gpt-image-1.5` to less expensive image generation/edit
  quality
  
  ## Test plan
  - `git diff --check`

  Konstantine Kahadze · 2026-04-24 21:48:45 +00:00
  c43e2fcfbf
• Update bundled OpenAI Docs skill for GPT-5.5 (#19407)

  ## Summary
  Updates the bundled OpenAI Docs system skill for GPT-5.5.
  
  ## Changes
  - Updates the bundled latest-model fallback
  - Replaces bundled upgrade guidance with GPT-5.5 migration guidance
  - Replaces bundled prompting guidance with GPT-5.5 prompting guidance
  
  ## Test plan
  - Ran `node scripts/resolve-latest-model-info.js`
  - Verified bundled files match the OpenAI Docs skill fallback content

  Konstantine Kahadze · 2026-04-24 18:26:47 +00:00
  6bb2fa3fd4
• Update bundled OpenAI Docs skill freshness check (#19043)

  ## Summary
  
  Sync the bundled `openai-docs` system skill with the already-merged
  `openai/skills` update from https://github.com/openai/skills/pull/360.
  
  Codex bundles system skills from `codex-rs/skills/src/assets/samples`,
  so this PR copies the same GPT-5.4 OpenAI Docs skill update into the
  Codex app/CLI bundle path.
  
  ## Changes
  
  - Add the latest-model resolver script to the bundled `openai-docs`
  skill.
  - Route model upgrade and prompt-upgrade requests through remote
  latest-model metadata when current guidance is needed.
  - Rename bundled fallback references to `upgrade-guide.md` and
  `prompting-guide.md`.
  - Keep the bundled fallback guidance GPT-5.4-only.
  
  ## Validation
  
  - Verified this bundled skill is byte-for-byte identical to
  `openai/skills@origin/main` `skills/.system/openai-docs`.
  - Ran the resolver locally and confirmed it returns `gpt-5.4` /
  `gpt-5p4`.

  Konstantine Kahadze · 2026-04-22 22:31:04 +00:00
  0e25c5ff42
• [codex] Update imagegen system skill (#18852)

  ## Summary
  
  This updates the embedded `imagegen` system skill in `codex-rs/skills`
  with the ImageGen 2 skill changes from `openai/skills-internal#87`.
  
  The bundled skill now keeps normal image generation/editing on the
  built-in `image_gen` path, updates the CLI fallback defaults to
  `gpt-image-2`, and routes explicit transparent-output requests through
  `gpt-image-1.5` with clear guidance that `gpt-image-2` does not support
  transparent backgrounds.
  
  ## Details
  
  - Update `SKILL.md` routing guidance for built-in vs CLI fallback
  behavior.
  - Update CLI/API references for `gpt-image-2` size constraints, quality
  options, near-4K sizes, and unsupported options.
  - Update `scripts/image_gen.py` defaults and validation:
    - default model `gpt-image-2`
    - default size `auto`
    - default quality `medium`
    - reject transparent backgrounds on `gpt-image-2`
    - reject `input_fidelity` on `gpt-image-2`
  - validate flexible `gpt-image-2` sizes and suggest `3824x2160` /
  `2160x3824` for near-4K requests
  - Update prompt/reference docs with the new model and routing guidance.
  
  ## Validation
  
  - `cargo test -p codex-skills`
  - `git diff --check`
  - Manual CLI dry-runs for:
    - default `gpt-image-2` payload
    - `3824x2160` near-4K size acceptance
    - `3840x2160` rejection with near-4K guidance
    - transparent background rejection on `gpt-image-2`
    - transparent background acceptance on `gpt-image-1.5`
    - `input_fidelity` rejection on `gpt-image-2`
  
  Bazel target check was not run locally because `bazel` is not installed
  in this environment.

  Vaibhav Srivastav · 2026-04-22 15:08:10 +00:00
  0ebe69a8c3
• Use AbsolutePathBuf in skill loading and codex_home (#17407)

  Helps with FS migration later

  pakrym-oai · 2026-04-13 10:26:51 -07:00
  ac82443d07
• [codex] Make AbsolutePathBuf joins infallible (#16981)

  Having to check for errors every time join is called is painful and
  unnecessary.

  pakrym-oai · 2026-04-07 10:52:08 -07:00
  f1a2b920f9
• Update plugin creator skill. (#15734)

  Add support for home-local plugin + fix policy.

  xl-openai · 2026-03-25 01:55:10 -07:00
  f5dccab5cf
• move imagegen skill into system skills (#15600)

  Add imagegen skill as built-in skill. Source: github.com/openai/skills

  Dominik Kundel · 2026-03-24 05:14:33 +00:00
  a10960e41c
• Add plugin-creator as system skill (#15554)
  alexsong-oai · 2026-03-23 19:08:30 -07:00
  db8bb7236d
• skill-creator: default new skills to ~/.codex/skills (#14837)

  ### Motivation
  - Prevent newly-created skills from being placed in unexpected locations
  by prompting for an install path and defaulting to a discoverable
  location so skills are usable immediately.
  - Make the `skill-creator` instructions explicit about the recommended
  default (`~/.codex/skills` / `$CODEX_HOME/skills`) so the agent and
  users follow a consistent, discoverable convention.
  
  ### Description
  - Updated `codex-rs/skills/src/assets/samples/skill-creator/SKILL.md` to
  add a user prompt: "Where should I create this skill? If you do not have
  a preference, I will place it in ~/.codex/skills so Codex can discover
  it automatically.".
  - Added guidance before running `init_skill.py` that if the user does
  not specify a location, the agent should default to `~/.codex/skills`
  (equivalently `$CODEX_HOME/skills`) for auto-discovery.
  - Updated the `init_skill.py` examples in the same `SKILL.md` to use
  `~/.codex/skills` as the recommended default while keeping one custom
  path example.
  
  ### Testing
  - Ran `cargo test -p codex-skills` and the crate's unit test suite
  passed (`1 passed; 0 failed`).
  - Verified relevant discovery behavior in code by checking
  `codex-rs/utils/home-dir/src/lib.rs` (`find_codex_home` defaults to
  `~/.codex`) and `codex-rs/core/src/skills/loader.rs` (user skill roots
  include `$CODEX_HOME/skills`).
  
  ------
  [Codex
  Task](https://chatgpt.com/codex/tasks/task_i_69b75a50bb008322a278e55eb0ddccd6)

  xl-openai · 2026-03-16 18:36:11 -07:00
  59533a2c26
• Add OpenAI Docs skill (#13596)

  ## Summary
  - add the OpenAI Docs skill under
  codex-rs/skills/src/assets/samples/openai-docs
  - include the skill metadata, assets, and GPT-5.4 upgrade reference
  files
  - exclude the test harness and test fixtures
  
  ## Testing
  - not run (skill-only asset copy)

  Charlie Guo · 2026-03-11 12:33:08 -07:00
  b7f8e9195a
• [skill-creator] Add forward-testing instructions (#13600)

  This updates the `skill-creator` sample skill to explicitly cover
  forward-testing as part of the skill authoring workflow. The guidance
  now treats subagent-based validation as a first-class step for complex
  or fragile skills, with an emphasis on preserving evaluation integrity
  and avoiding leaked context.
  
  The sample initialization script is also updated so newly created skills
  point authors toward forward-testing after validation. Together, these
  changes make the sample more opinionated about how skills should be
  iterated on once the initial implementation is complete.
  
  - Add new guidance to `SKILL.md` on protecting validation integrity,
  when to use subagents for forward-testing, and how to structure
  realistic test prompts without leaking expected answers.
  - Expand the skill creation workflow so iteration explicitly includes
  forward-testing for complex skills, including approval guidance for
  expensive or risky validation runs.

  Eugene Brevdo · 2026-03-11 12:33:08 -07:00
  3b1c78a5c5
• tmp: drop artifact skills (#13851)
  jif-oai · 2026-03-07 18:04:05 +01:00
  b9a2e40001
• feat: skills for artifacts (#13525)

  Co-authored-by: Dibyo Majumdar <dibyo@openai.com>

  jif-oai · 2026-03-05 12:02:02 +00:00
  a246dbf9d1
• refactor(core): move embedded system skills into codex-skills crate (#12435)

  ## Why
  
  `codex-core` was carrying the embedded system-skill sample assets (and a
  `build.rs` that walks those files to register rerun triggers). Those
  assets change infrequently, but any change under `codex-core` still ties
  them to `codex-core`'s build/cache lifecycle.
  
  This change moves the embedded system-skills packaging into a dedicated
  `codex-skills` crate so it can be cached independently. That reduces
  unnecessary invalidation/rebuild pressure on `codex-core` when the
  skills bundle is the only thing that changes.
  
  ## What Changed
  
  - Added a new `codex-rs/skills` crate (`codex-skills`) with:
    - `Cargo.toml`
    - `BUILD.bazel`
    - `build.rs` to track skill asset file changes for Cargo rebuilds
  - `src/lib.rs` containing the embedded system-skills install/cache logic
  previously in `codex-core`
  - Moved the embedded sample skill assets from
  `codex-rs/core/src/skills/assets/samples` to
  `codex-rs/skills/src/assets/samples`.
  - Updated `codex-rs/core/Cargo.toml` to depend on `codex-skills` and
  removed `codex-core`'s direct `include_dir` dependency.
  - Removed `codex-core`'s `build.rs`.
  - Replaced `codex-rs/core/src/skills/system.rs` implementation with a
  thin re-export wrapper to keep existing `codex-core` call sites
  unchanged.
  - Updated workspace manifests/lockfile (`codex-rs/Cargo.toml`,
  `codex-rs/Cargo.lock`) for the new crate.

  Michael Bolin · 2026-02-21 08:34:08 +00:00
  85ce91a5b3