## 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: ```text Description must be a string, got list ``` The source is: ```text codex-rs/skills/src/assets/samples/skill-creator/scripts/init_skill.py ``` At current `main` (`ed2f985a26eee9a59cde0fdefd20f69b45bc25f5`), the template contains: ```yaml description: [TODO: Complete and i

skill-creator initializer generates invalid description frontmatter

Open 💬 1 comment Opened Aug 5, 2026 by techronin

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.

View original on GitHub ↗

1 Comment

ded-furby · 23 days ago

I confirmed the root cause in the skill template: the description field is unquoted with [...], so YAML parses it as a sequence rather than a string and quick_validate rejects newly generated skills immediately.

A one-line fix is to quote that placeholder value while leaving the TODO text unchanged. This avoids changing template meaning and should be a minimal, low-risk change.

Since this appears to be the first parser-facing failure in the init_skill.py flow, I also recommend a regression check that runs quick_validate.py on fresh output from init_skill.py.

I’m flagging this here because external code PRs are still invite-only in this repo (docs/contributing.md), so issue-level analysis is the safest path for follow-up.