Bundled skill validator fails because Codex Python lacks PyYAML

I took a quick look at current origin/main (7d47056). This looks consistent with the report: the bundled skill/plugin helper scripts have a Python YAML dependency that does not appear to be declared in the bundled Python runtime metadata.

Code pointers:

• codex-rs/skills/src/assets/samples/skill-creator/scripts/quick_validate.py imports yaml at module load time and uses yaml.safe_load, so it fails before validation can run if PyYAML is absent.
• codex-rs/skills/src/assets/samples/skill-creator/SKILL.md documents scripts/quick_validate.py <path/to/skill-folder> as the validation step.
• codex-rs/skills/src/lib.rs embeds the skill-creator assets as system skills under CODEX_HOME/skills/.system.
• I could not find PyYAML/pyyaml in the bundled Python runtime metadata (sdk/python-runtime/pyproject.toml / uv.lock).

There are adjacent hits too: skill-creator/scripts/generate_openai_yaml.py and plugin-creator/scripts/validate_plugin.py also import/use yaml, so the same dependency contract can affect more than just quick_validate.py.

A narrow fix would be either to make PyYAML available in the Python environment expected to run these bundled skill/plugin scripts, or to remove the PyYAML dependency from those bundled scripts / fail with a clearer dependency diagnostic before validation starts.

Proposed Solution: Add PyYAML to Bundled Python Dependencies

Root Cause

Codex bundles a minimal Python runtime for skill validation, but PyYAML is not included. Skills are defined in YAML format, making PyYAML a critical dependency.

Fix

Add PyYAML to the bundled Python dependency list:

RUN pip install --no-cache-dir pyyaml>=6.0 jsonschema>=4.0

Plus graceful degradation with clear error message when PyYAML is missing.

Impact

• Severity: Medium - skill validation completely broken on Windows
• Scope: All Windows users using bundled skill validation

Testing

1. Verify PyYAML is importable in bundled Python
2. Run skill validator with YAML skill config

Full solution: solutions/codex-24195-pyyaml-missing-bundled-python-fix.md

Submitted feedback ID 019f0345-32c8-7113-9d9a-3f19c9c6d58a

I can reproduce the underlying bundled-runtime dependency issue on Windows with a newer Codex App build.

Environment:

• Codex App: OpenAI.Codex 26.623.5175.0
• Windows package path: C:\Program Files\WindowsApps\OpenAI.Codex_26.623.5175.0_x64__2p2nqsd0c76g0
• Bundled Python: C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe
• Bundled Python version: 3.12.13
• Validator: C:\Users\Administrator\.codex\skills\.system\skill-creator\scripts\quick_validate.py

Observed with the bundled Codex Python:

C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe -c "import yaml"
ModuleNotFoundError: No module named 'yaml'

Current workaround on this machine:

• System Python C:\Python314\python.exe has PyYAML installed, so running quick_validate.py through system python succeeds.

Why this still matters:

• The skill-creator validator appears to depend on PyYAML, but Codex's bundled runtime does not include it. A built-in Codex skill workflow is more robust if either the bundled runtime includes the dependency, the validator avoids the dependency, or the docs/wrapper clearly call out the required external Python package.

Plus one from here. Every time I create a skill, Codex tries to improvise to resolve this dependency. Trying different Python interpreter (system one), downloading PyYAML to a temp directory and adding ENV vars so that script would pick it up, using bundled Ruby yaml.

ARM MacOS, latest version, but do not think that platform really matters here.

Confirming this still reproduces on macOS with the current Codex Desktop bundled skill workflow as of 2026-08-09.

I ran:

python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ~/.codex/skills/prepare-fiu-standup

The default Python failed before validation with:

ModuleNotFoundError: No module named 'yaml'

I then retried with Codex’s bundled Python at:

~/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3

It produced the same missing yaml error. Installing PyYAML into an isolated temporary directory and exposing it only through PYTHONPATH allowed the unchanged bundled validator to complete successfully with Skill is valid!.

This confirms the skill itself was valid and the failure was the undeclared validator dependency. No global Python installation was needed for the workaround.

I investigated where the dependency belongs and found that adding PyYAML to sdk/python-runtime would target the wrong runtime. That package builds the platform-specific openai-codex-cli-bin wheel for the Python SDK; it is not the Desktop codex-primary-runtime whose bundled Python reproduced this failure.

More importantly, Codex already has a production skill-frontmatter parser in Rust:

• codex-rs/skills/src/parser.rs
• parse_skill_frontmatter_metadata(...)
• backed by the workspace serde_yaml dependency
• covered by parser tests for nested metadata, block scalars, quotes, colons, malformed YAML, and field normalization

quick_validate.py currently creates a second parsing path with PyYAML and additional authoring-policy checks. That duplication is the source of both the undeclared dependency and potential drift between what the validator accepts and what Codex actually loads.

Proposed direction

1. Add a supported command such as:

``text
codex skills validate /path/to/skill
``

1. Implement it on top of the existing codex-skills Rust parser.
2. Add the authoring checks currently unique to quick_validate.py, including:

• hyphen-case names
• the 64-character name limit
• required descriptions
• the 1,024-character description limit
• allowed frontmatter properties
• the current description character restrictions

1. Update the bundled skill-creator instructions to use that command.
2. Remove quick_validate.py, or retain it temporarily as a compatibility wrapper that delegates to the Codex command.
3. Add Rust unit coverage for the authoring rules and a CLI integration test proving a valid skill can be checked without any user-installed Python packages.

This would provide one canonical YAML implementation, use the same parser during authoring and runtime loading, avoid a partial custom YAML parser, remove the PyYAML provisioning problem, and behave consistently across platforms.

The smaller fallback would be to provision PyYAML in the Desktop primary runtime and improve the import error, but that would preserve two independent validation paths and would not address behavioral drift.

Would the maintainers agree that a Rust-backed codex skills validate command is the preferred direction? If so, would you be willing to invite a focused pull request for this change under the repository's invitation-only contribution policy?

Related reports

This change should also resolve the same quick_validate.py / missing-PyYAML failure reported in #30935, #33022, and #36245. Those issues describe the same underlying split between the bundled validator and the Python environments available to run it. Consolidating validation in the existing Rust skill parser would address the shared root cause rather than applying separate environment-specific workarounds.

Considered alternative and prior work

An earlier independent attempt in ChronoAIProject/FKST-codex-harness#368 implemented a focused stdlib-only parser on a fork branch, together with a python3 -S regression test. That work did not proceed to an upstream PR, but it is useful prior art and directly demonstrates that removing the import can make the bundled script runnable without site packages.

I considered that approach but do not recommend it as the canonical fix because the replacement parser intentionally handles only top-level key: value lines, skips indented content, and does not validate the full YAML structures already handled by Codex’s Rust serde_yaml parser. Keeping a separate partial parser would preserve semantic drift between authoring validation and runtime loading. Reusing the existing Rust parser retains full YAML handling while addressing the same dependency failure.