mastra-ai/mastra · error

SKILL.md not found in ${skillPath}

Error message

SKILL.md not found in ${skillPath}

What it means

collectSkillForPublish gathers all files under a skill directory and then parses a snapshot; when the underlying parse fails because SKILL.md is absent, it rethrows with the skill's path included so the developer knows which directory is broken. This is the user-facing form of the 'SKILL.md not found in skill files' error.

Source

Thrown at packages/core/src/workspace/skills/publish.ts:330

          mimeType,
          createdAt: now,
        });
      }
    }
  }

  const tree: SkillVersionTree = { entries: treeEntries };
  const blobs = Array.from(blobMap.values());
  const fileNodes = buildSkillFileNodes(files);

  // 3. Parse SKILL.md frontmatter and discover references/scripts/assets paths
  let snapshot: Omit<StorageSkillSnapshotType, 'tree'>;
  try {
    snapshot = parseSkillSnapshotFromFiles(files);
  } catch (err) {
    // Surface the skill path to make the error easier to debug
    if (err instanceof Error && err.message.includes('SKILL.md not found')) {
      throw new Error(`SKILL.md not found in ${skillPath}`);
    }
    throw err;
  }

  return { snapshot, tree, blobs, files: fileNodes };
}

/**
 * Publish a skill: collect files, store blobs, create version.
 * This is the full publish flow.
 *
 * @param source - The SkillSource to read from
 * @param skillPath - Path to the skill directory
 * @param blobStore - Where to store file blobs
 */
export async function publishSkillFromSource(
  source: SkillSource,
  skillPath: string,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Create or restore SKILL.md at the root of the directory passed as skillPath, with valid frontmatter.
2. Check the spelling/casing of the filename — it must be exactly 'SKILL.md'.
3. Confirm skillPath points at the skill directory itself, not its parent or a subfolder.
4. Review any include/exclude globs in the collection step so SKILL.md isn't filtered out.

Example fix

// before
await collectSkillForPublish('./skills/my-skill'); // dir has only assets/
// after
// add ./skills/my-skill/SKILL.md with frontmatter:
// ---
// name: my-skill
// description: ...
// ---
await collectSkillForPublish('./skills/my-skill');

import { existsSync } from 'node:fs';
if (!existsSync(`${skillPath}/SKILL.md`)) {
  throw new Error(`Refusing to publish '${skillPath}': missing SKILL.md`);
}
const result = await collectSkillForPublish(skillPath);

try {
  return await collectSkillForPublish(skillPath);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('SKILL.md not found in')) {
    // guide the user to add SKILL.md at that path
  }
  throw err;
}

When it happens

Trigger: Calling collectSkillForPublish(skillPath) where the directory at skillPath has no root-level SKILL.md (missing, misnamed, or excluded by collection filters).

Common situations: Publishing a freshly scaffolded skill folder where only assets were copied; renaming SKILL.md to something else; .gitignore-like filters dropping SKILL.md; wrong skillPath passed (parent dir instead of the skill dir).

Related errors

• SKILL.md not found in skill files
• Invalid skill "${name}": ${validation.errors.join('; ')}
• Invalid skill metadata in ${filePath}: ${validation.errors.j
• Invalid ${label} path: ${input}
• Invalid skill name "${name}". Names must start with alphanum

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