{"record":{"id":"a9748c95bc0ff06c","repo":"OpenBMB/ChatDev","slug":"frontmatter-must-be-a-mapping","errorCode":null,"errorMessage":"frontmatter must be a mapping","messagePattern":"frontmatter must be a mapping","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"entity/configs/node/skills.py","lineNumber":62,"sourceCode":"    return discovered\n\n\ndef _parse_frontmatter(skill_file: Path) -> Mapping[str, object]:\n    text = skill_file.read_text(encoding=\"utf-8\")\n    if not text.startswith(\"---\"):\n        raise ValueError(\"missing frontmatter\")\n    lines = text.splitlines()\n    end_idx = None\n    for idx in range(1, len(lines)):\n        if lines[idx].strip() == \"---\":\n            end_idx = idx\n            break\n    if end_idx is None:\n        raise ValueError(\"missing closing delimiter\")\n    payload = \"\\n\".join(lines[1:end_idx])\n    data = yaml.safe_load(payload) or {}\n    if not isinstance(data, Mapping):\n        raise ValueError(\"frontmatter must be a mapping\")\n    return data\n\n\n@dataclass\nclass AgentSkillSelectionConfig(BaseConfig):\n    name: str\n\n    FIELD_SPECS = {\n        \"name\": ConfigFieldSpec(\n            name=\"name\",\n            display_name=\"Skill Name\",\n            type_hint=\"str\",\n            required=True,\n            description=\"Discovered skill name from the default repo-level skills directory.\",\n        ),\n    }\n\n    @classmethod","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/OpenBMB/ChatDev/blob/4fb2db0ea90375ce1059f44fe03ffbd191a7a169/entity/configs/node/skills.py#L44-L80","documentation":"Once the frontmatter block is extracted, _parse_frontmatter yaml.safe_loads it and requires the result to be a Mapping. A YAML scalar or list at the top level (e.g. a bare string or '- a' sequence) raises ValueError('frontmatter must be a mapping').","triggerScenarios":"Skill frontmatter whose top-level YAML is a scalar (e.g. just 'my-skill') or a sequence ('- name: x') instead of key: value pairs.","commonSituations":"Authors writing a title line instead of key-value metadata; YAML syntax errors that make safe_load return a string; list-style frontmatter borrowed from other tools.","solutions":["Rewrite frontmatter as key: value mappings (name:, description:, ...), one pair per line","Validate the block with a YAML linter before shipping","Check for missing colons or misindentation that degrade the mapping"],"exampleFix":"# before\n---\nmy-skill\n---\n# after\n---\nname: my-skill\ndescription: does a thing\n---","handlingStrategy":"validation","validationCode":"import yaml\npayload = text.split('---')[1]\ndata = yaml.safe_load(payload)\nassert isinstance(data, dict), 'frontmatter must be key: value YAML'","typeGuard":null,"tryCatchPattern":"try:\n    _discover_default_skills(skills_dir)\nexcept ValueError as e:\n    if 'must be a mapping' in str(e):\n        # rewrite file frontmatter from a default template\n        ...","preventionTips":["Start frontmatter with name:/description: keys","Use a YAML linter on the frontmatter block"],"tags":["skills","frontmatter","yaml","parsing"],"backgroundTag":"malformed-frontmatter","analyzedSha":"4fb2db0ea90375ce1059f44fe03ffbd191a7a169","analyzedAt":"2026-08-27T14:35:29.622Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}