skill-creator initializer generates invalid description frontmatter

Open Beginner friendly
#37,052 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
85/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Quiet
Tech stack
python, yaml
Domain
tooling

Research direction

Start with codex-rs/skills/src/assets/samples/skill-creator/scripts/init_skill.py and inspect the SKILL.md template's description field. Run the provided init_skill.py and quick_validate.py reproduction, then confirm the generated description is parsed as a string and quick_validate.py reports "Skill is valid!" while agents/openai.yaml remains unchanged.

Written by the indexing model from the issue text.

Description

bug CLI skills

What issue are you seeing?

The bundled skill-creator initializer creates a SKILL.md whose placeholder description is parsed by YAML as a list. The bundled validator then rejects the freshly generated skill:

Description must be a string, got list

The source is:

codex-rs/skills/src/assets/samples/skill-creator/scripts/init_skill.py

At current main (ed2f985a26eee9a59cde0fdefd20f69b45bc25f5), the template contains:

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.]

Because square brackets are YAML sequence syntax, yaml.safe_load returns a list, while quick_validate.py correctly requires description to be a string.

What steps can reproduce the bug?

SKILL_CREATOR=codex-rs/skills/src/assets/samples/skill-creator
SMOKE_ROOT=$(mktemp -d)

python3 "$SKILL_CREATOR/scripts/init_skill.py" example-skill \
  --path "$SMOKE_ROOT" \
  --interface 'display_name=Example Skill' \
  --interface 'short_description=Example generated skill' \
  --interface 'default_prompt=Use $example-skill for an example.'

python3 "$SKILL_CREATOR/scripts/quick_validate.py" \
  "$SMOKE_ROOT/example-skill"

Observed result:

Description must be a string, got list

What is the expected behavior?

A new skill created by the bundled initializer should pass the bundled structural validator before its TODO text is replaced.

Quoting the placeholder fixes the mismatch without changing its content:

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.]"

After this one-line change:

  • the generated description parses as a string;
  • the generated agents/openai.yaml remains unchanged; and
  • quick_validate.py returns Skill is valid! for the fresh package.

Additional information

  • Reproduced with codex-cli 0.145.0 on macOS.
  • Confirmed against current openai/codex main at ed2f985a26eee9a59cde0fdefd20f69b45bc25f5.
  • py_compile passes for all three bundled Python utilities before and after the one-line change.
  • git diff --check passes.
  • I can submit the one-line PR with the verified reproduction if a maintainer invites the contribution, in accordance with docs/contributing.md.
Dominant language
Rust
Stars
125k
Forks
19.5k
Avg merge
1m
Merged PRs (30d)
1k

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openai/codex

All issues in openai/codex

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.