False 'missing YAML frontmatter delimited by ---' for valid SKILL.md
Resolved 💬 5 comments Opened Feb 11, 2026 by Morriz Closed Feb 14, 2026
💡 Likely answer: A maintainer (etraut-openai, contributor)
responded on this thread — see the highlighted reply below.
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(Darwin25.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: neExpected 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.
5 Comments
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.
The increased debounce period will be included in the next release.
Hi, I get this with skills created by other agents - because there's no official skill standard - it's just markdown.
I would ask that Codex cli respect that.
@dinedal, there is an official skills standard: https://agentskills.io/specification.
@etraut-openai TIL thanks