{"record":{"id":"335c3c7fb7b6c3dc","repo":"crewAIInc/crewAI","slug":"skill-md-frontmatter-must-include-a-version-fiel","errorCode":null,"errorMessage":"SKILL.md frontmatter must include a 'version' field before publishing.","messagePattern":"SKILL\\.md frontmatter must include a 'version' field before publishing\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"lib/cli/src/crewai_cli/skills/main.py","lineNumber":254,"sourceCode":"\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(\n            f\"[bold blue]Publishing skill [bold]{name}[/bold] v{version} to {effective_org}...[/bold blue]\"\n        )\n\n        archive_bytes = self._build_skill_tarball()\n        encoded_file = \"data:application/x-gzip;base64,\" + base64.b64encode(\n            archive_bytes","sourceCodeStart":236,"sourceCodeEnd":272,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/cli/src/crewai_cli/skills/main.py#L236-L272","documentation":"Publishing requires a version string, read as `metadata.version` from the SKILL.md frontmatter (`raw_metadata.get(\"version\")` when `metadata` is a dict). If absent, empty, or `metadata` itself is missing/not a mapping, the CLI exits because the registry needs an explicit version for each upload.","triggerScenarios":"Running `crewai skill publish` where frontmatter lacks a `metadata:` block, has `metadata:` without a `version:` key, sets `version: \"\"`, or has `version` as a top-level key instead of under `metadata`. A YAML `version: 1.0.0` unquoted float still passes this check but is later sent as a number.","commonSituations":"Scaffolding by hand and forgetting version; placing `version:` at top level; bumping version in the wrong place before republishing.","solutions":["Add `metadata:\\n  version: \"1.0.0\"` to the frontmatter (quoted string recommended) and retry.","Bump this version on every subsequent publish so the registry accepts the new upload.","Ensure `metadata` is a YAML mapping, not a scalar string."],"exampleFix":"# before\n---\nname: research-helper\nversion: \"1.0.0\"\n---\n\n# after\n---\nname: research-helper\nmetadata:\n  version: \"1.0.0\"\n---","handlingStrategy":"validation","validationCode":"def has_version_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 isinstance(fm.get(\"metadata\"), dict) and bool(fm[\"metadata\"].get(\"version\"))","typeGuard":"def has_publishable_version(fm: dict) -> bool:\n    \"\"\"True when metadata.version exists and is a non-empty scalar.\"\"\"\n    md = fm.get(\"metadata\")\n    return isinstance(md, dict) and bool(str(md.get(\"version\") or \"\").strip())","tryCatchPattern":null,"preventionTips":["Store the version under `metadata.version`, quoted as a string (\"1.0.0\").","Bump the version on every content change so republishing is accepted.","Automate the bump in the same commit as the change."],"tags":["cli","yaml","frontmatter","publish","skill","versioning"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}