OpenBMB/ChatDev · error · ValueError

missing frontmatter

Error message

missing frontmatter

What it means

_parse_frontmatter in skills.py reads a skill markdown file and requires it to begin with '---'. A file that does not start with the frontmatter delimiter raises ValueError('missing frontmatter'). It is called during default skill discovery, so a malformed bundled/local skill file surfaces here.

Source

Thrown at entity/configs/node/skills.py:50

            continue
        try:
            frontmatter = _parse_frontmatter(skill_file)
        except Exception:
            continue
        raw_name = frontmatter.get("name")
        raw_description = frontmatter.get("description")
        if not isinstance(raw_name, str) or not raw_name.strip():
            continue
        if not isinstance(raw_description, str) or not raw_description.strip():
            continue
        discovered.append((raw_name.strip(), raw_description.strip()))
    return discovered


def _parse_frontmatter(skill_file: Path) -> Mapping[str, object]:
    text = skill_file.read_text(encoding="utf-8")
    if not text.startswith("---"):
        raise ValueError("missing frontmatter")
    lines = text.splitlines()
    end_idx = None
    for idx in range(1, len(lines)):
        if lines[idx].strip() == "---":
            end_idx = idx
            break
    if end_idx is None:
        raise ValueError("missing closing delimiter")
    payload = "\n".join(lines[1:end_idx])
    data = yaml.safe_load(payload) or {}
    if not isinstance(data, Mapping):
        raise ValueError("frontmatter must be a mapping")
    return data


@dataclass
class AgentSkillSelectionConfig(BaseConfig):
    name: str

View on GitHub (pinned to 4fb2db0ea9)

Solutions

1. Start the skill file with '---' on the first line followed by YAML frontmatter and a closing '---'
2. Remove any BOM or leading blank lines from the file
3. Remove non-skill markdown files from the skills directory

Example fix

# before
# My skill doc
Some prose...
# after
---
name: my-skill
description: does a thing
---
Some prose...

text = path.read_text(encoding='utf-8')
assert text.startswith('---'), 'skill file must start with frontmatter'

try:
    _discover_default_skills(skills_dir)
except ValueError as e:
    if 'missing frontmatter' in str(e):
        # skip/repair the offending file, log its path
        ...

When it happens

Trigger: A skill .md file in the skills directory that lacks the leading '---' line (e.g. starts with prose, a BOM, or blank line) while _discover_default_skills parses it.

Common situations: Hand-authored skill files missing frontmatter; editors adding a BOM or leading blank line; renaming non-skill markdown files into the skills directory.

Related errors

• missing closing delimiter
• frontmatter must be a mapping
• skill name is required
• expected list of skill entries
• expected skill entry mapping or string

AI-assisted analysis of OpenBMB/ChatDev@4fb2db0ea9 (2026-08-27). Data as JSON: /api/errors/ce45cc334863e842. Report an issue: GitHub.