mastra-ai/mastra · error · Error

Invalid skill "${name}": ${validation.errors.join('; ')}

Error message

Invalid skill "${name}": ${validation.errors.join('; ')}

What it means

createSkill() validates the assembled skill definition (frontmatter fields like name, description, license, compatibility, user-invocable, metadata, plus instructions) before returning the inline skill object. When validation reports any errors, createSkill throws with all error messages joined by semicolons. This surfaces schema/shape problems with the skill definition at creation time.

Source

Thrown at packages/core/src/skills/create-skill.ts:49

 * Create an inline skill from code — no filesystem needed.
 *
 * The returned object implements the `Skill` interface and can be passed
 * directly to an Agent's `skills` config or used anywhere a `Skill` is expected.
 *
 * @throws Error if the skill metadata fails validation
 */
export function createSkill(input: InlineSkillInput): InlineSkill {
  const { name, description, instructions, license, compatibility, metadata, references } = input;

  // Validate metadata (same checks as filesystem-discovered skills)
  const validation = validateSkillMetadata(
    { name, description, license, compatibility, 'user-invocable': input['user-invocable'], metadata },
    undefined,
    instructions,
  );

  if (!validation.valid) {
    throw new Error(`Invalid skill "${name}": ${validation.errors.join('; ')}`);
  }

  const referenceKeys = references ? Object.keys(references) : [];

  return {
    __inline: true as const,
    __referenceContents: references ?? {},
    name,
    description,
    instructions,
    license,
    compatibility,
    'user-invocable': input['user-invocable'],
    metadata,
    // Inline skills use a synthetic path: `inline/<name>`
    path: `inline/${name}`,
    source: { type: 'local', projectPath: `inline/${name}` },
    references: referenceKeys,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the joined error list in the message and fix each named field in the input to createSkill.
2. Ensure required frontmatter fields (name, description) are non-empty strings and compatibility/user-invocable/metadata match the documented schema.
3. If migrating from a file-based skill, parse SKILL.md frontmatter through the same validation path to find which fields are rejected.
4. Check field-name spelling against the current skill schema (APIs may have changed across versions).

Example fix

// before
createSkill({
  name: 'my-skill',
  compatable: 'claude', // typo'd field, description missing
  instructions: 'Do things',
});
// after
createSkill({
  name: 'my-skill',
  description: 'Does useful things',
  compatibility: 'claude',
  instructions: 'Do things',
});

function assertValidSkillInput(input) {
  const errors = [];
  if (!input || typeof input !== 'object') errors.push('input must be an object');
  if (typeof input?.name !== 'string' || !input.name.trim()) errors.push('name is required');
  if (typeof input?.description !== 'string' || !input.description.trim()) errors.push('description is required');
  if (input?.metadata && typeof input.metadata !== 'object') errors.push('metadata must be an object');
  if (errors.length) throw new TypeError(`Invalid skill input: ${errors.join('; ')}`);
}

function isSkillInput(x) {
  return typeof x === 'object' && x !== null &&
    typeof x.name === 'string' && x.name.length > 0 &&
    typeof x.description === 'string' && x.description.length > 0 &&
    typeof x.instructions === 'string';
}

try {
  const skill = createSkill(input);
} catch (e) {
  if (String(e?.message).startsWith('Invalid skill')) {
    // message lists each validation error joined by '; '
    console.error('Skill validation failed:', e.message);
    // fix fields per message, or surface to the user
  } else throw e;
}

When it happens

Trigger: Calling createSkill() (directly or via helpers like skill/skill1/skill2/ws/agentSkills/workspaceSkills) with input that fails validation — e.g. missing or malformed 'description', invalid 'compatibility' value, or bad metadata shape — such that validation.valid === false.

Common situations: Porting an existing SKILL.md frontmatter that omits required fields; hand-building skills in code with typos in field names (e.g. 'compatable'); programmatically generated metadata containing wrong types (array where object expected); older skill format not matching the current schema.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• ${label} contains an unsupported field.
• Invalid state update: ${messages}
• SchemaValidationError(field, this.formatErrors(result.error)
• INVALID_DATA_ITEM
• We could not convert the schema to a JSONSchema

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/7f41a8494e1970d5. Report an issue: GitHub.