False 'missing YAML frontmatter delimited by ---' for valid SKILL.md

[Morriz]

Summary

Codex CLI reported a frontmatter error for a skill file that does have valid YAML frontmatter at byte 0.

Observed in the interactive TUI output:

/Users/Morriz/.codex/skills/next-test-analyzer/SKILL.md: missing YAML frontmatter delimited by ---

Environment

• codex-cli 0.98.0
• macOS 26.1 (Darwin 25.1.0, arm64)

Why this looks incorrect

The file starts with --- with no leading bytes/whitespace:

$ head -n 8 /Users/Morriz/.codex/skills/next-test-analyzer/SKILL.md
---
name: next-test-analyzer
description: Review test coverage quality and completeness. Use after creating a PR or adding new functionality to ensure tests adequately cover new code and edge cases.
---

$ xxd -g 1 -l 12 /Users/Morriz/.codex/skills/next-test-analyzer/SKILL.md
00000000: 2d 2d 2d 0a 6e 61 6d 65 3a 20 6e 65  ---.name: ne

Expected behavior

No "missing YAML frontmatter" error should be emitted for this file.

Actual behavior

CLI reports missing frontmatter for this path despite valid delimiter and metadata.

Notes

I saw this in TUI output just before sending another prompt. I have not yet found a deterministic minimal repro; this may be intermittent in skill scanning/parsing.

If helpful, I can capture a debug run (RUST_LOG etc.) once you suggest the best flags.

[etraut-openai]

Was this skill recently created? We recently added live detection of skill updates via a file watcher. It's likely that the skill was saved prior to being complete, and codex tried to load it and reported the frontmatter error.

Based on user feedback, I'm increasing the debounce period for the file watcher from 1s to 10s, which should help mitigate errors like this from being reported.

[etraut-openai]

The increased debounce period will be included in the next release.