CLI bug: bundled skill-creator helper scripts are not self-contained for YAML parsing

What version of Codex CLI is running?

codex-cli 0.114.0

What subscription do you have?

Unknown / not obvious from the local CLI environment. I was using Codex CLI through my normal OpenAI account workflow.

Which model were you using?

N/A for the failing step. This bug is in the bundled local helper scripts under ~/.codex/skills/.system/skill-creator/scripts/, before any model call mattered.

What platform is your computer?

Darwin 25.3.0 arm64 arm

What terminal emulator and version are you using (if applicable)?

Terminal.app with zsh, no multiplexer.

What issue are you seeing?

The bundled skill-creator helper scripts are not self-contained on a fresh environment.

Concretely, these scripts import YAML support but do not declare a dependency in their PEP 723 script metadata:

• quick_validate.py
• generate_openai_yaml.py
• init_skill.py

When I tried to validate a newly created skill, the first failure was:

Traceback (most recent call last):
  File "/Users/tal/.codex/skills/.system/skill-creator/scripts/quick_validate.py", line 10, in <module>
    import yaml
ModuleNotFoundError: No module named 'yaml'

I then tried the obvious local fix: add PyYAML as a script dependency and run via uv run. In this environment that also failed, because uv could not resolve PyYAML for the local CPython 3.13 ABI:

× No solution found when resolving script dependencies:
╰─▶ Because all versions of pyyaml have no wheels with a matching Python ABI
    tag (e.g., `cp313`) and you require pyyaml, we can conclude that your
    requirements are unsatisfiable.

    hint: You require CPython 3.13 (`cp313`), but we only found wheels for
    `pyyaml` (v6.0.3) with the following Python ABI tags: `cp310`, `cp312`,
    `cp314`

The workaround I ended up applying locally was to switch those helper scripts from PyYAML to ruamel.yaml and declare that in their PEP 723 headers. After that, both validation and YAML generation worked with uv run.

This feels like a portability bug in the bundled skill tooling: the scripts either need to declare dependencies that resolve on supported runtimes, or avoid non-stdlib YAML parsing in the quick helper path.

What steps can reproduce the bug?

1. Use a fresh Codex CLI environment where the bundled skills are available.
2. Create or point at any valid skill directory with a SKILL.md.
3. Run the validator directly:

python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ~/.codex/skills/logfire-span-triage

1. Observe ModuleNotFoundError: No module named 'yaml'.
2. Try to make the script self-contained by adding a PEP 723 dependency on PyYAML and run it through uv run:

uv run ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ~/.codex/skills/logfire-span-triage

1. Observe dependency resolution failure on CPython 3.13 because PyYAML is not available for that ABI in this environment.

What is the expected behavior?

The bundled skill-creator helper scripts should work out of the box when invoked in the recommended script style.

At minimum I would expect one of these:

• the scripts declare all required dependencies in a way that uv run can resolve on supported runtimes
• the scripts avoid external YAML dependencies for this lightweight validation/generation path
• the docs explicitly state a prerequisite if these helpers are not intended to be standalone

Additional information

I hit this while creating a new global skill and trying to validate it immediately afterward.

My local workaround was:

• add PEP 723 headers to the helper scripts
• replace PyYAML usage with ruamel.yaml
• rerun:

uv run ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ~/.codex/skills/dictation-prompt-optimization
uv run ~/.codex/skills/.system/skill-creator/scripts/generate_openai_yaml.py ~/.codex/skills/dictation-prompt-optimization --interface display_name='Dictation Prompt Optimization' --interface short_description='Analyze dictation outputs and tune prompts.' --interface default_prompt='Use $dictation-prompt-optimization to sample MacWhisper history or a provided JSONL and generate a review, revised prompt, dictionary, and Whisper prompt suggestion.'

After that I got:

Skill is valid!
[OK] Created agents/openai.yaml

I am filing this because the workaround was reasonable for me locally, but it seems like something the shipped helper scripts should handle themselves.