{"record":{"id":"aaf61090f12c1b9c","repo":"mastra-ai/mastra","slug":"skill-identifier-not-found","errorCode":null,"errorMessage":"Skill \"${identifier}\" not found","messagePattern":"Skill \"(.+?)\" not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/agents.ts","lineNumber":3629,"sourceCode":"  queryParamSchema: skillDisambiguationQuerySchema,\n  responseSchema: getAgentSkillResponseSchema,\n  summary: 'Get agent skill',\n  description: 'Returns details for a specific skill available to the agent (inline or workspace)',\n  tags: ['Agents', 'Skills'],\n  handler: async ({ mastra, agentId, skillName, path, requestContext }) => {\n    try {\n      const agent = agentId ? mastra.getAgentById(agentId) : null;\n      if (!agent) {\n        throw new HTTPException(404, { message: 'Agent not found' });\n      }\n\n      // Use the optional ?path= query param for disambiguation, otherwise fall back to name\n      const identifier = path ? decodeURIComponent(path) : skillName;\n\n      // Get the skill from the agent (searches both inline and workspace skills)\n      const skill = await agent.getSkill(identifier, { requestContext });\n      if (!skill) {\n        throw new HTTPException(404, { message: `Skill \"${identifier}\" not found` });\n      }\n\n      return {\n        name: skill.name,\n        description: skill.description,\n        license: skill.license,\n        compatibility: skill.compatibility,\n        metadata: skill.metadata,\n        path: skill.path,\n        instructions: skill.instructions,\n        source: skill.source,\n        references: skill.references,\n        scripts: skill.scripts,\n        assets: skill.assets,\n      };\n    } catch (error) {\n      return handleError(error, 'Error getting agent skill');\n    }","sourceCodeStart":3611,"sourceCodeEnd":3647,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/agents.ts#L3611-L3647","documentation":"This HTTP 404 error is thrown when `agent.getSkill(identifier, { requestContext })` returns no skill. The lookup searches the agent's inline skills and workspace skills, using the `?path=` query param for disambiguation when given, otherwise the `:skillName` path param.","triggerScenarios":"GET /api/agents/:agentId/skills/:skillName where the skill name doesn't match any inline or workspace skill on that agent, or multiple skills share a name and no ?path= disambiguator is provided in a way that resolves one.","commonSituations":"Typo in skill name; skill file not loaded into the agent's workspace; skill exists on a different agent; name vs path mismatch (the identifier falls back to skillName when ?path= is absent); case sensitivity.","solutions":["Confirm the exact skill name/path exists on the agent (e.g. via the agent's skills list endpoint) and correct the request.","If multiple skills share a name, pass the ?path= query param with the encoded path to disambiguate.","Ensure the skill is actually present in the agent's inline skills or workspace and the server was restarted after adding it."],"exampleFix":"// before\nGET /api/agents/myAgent/skills/My-Skill   // case mismatch\n// after\nGET /api/agents/myAgent/skills/my-skill?path=%2Fskills%2Fmy-skill%2FSKILL.md","handlingStrategy":"validation","validationCode":"// list skills for the agent first and check the name\nconst res = await fetch(`/api/agents/${agentId}/skills`);\nconst skills = await res.json();\nif (!skills.some(s => s.name === skillName)) {\n  throw new Error(`Skill \"${skillName}\" not available on agent ${agentId}`);\n}","typeGuard":"function hasSkill(skills: { name: string }[], name: string): boolean {\n  return skills.some(s => s.name === name);\n}","tryCatchPattern":"try {\n  const res = await fetch(`/api/agents/${agentId}/skills/${encodeURIComponent(skillName)}`);\n  if (res.status === 404) throw new Error(`Skill \"${skillName}\" not found`);\n  return await res.json();\n} catch (e) { /* offer the user the list of valid skills */ }","preventionTips":["List the agent's skills before requesting one by name.","Pass ?path= when skill names are ambiguous or duplicated.","URL-encode skill names/paths in request URLs."],"tags":["http-404","skill-not-found","routing"],"backgroundTag":"resource-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}