{"record":{"id":"01569b798d05b4ba","repo":"mastra-ai/mastra","slug":"invalid-skill-metadata-in-filepath-validatio","errorCode":null,"errorMessage":"Invalid skill metadata in ${filePath}:\n${validation.errors.join('\\n')}","messagePattern":"Invalid skill metadata in (.+?):\n(.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/workspace/skills/workspace-skills.ts","lineNumber":1197,"sourceCode":"    // Extract required fields\n    // Get skill directory path (parent of SKILL.md) - needed for SkillMetadata\n    const skillPath = this.#getParentPath(filePath);\n\n    const metadata: SkillMetadata = {\n      name: frontmatter.name,\n      path: skillPath,\n      description: frontmatter.description,\n      license: frontmatter.license,\n      compatibility: frontmatter.compatibility,\n      'user-invocable': frontmatter['user-invocable'],\n      metadata: frontmatter.metadata,\n    };\n\n    // Validate if enabled (includes token/line count warnings)\n    if (this.#validateOnLoad) {\n      const validation = this.#validateSkillMetadata(metadata, dirName, body);\n      if (!validation.valid) {\n        throw new Error(`Invalid skill metadata in ${filePath}:\\n${validation.errors.join('\\n')}`);\n      }\n    }\n\n    // Discover reference, script, and asset files (parallel — independent subdirs)\n    const [references, scripts, assets] = await Promise.all([\n      this.#discoverFilesInSubdir(skillPath, 'references'),\n      this.#discoverFilesInSubdir(skillPath, 'scripts'),\n      this.#discoverFilesInSubdir(skillPath, 'assets'),\n    ]);\n\n    // Build indexable content (instructions + references)\n    const indexableContent = await this.#buildIndexableContent(body, skillPath, references);\n\n    return {\n      ...metadata,\n      instructions: body,\n      source,\n      references,","sourceCodeStart":1179,"sourceCodeEnd":1215,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/skills/workspace-skills.ts#L1179-L1215","documentation":"Thrown by WorkspaceSkillsImpl when a SKILL.md file's frontmatter metadata fails validation on load (enabled via #validateOnLoad). Validation also reports token/line-count warnings, but errors mean the skill definition is structurally invalid and cannot be loaded. The message includes the file path and each validation error joined by newlines.","triggerScenarios":"Loading a skill from a directory whose SKILL.md frontmatter is missing required fields (e.g. name/description), has fields of the wrong type, or whose body/section sizes exceed configured limits, while validateOnLoad is enabled.","commonSituations":"Hand-authored skill directories with typos in frontmatter keys; skills copied from other repos with older metadata formats; skills generated by tooling that omitted required fields; oversized skill bodies after heavy edits.","solutions":["Read the validation errors listed in the message and fix the SKILL.md frontmatter fields at the given filePath","Ensure required metadata fields (name matching the directory, non-empty description) exist with correct types","Split or shorten the skill body/references if token/line-count limit errors are reported","Set validateOnLoad to false only if you intentionally want to skip validation (not recommended)"],"exampleFix":"// before: .mastra/skills/my-skill/SKILL.md\n---\nname: My Skill\ndesc: does things\n---\n// after\n---\nname: my-skill\ndescription: Does things when invoked.\n---","handlingStrategy":"validation","validationCode":"function validateSkillMd(meta) {\n  const errors = [];\n  if (!meta?.name) errors.push('missing name');\n  if (!meta?.description) errors.push('missing description');\n  if (typeof meta?.name !== 'string') errors.push('name must be a string');\n  return { valid: errors.length === 0, errors };\n}","typeGuard":"function isValidSkillMetadata(m: unknown): m is { name: string; description: string } {\n  return !!m && typeof m === 'object' && typeof (m as any).name === 'string' && typeof (m as any).description === 'string';\n}","tryCatchPattern":"try {\n  const skill = await skills.loadSkill(dir);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Invalid skill metadata in')) {\n    console.error('Fix SKILL.md:', e.message);\n  } else throw e;\n}","preventionTips":["Validate SKILL.md frontmatter in CI with the same validator the library uses","Keep name identical to the skill directory name","Lint frontmatter with a JSON/YAML schema for skill metadata","Monitor token/line warnings before they become hard errors"],"tags":["skills","validation","frontmatter","workspace"],"backgroundTag":"skill-metadata-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}