{"record":{"id":"391e2970b9fcafdf","repo":"crewAIInc/crewAI","slug":"failed-to-parse-skill-md-frontmatter-exc","errorCode":null,"errorMessage":"Failed to parse SKILL.md frontmatter: {exc}","messagePattern":"Failed to parse SKILL\\.md frontmatter: (.+?)","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"lib/cli/src/crewai_cli/skills/main.py","lineNumber":235,"sourceCode":"                    )\n                    raise SystemExit(1) from exc\n            if repository is not None and not repository.is_synced():\n                console.print(\n                    \"[bold red]Failed to publish skill.[/bold red]\\n\"\n                    \"Local changes need to be resolved before publishing. Please do the following:\\n\"\n                    \"* [bold]Commit[/bold] your changes.\\n\"\n                    \"* [bold]Push[/bold] to sync with the remote.\\n\"\n                    \"* [bold]Pull[/bold] the latest changes from the remote.\\n\"\n                    \"\\nOnce your repository is up-to-date, retry publishing the skill \"\n                    \"(or pass --force to skip this check).\"\n                )\n                raise SystemExit(1)\n\n        try:\n            frontmatter = self._parse_frontmatter(skill_md.read_text(encoding=\"utf-8\"))\n        except ValueError as exc:\n            console.print(f\"[red]Failed to parse SKILL.md frontmatter: {exc}[/red]\")\n            raise SystemExit(1) from exc\n\n        name = frontmatter.get(\"name\")\n        raw_metadata = frontmatter.get(\"metadata\")\n        version = (\n            raw_metadata.get(\"version\") if isinstance(raw_metadata, dict) else None\n        )\n        description = frontmatter.get(\"description\")\n\n        if not name:\n            console.print(\n                \"[red]SKILL.md frontmatter must include a 'name' field.[/red]\"\n            )\n            raise SystemExit(1)\n\n        if not version:\n            console.print(\n                \"[red]SKILL.md frontmatter must include a 'version' field before publishing.[/red]\"\n            )","sourceCodeStart":217,"sourceCodeEnd":253,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/cli/src/crewai_cli/skills/main.py#L217-L253","documentation":"The SKILL.md frontmatter could not be parsed. `self._parse_frontmatter(...)` raises `ValueError` either because no `---`-delimited YAML block was found, or (via the SDK's `parse_frontmatter`) because the YAML content is malformed. The original exception message is included in the printed error.","triggerScenarios":"Running `crewai skill publish` on a SKILL.md whose frontmatter delimiters are missing, mis-ordered, or not at byte 0 (e.g. a BOM or leading blank line before `---`), or whose YAML has syntax errors (bad indentation, unquoted colons, tabs).","commonSituations":"Hand-editing SKILL.md and breaking YAML indentation; tools that prepend a BOM; frontmatter written with `...` instead of closing `---`; tabs copied from rich-text editors.","solutions":["Open SKILL.md and verify it starts with `---` on line 1, has a closing `---`, and contains valid YAML (validate with `python -c \"import yaml,sys; yaml.safe_load(open('SKILL.md').read().split('---')[1])\"`).","Fix indentation to spaces-only and quote values containing colons or special characters.","If frontmatter is missing entirely, add one with `name`, `description`, and `metadata.version` fields."],"exampleFix":"# before (SKILL.md)\nname: my-skill\nmetadata:\n  version: 1.0.0   # ValueError: float, not string; or broken indent\n---\n# body...\n\n# after\n---\nname: my-skill\ndescription: Does a thing.\nmetadata:\n  version: \"1.0.0\"\n---\n# body...","handlingStrategy":"try-catch","validationCode":"import re, yaml\nfrom pathlib import Path\n\ndef frontmatter_parses(path: str = \"SKILL.md\") -> bool:\n    text = Path(path).read_text(encoding=\"utf-8\")\n    m = re.match(r\"^---\\n(.*?)\\n---\", text, re.DOTALL)\n    if not m:\n        return False\n    try:\n        yaml.safe_load(m.group(1))\n        return True\n    except yaml.YAMLError:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    publish()\nexcept SystemExit:\n    if not frontmatter_parses():\n        fix_frontmatter()  # repair delimiters/indentation, then retry","preventionTips":["Start SKILL.md with `---` on line 1 (no BOM, no blank line) and close the block with `---`.","Use spaces only (never tabs) and quote values containing colons.","Validate frontmatter with a YAML linter before publishing."],"tags":["cli","yaml","frontmatter","publish","skill"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}