{"record":{"id":"5502265d7622d6e3","repo":"crewAIInc/crewAI","slug":"skill-md-frontmatter-must-include-a-name-field","errorCode":null,"errorMessage":"SKILL.md frontmatter must include a 'name' field.","messagePattern":"SKILL\\.md frontmatter must include a 'name' field\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"lib/cli/src/crewai_cli/skills/main.py","lineNumber":248,"sourceCode":"\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            )\n            raise SystemExit(1)\n\n        settings = Settings()\n        effective_org = org or settings.org_name\n        if not effective_org:\n            console.print(\n                \"[red]No organisation set. Run `crewai org switch <org_id>` first, \"\n                \"or pass --org.[/red]\"\n            )\n            raise SystemExit(1)\n\n        self._print_current_organization()\n        console.print(","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/cli/src/crewai_cli/skills/main.py#L230-L266","documentation":"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).","triggerScenarios":"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.","commonSituations":"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`.","solutions":["Add a top-level `name: my-skill` field to the SKILL.md frontmatter and retry.","Make sure it is top-level (not inside `metadata:`) and non-empty.","Re-run publish and confirm the name matches the intended registry reference segment."],"exampleFix":"# before (SKILL.md frontmatter)\n---\ndescription: Helps with research.\nmetadata:\n  version: \"1.0.0\"\n---\n\n# after\n---\nname: research-helper\ndescription: Helps with research.\nmetadata:\n  version: \"1.0.0\"\n---","handlingStrategy":"validation","validationCode":"from pathlib import Path\nimport re, yaml\n\ndef has_name_field(path: str = \"SKILL.md\") -> bool:\n    m = re.match(r\"^---\\n(.*?)\\n---\", Path(path).read_text(encoding=\"utf-8\"), re.DOTALL)\n    if not m:\n        return False\n    fm = yaml.safe_load(m.group(1)) or {}\n    return bool(isinstance(fm, dict) and fm.get(\"name\"))","typeGuard":"def is_publishable_frontmatter(fm: dict) -> bool:\n    \"\"\"True when the parsed frontmatter carries a non-empty top-level name.\"\"\"\n    return isinstance(fm, dict) and isinstance(fm.get(\"name\"), str) and bool(fm[\"name\"].strip())","tryCatchPattern":null,"preventionTips":["Keep `name:` top-level in frontmatter, not nested under `metadata:`.","Generate SKILL.md with `crewai skill create` so required fields are pre-filled.","Add a pre-publish lint step that checks for non-empty `name`."],"tags":["cli","yaml","frontmatter","publish","skill","validation"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}