crewAIInc/crewAI · error · SystemExit

SKILL.md frontmatter must include a 'name' field.

Error message

SKILL.md frontmatter must include a 'name' field.

What it means

Publishing requires a `name` key in the SKILL.md frontmatter because that name becomes the registry identifier (`@org/<name>`). If `frontmatter.get("name")` is falsy (missing, empty, or null), the CLI exits with SystemExit(1).

Source

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

        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]"
            )
            raise SystemExit(1)

        settings = Settings()
        effective_org = org or settings.org_name
        if not effective_org:
            console.print(
                "[red]No organisation set. Run `crewai org switch <org_id>` first, "
                "or pass --org.[/red]"
            )
            raise SystemExit(1)

        self._print_current_organization()
        console.print(

View on GitHub (pinned to 754d7323be)

Solutions

1. Add a top-level `name: my-skill` field to the SKILL.md frontmatter and retry.
2. Make sure it is top-level (not inside `metadata:`) and non-empty.
3. Re-run publish and confirm the name matches the intended registry reference segment.

Example fix

# before (SKILL.md frontmatter)
---
description: Helps with research.
metadata:
  version: "1.0.0"
---

# after
---
name: research-helper
description: Helps with research.
metadata:
  version: "1.0.0"
---

from pathlib import Path
import re, yaml

def has_name_field(path: str = "SKILL.md") -> bool:
    m = re.match(r"^---\n(.*?)\n---", Path(path).read_text(encoding="utf-8"), re.DOTALL)
    if not m:
        return False
    fm = yaml.safe_load(m.group(1)) or {}
    return bool(isinstance(fm, dict) and fm.get("name"))

def is_publishable_frontmatter(fm: dict) -> bool:
    """True when the parsed frontmatter carries a non-empty top-level name."""
    return isinstance(fm, dict) and isinstance(fm.get("name"), str) and bool(fm["name"].strip())

When it happens

Trigger: Running `crewai skill publish` on a SKILL.md whose frontmatter has `description` and `metadata` but no `name:`, has `name:` with an empty value, or where `name` is nested under `metadata` instead of top-level.

Common situations: Using a template that omits `name`; nesting all fields under `metadata:`; a trailing-space typo like `name :` that the naive fallback parser mis-reads; `name:` set to `null`.

Related errors

• Failed to parse SKILL.md frontmatter: {exc}
• SKILL.md frontmatter must include a 'version' field before p
• No YAML frontmatter block found
• Invalid skill reference. Use the format @org/name.
• Invalid skill reference: org and name must be single, non-em

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