{"record":{"id":"9fdeecf46b377322","repo":"mastra-ai/mastra","slug":"skill-not-found","errorCode":"skill_not_found","errorMessage":"skill_not_found","messagePattern":"skill_not_found","errorType":"error_code","errorClass":"SkillInvocationError","httpStatus":null,"severity":"error","filePath":"mastracode/factory/src/skills/service.ts","lineNumber":71,"sourceCode":"  input: { resourceId: string; scope?: SkillInvocationInput['scope']; prompt: string },\n): Promise<{ session: SkillSession; message: string }> {\n  const session = (await controller.getSessionByResource(input.resourceId, input.scope)) as SkillSession | undefined;\n  if (!session) throw new SkillInvocationError('session_not_found', 'Agent controller session not found.');\n  return { session, message: input.prompt };\n}\n\nexport async function resolveSkillInvocation(\n  controller: Pick<AgentController<MastraCodeState>, 'getSessionByResource'>,\n  input: SkillInvocationInput,\n): Promise<{ session: SkillSession; skillName: string; message: string }> {\n  const session = (await controller.getSessionByResource(input.resourceId, input.scope)) as SkillSession | undefined;\n  if (!session) throw new SkillInvocationError('session_not_found', 'Agent controller session not found.');\n\n  const skills = session.getWorkspace().skills;\n  await skills?.maybeRefresh();\n  const skill = await skills?.get(input.name);\n  if (!skill || skill['user-invocable'] === false) {\n    throw new SkillInvocationError('skill_not_found', `Skill not found: ${input.name}.`);\n  }\n\n  const args = input.arguments?.trim();\n  const content = `${formatSkillActivation(skill)}${args ? `\\n\\nARGUMENTS: ${args}` : ''}`.trim();\n  return {\n    session,\n    skillName: skill.name,\n    message: `<skill name=\"${skill.name}\">\\n${escapeSkillBoundary(content)}\\n</skill>`,\n  };\n}\n\nexport async function dispatchSkillInvocation(\n  controller: Pick<AgentController<MastraCodeState>, 'getSessionByResource'>,\n  input: SkillInvocationInput,\n): Promise<{ skillName: string; message: string }> {\n  const resolved = await resolveSkillInvocation(controller, input);\n  await resolved.session.sendMessage({ content: resolved.message });\n  return { skillName: resolved.skillName, message: resolved.message };","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory/src/skills/service.ts#L53-L89","documentation":"resolveSkillInvocation found the session, refreshed workspace skills, but skills.get(input.name) returned nothing or the skill has 'user-invocable': false. It throws SkillInvocationError('skill_not_found') with the skill name in the message.","triggerScenarios":"Invoking a skill whose name doesn't exist in the session workspace's skills directory, a typo in input.name, or invoking a skill marked 'user-invocable': false in its frontmatter.","commonSituations":"Skill added after the session's workspace snapshot (refresh pending or not persisted); skill name mismatch (directory name vs frontmatter name); skill intentionally restricted to agent-only invocation.","solutions":["Check the skill name matches the skills directory/frontmatter exactly","Ensure the skill frontmatter does not set 'user-invocable': false","Call skills.maybeRefresh() or reload the workspace so newly added skills are visible","List available skills from session.getWorkspace().skills to confirm the name"],"exampleFix":"// before\nawait resolveSkillInvocation(controller, { resourceId, name: 'Deploy-Skill' });\n// after\nconst skills = session.getWorkspace().skills;\nif (skills && !(await skills.get('deploy-skill'))) throw new Error('skill not installed in workspace');\nawait resolveSkillInvocation(controller, { resourceId, name: 'deploy-skill' });","handlingStrategy":"validation","validationCode":"const skills = session.getWorkspace().skills;\nawait skills?.maybeRefresh();\nconst skill = await skills?.get(name);\nif (!skill || skill['user-invocable'] === false) {\n  throw new Error(`Skill \"${name}\" missing or not user-invocable in this workspace`);\n}","typeGuard":"function isInvocableSkill(s: { 'user-invocable'?: boolean } | undefined): boolean {\n  return s != null && s['user-invocable'] !== false;\n}","tryCatchPattern":"try {\n  await resolveSkillInvocation(controller, input);\n} catch (e) {\n  if (e instanceof SkillInvocationError && e.code === 'skill_not_found') {\n    const available = await session.getWorkspace().skills?.list?.() ?? [];\n    throw new Error(`Unknown skill \"${input.name}\". Available: ${available.join(', ')}`);\n  }\n  throw e;\n}","preventionTips":["Refresh the skills workspace after installing new skills","Match skill names exactly as in the directory/frontmatter","Check frontmatter 'user-invocable' before exposing the skill to users","Surface a skill list to callers instead of free-form names"],"tags":["skill","not-found","workspace"],"backgroundTag":"skill-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}