crewAIInc/crewAI · error · SystemExit

Failed to parse SKILL.md frontmatter: {exc}

Error message

Failed to parse SKILL.md frontmatter: {exc}

What it means

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.

Source

Thrown at lib/cli/src/crewai_cli/skills/main.py:235

                    )
                    raise SystemExit(1) from exc
            if repository is not None and not repository.is_synced():
                console.print(
                    "[bold red]Failed to publish skill.[/bold red]\n"
                    "Local changes need to be resolved before publishing. Please do the following:\n"
                    "* [bold]Commit[/bold] your changes.\n"
                    "* [bold]Push[/bold] to sync with the remote.\n"
                    "* [bold]Pull[/bold] the latest changes from the remote.\n"
                    "\nOnce your repository is up-to-date, retry publishing the skill "
                    "(or pass --force to skip this check)."
                )
                raise SystemExit(1)

        try:
            frontmatter = self._parse_frontmatter(skill_md.read_text(encoding="utf-8"))
        except ValueError as exc:
            console.print(f"[red]Failed to parse SKILL.md frontmatter: {exc}[/red]")
            raise SystemExit(1) from exc

        name = frontmatter.get("name")
        raw_metadata = frontmatter.get("metadata")
        version = (
            raw_metadata.get("version") if isinstance(raw_metadata, dict) else None
        )
        description = frontmatter.get("description")

        if not name:
            console.print(
                "[red]SKILL.md frontmatter must include a 'name' field.[/red]"
            )
            raise SystemExit(1)

        if not version:
            console.print(
                "[red]SKILL.md frontmatter must include a 'version' field before publishing.[/red]"
            )

View on GitHub (pinned to 754d7323be)

Solutions

1. 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])"`).
2. Fix indentation to spaces-only and quote values containing colons or special characters.
3. If frontmatter is missing entirely, add one with `name`, `description`, and `metadata.version` fields.

Example fix

# before (SKILL.md)
name: my-skill
metadata:
  version: 1.0.0   # ValueError: float, not string; or broken indent
---
# body...

# after
---
name: my-skill
description: Does a thing.
metadata:
  version: "1.0.0"
---
# body...

import re, yaml
from pathlib import Path

def frontmatter_parses(path: str = "SKILL.md") -> bool:
    text = Path(path).read_text(encoding="utf-8")
    m = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
    if not m:
        return False
    try:
        yaml.safe_load(m.group(1))
        return True
    except yaml.YAMLError:
        return False

try:
    publish()
except SystemExit:
    if not frontmatter_parses():
        fix_frontmatter()  # repair delimiters/indentation, then retry

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• SKILL.md frontmatter must include a 'name' field.
• SKILL.md frontmatter must include a 'version' field before p
• No YAML frontmatter block found
• No SKILL.md found in current directory. Run this command fro
• Unable to validate git state: {exc} Fix the issue or pass --

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/391e2970b9fcafdf. Report an issue: GitHub.