@mastra/mcp-docs-server 1.2.1-alpha.4 → 1.2.1-alpha.5

package/.docs/docs/agent-builder/overview.md

@@ -2,6 +2,8 @@
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
 
+[YouTube video player](https://www.youtube-nocookie.com/embed/AbdgIu4Z07I)
+
 The Agent Builder lets you build, configure, and operate Mastra agents all within the UI. It runs inside your Mastra server, persists everything to `Mastra.storage`, and supports multi-tenant agent workflows with RBAC and channel integrations.
 
 - [**Configuration**](https://mastra.ai/docs/agent-builder/configuration): Toggle UI sections and pin admin-controlled defaults for every new agent.

package/.docs/docs/agents/skills.md

@@ -0,0 +1,186 @@
+# Agent skills
+
+Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io).
+
+You can attach skills directly to an agent without setting up a workspace, filesystem, or sandbox. This is useful when you want portable, code-defined capabilities that travel with your agent definition.
+
+## When to use agent-level skills
+
+Use agent-level skills when:
+
+- You want self-contained agents that don't depend on a workspace
+- Skills are defined in code and don't need filesystem discovery
+- You're building packages or libraries that ship agent capabilities
+- You need per-request skill resolution based on context
+
+For filesystem-based skill discovery across a project, use [workspace skills](https://mastra.ai/docs/workspace/skills) instead.
+
+## Quickstart
+
+Define a skill inline and attach it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSkill } from '@mastra/core/skills'
+
+const codeReview = createSkill({
+  name: 'code-review',
+  description: 'Use when reviewing code changes.',
+  instructions: `
+    When reviewing code:
+    1. Check for correctness and edge cases
+    2. Verify style consistency
+    3. Look for potential bugs
+  `,
+})
+
+export const reviewer = new Agent({
+  id: 'reviewer',
+  model: 'openai/gpt-5.5',
+  instructions: 'You are a code review assistant.',
+  skills: [codeReview],
+})
+```
+
+The agent automatically gets `skill`, `skill_read`, and `skill_search` tools so it can discover and load skills during conversations.
+
+## Defining inline skills
+
+Use `createSkill()` to create skills entirely in code:
+
+```typescript
+import { createSkill } from '@mastra/core/skills'
+
+export const releaseChecklist = createSkill({
+  name: 'release-checklist',
+  description: 'Use when preparing a release.',
+  instructions: `
+    ## Release Checklist
+    1. Run the full test suite
+    2. Update CHANGELOG.md
+    3. Bump version numbers
+    4. Create a git tag
+  `,
+  references: {
+    'changelog-format.md': '# Changelog Format\nUse Keep a Changelog...',
+  },
+})
+```
+
+The `references` field bundles supporting documents that the agent can read with the `skill_read` tool, just like `references/` files in a filesystem skill.
+
+> **Note:** Visit [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill) for the full API.
+
+## Filesystem path skills
+
+Point to skill directories on disk without a workspace:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSkill } from '@mastra/core/skills'
+
+export const agent = new Agent({
+  id: 'my-agent',
+  model: 'openai/gpt-5.5',
+  skills: [
+    './skills/code-review', // path to a SKILL.md directory
+    './skills/testing', // another filesystem skill
+    createSkill({
+      /* ... */
+    }), // inline skill
+  ],
+})
+```
+
+Filesystem paths use `LocalSkillSource` under the hood, which reads `SKILL.md` files following the same format as [workspace skills](https://mastra.ai/docs/workspace/skills).
+
+## Dynamic skills
+
+For per-request skill resolution, pass a function:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSkill } from '@mastra/core/skills'
+
+const devSkill = createSkill({
+  name: 'dev-tools',
+  description: 'Developer productivity tools.',
+  instructions: '...',
+})
+
+const supportSkill = createSkill({
+  name: 'support-guide',
+  description: 'Customer support guidelines.',
+  instructions: '...',
+})
+
+export const agent = new Agent({
+  id: 'dynamic-agent',
+  model: 'openai/gpt-5.5',
+  skills: ({ requestContext }) => {
+    const role = requestContext.get('userRole')
+    if (role === 'developer') return [devSkill]
+    return [supportSkill]
+  },
+})
+```
+
+The resolver function receives `{ requestContext }` and returns a `SkillInput[]` array or a `Promise<SkillInput[]>`.
+
+## Merging with workspace skills
+
+When an agent has both `skills` and a workspace with skills configured, they merge. Agent-level skills take precedence on name conflicts:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+import { createSkill } from '@mastra/core/skills'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  skills: ['skills'], // provides "code-review" skill
+})
+
+const customReview = createSkill({
+  name: 'code-review', // same name as workspace skill
+  description: 'Custom review process.',
+  instructions: '...',
+})
+
+export const agent = new Agent({
+  id: 'reviewer',
+  model: 'openai/gpt-5.5',
+  workspace,
+  skills: [customReview], // agent-level "code-review" wins
+})
+```
+
+## Programmatic skill access
+
+Use `agent.getSkill()` and `agent.listSkills()` to access skills from application code (e.g., in workflows or API routes):
+
+```typescript
+import { reviewer } from '../mastra/agents'
+
+// Get a specific skill by name
+const skill = await reviewer.getSkill('code-review')
+if (skill) {
+  console.log(skill.instructions)
+}
+
+// List all available skills
+const allSkills = await reviewer.listSkills()
+for (const meta of allSkills) {
+  console.log(`${meta.name}: ${meta.description}`)
+}
+```
+
+> **Note:** Visit [`.getSkill()` reference](https://mastra.ai/reference/agents/getSkill) and [`.listSkills()` reference](https://mastra.ai/reference/agents/listSkills) for the full API.
+
+## Related
+
+- [Workspace skills](https://mastra.ai/docs/workspace/skills)
+- [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)
+- [`.getSkill()` reference](https://mastra.ai/reference/agents/getSkill)
+- [`.listSkills()` reference](https://mastra.ai/reference/agents/listSkills)
+- [Agent skills specification](https://agentskills.io)

package/.docs/docs/evals/datasets/running-experiments.md

@@ -127,6 +127,82 @@ for (const item of summary.results) {
 
 > **Info:** Visit the [Scorers overview](https://mastra.ai/docs/evals/overview) for details on available and custom scorers.
 
+## Tool mocks
+
+When an experiment runs an agent that calls side-effecting tools, you can make the run deterministic by attaching static tool mocks to individual dataset items. During the experiment, a mocked tool returns its declared output instead of executing. Tools that have no mock on the item run live.
+
+Mocks live on the dataset item, so they version with the row and travel with the test case. Each mock declares a tool name, the arguments it expects, and the output to return:
+
+```typescript
+await dataset.addItem({
+  input: 'What is the weather in Seattle?',
+  toolMocks: [
+    {
+      toolName: 'getWeather',
+      args: { city: 'Seattle' },
+      output: { temperature: 60, conditions: 'rainy' },
+    },
+  ],
+})
+```
+
+Tool mocks are supported for `agent` targets only.
+
+### Matching and consumption
+
+Arguments are matched strictly: object key order is ignored, array order is significant, and there is no type coercion. A mock is served only when the agent calls the tool with arguments that deep-equal the mock's `args`.
+
+When an item declares several mocks for the same tool and arguments, they are consumed in order — the first call gets the first mock, the next call gets the second, and so on. Ordering is tracked per `(toolName, args)` group and is independent across different arguments.
+
+### Matching mode
+
+By default each mock matches strictly on its `args`. Set `matchArgs: 'ignore'` to match on the tool name only — the mock's `args` are not compared and the next unconsumed mock for that tool is served regardless of how the agent called it:
+
+```typescript
+const subAgentMock = {
+  toolName: 'agent-balanceAgent',
+  args: { prompt: 'look up the balance for YJ' },
+  output: { text: "YJ's balance is $100." },
+  matchArgs: 'ignore',
+}
+```
+
+This is useful when a tool's arguments are noisy or generated by the model. The most common case is mocking a **sub-agent's response**: a delegated sub-agent is exposed to the parent as a tool named `agent-<name>`, and its arguments include an LLM-authored `prompt` plus runtime-injected fields. Mocking `agent-<name>` returns the canned response in place of running the sub-agent and its inner tools. When you create a mock from a trace, sub-agent delegation calls are derived with `matchArgs: 'ignore'` automatically; you can change it to `'strict'` to pin the exact arguments.
+
+### Failures
+
+A mocked tool call fails the item when the arguments do not match or all matching mocks have been consumed:
+
+- `TOOL_MOCK_MISMATCH` — the tool was called with arguments that no mock matches.
+- `TOOL_MOCK_EXHAUSTED` — every matching mock has already been consumed.
+
+When a mocked tool is mis-called, the agent run is aborted immediately, so the model cannot go on to call any further tools — including unmocked, side-effecting tools that would otherwise run live. These failures are deterministic, so they are not retried. Mocks that are declared but never used do not fail the item — they are reported as unconsumed.
+
+While an item has mocks, the agent's tools execute sequentially so repeated `(toolName, args)` mocks are consumed in the provider's call order. This serialization applies only to items that declare mocks.
+
+### Diagnostics
+
+Each item result carries a `toolMockReport` describing what the run did with the item's mocks:
+
+```typescript
+for (const item of summary.results) {
+  const report = item.toolMockReport
+  if (!report) continue
+
+  console.log(report.served) // mocks matched and returned
+  console.log(report.unconsumed) // mocks declared but never used
+  console.log(report.liveCalls) // unmocked tools that ran live
+  console.log(report.failure) // the mismatch/exhausted failure, if any
+}
+```
+
+In [Studio](https://mastra.ai/docs/studio/overview), edit a dataset item to author tool mocks as a JSON array, and open an experiment result to see the same report.
+
+### Limitations
+
+- **No tool span for mocked calls.** A mocked call returns its output before the tool executes, so it does not create a tool span. Trajectory scorers backed by stored traces may therefore not see mocked tool calls. Trajectory extraction that falls back to the agent's message output still sees them, so trajectory scoring can differ depending on your observability configuration.
+- **Storage support.** Tool mocks and tool mock reports are persisted by the LibSQL, PostgreSQL, MongoDB, and Spanner adapters. The MySQL adapter does not support them and rejects writes that carry tool mocks or a tool mock report so the feature never silently runs tools live.
+
 ## Async experiments
 
 `startExperiment()` blocks until every item completes. For long-running datasets, use [`startExperimentAsync()`](https://mastra.ai/reference/datasets/startExperimentAsync) to start the experiment in the background:

package/.docs/docs/workspace/skills.md

@@ -187,8 +187,16 @@ const workspace = new Workspace({
 
 When `skillSource` is provided, it's used instead of the workspace filesystem for skill discovery.
 
+## Agent-level skills
+
+You can also attach skills directly to an agent without a workspace using `createSkill()` and the agent's `skills` config. When both agent-level and workspace-level skills exist, they merge — agent-level skills take precedence on name conflicts.
+
+See [Agent skills](https://mastra.ai/docs/agents/skills) for details.
+
 ## Related
 
+- [Agent skills](https://mastra.ai/docs/agents/skills)
 - [Agent skills specification](https://agentskills.io)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)
-- [Search and indexing](https://mastra.ai/docs/workspace/search)
+- [Search and indexing](https://mastra.ai/docs/workspace/search)
+- [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)

package/.docs/models/gateways/openrouter.md

@@ -284,7 +284,6 @@ ANTHROPIC_API_KEY=ant-...
 | `poolside/laguna-m.1:free`                                      |
 | `poolside/laguna-xs.2`                                          |
 | `poolside/laguna-xs.2:free`                                     |
-| `prime-intellect/intellect-3`                                   |
 | `qwen/qwen-2.5-72b-instruct`                                    |
 | `qwen/qwen-2.5-7b-instruct`                                     |
 | `qwen/qwen-2.5-coder-32b-instruct`                              |
@@ -370,4 +369,5 @@ ANTHROPIC_API_KEY=ant-...
 | `z-ai/glm-5`                                                    |
 | `z-ai/glm-5-turbo`                                              |
 | `z-ai/glm-5.1`                                                  |
-| `z-ai/glm-5.2`                                                  |
+| `z-ai/glm-5.2`                                                  |
+| `z-ai/glm-5v-turbo`                                             |

package/.docs/models/gateways/vercel.md

@@ -1,6 +1,6 @@
 # ![Vercel logo](https://models.dev/logos/vercel.svg)Vercel
 
-Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 279 models through Mastra's model router.
+Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 288 models through Mastra's model router.
 
 Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
 
@@ -216,6 +216,8 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/gpt-4o`                          |
 | `openai/gpt-4o-mini`                     |
 | `openai/gpt-4o-mini-search-preview`      |
+| `openai/gpt-4o-mini-transcribe`          |
+| `openai/gpt-4o-transcribe`               |
 | `openai/gpt-5`                           |
 | `openai/gpt-5-chat`                      |
 | `openai/gpt-5-codex`                     |
@@ -246,6 +248,9 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/gpt-oss-120b`                    |
 | `openai/gpt-oss-20b`                     |
 | `openai/gpt-oss-safeguard-20b`           |
+| `openai/gpt-realtime-1.5`                |
+| `openai/gpt-realtime-2`                  |
+| `openai/gpt-realtime-mini`               |
 | `openai/o1`                              |
 | `openai/o3`                              |
 | `openai/o3-deep-research`                |
@@ -255,6 +260,9 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/text-embedding-3-large`          |
 | `openai/text-embedding-3-small`          |
 | `openai/text-embedding-ada-002`          |
+| `openai/tts-1`                           |
+| `openai/tts-1-hd`                        |
+| `openai/whisper-1`                       |
 | `perplexity/sonar`                       |
 | `perplexity/sonar-pro`                   |
 | `perplexity/sonar-reasoning-pro`         |
@@ -295,6 +303,7 @@ ANTHROPIC_API_KEY=ant-...
 | `xai/grok-imagine-image`                 |
 | `xai/grok-imagine-video`                 |
 | `xai/grok-imagine-video-1.5-preview`     |
+| `xai/grok-voice-think-fast-1.0`          |
 | `xiaomi/mimo-v2-flash`                   |
 | `xiaomi/mimo-v2-pro`                     |
 | `xiaomi/mimo-v2.5`                       |

package/.docs/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4563 models from 133 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4575 models from 133 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/baseten.md

@@ -44,7 +44,7 @@ for await (const chunk of stream) {
 | `baseten/zai-org/GLM-4.7`                          | 200K    |       |           |       |       |       | $0.60      | $2          |
 | `baseten/zai-org/GLM-5`                            | 203K    |       |           |       |       |       | $0.95      | $3          |
 | `baseten/zai-org/GLM-5.1`                          | 203K    |       |           |       |       |       | $1         | $4          |
-| `baseten/zai-org/GLM-5.2`                          | 131K    |       |           |       |       |       | $1         | $4          |
+| `baseten/zai-org/GLM-5.2`                          | 262K    |       |           |       |       |       | $1         | $4          |
 
 ## Advanced configuration
 

package/.docs/models/providers/friendli.md

@@ -1,6 +1,6 @@
 # ![Friendli logo](https://models.dev/logos/friendli.svg)Friendli
 
-Access 6 Friendli models through Mastra's model router. Authentication is handled automatically using the `FRIENDLI_TOKEN` environment variable.
+Access 7 Friendli models through Mastra's model router. Authentication is handled automatically using the `FRIENDLI_TOKEN` environment variable.
 
 Learn more in the [Friendli documentation](https://friendli.ai/docs/guides/serverless_endpoints/introduction).
 
@@ -40,6 +40,7 @@ for await (const chunk of stream) {
 | `friendli/Qwen/Qwen3-235B-A22B-Instruct-2507` | 262K    |       |           |       |       |       | $0.20      | $0.80       |
 | `friendli/zai-org/GLM-5`                      | 203K    |       |           |       |       |       | $1         | $3          |
 | `friendli/zai-org/GLM-5.1`                    | 203K    |       |           |       |       |       | $1         | $4          |
+| `friendli/zai-org/GLM-5.2`                    | 1.0M    |       |           |       |       |       | $1         | $4          |
 
 ## Advanced configuration
 
@@ -69,7 +70,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "friendli/zai-org/GLM-5.1"
+      ? "friendli/zai-org/GLM-5.2"
       : "friendli/MiniMaxAI/MiniMax-M2.5";
   }
 });

package/.docs/models/providers/lilac.md

@@ -32,12 +32,12 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model                          | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| ------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `lilac/google/gemma-4-31b-it`  | 262K    |       |           |       |       |       | $0.11      | $0.35       |
-| `lilac/minimaxai/minimax-m2.7` | 205K    |       |           |       |       |       | $0.30      | $1          |
-| `lilac/moonshotai/kimi-k2.6`   | 262K    |       |           |       |       |       | $0.70      | $4          |
-| `lilac/zai-org/glm-5.1`        | 203K    |       |           |       |       |       | $0.90      | $3          |
+| Model                         | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ----------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `lilac/google/gemma-4-31b-it` | 262K    |       |           |       |       |       | $0.11      | $0.35       |
+| `lilac/minimaxai/minimax-m3`  | 1.0M    |       |           |       |       |       | $0.28      | $1          |
+| `lilac/moonshotai/kimi-k2.6`  | 262K    |       |           |       |       |       | $0.70      | $4          |
+| `lilac/zai-org/glm-5.2`       | 524K    |       |           |       |       |       | $0.90      | $3          |
 
 ## Advanced configuration
 
@@ -67,7 +67,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "lilac/zai-org/glm-5.1"
+      ? "lilac/zai-org/glm-5.2"
       : "lilac/google/gemma-4-31b-it";
   }
 });

package/.docs/models/providers/siliconflow-cn.md

@@ -1,6 +1,6 @@
 # ![SiliconFlow (China) logo](https://models.dev/logos/siliconflow-cn.svg)SiliconFlow (China)
 
-Access 74 SiliconFlow (China) models through Mastra's model router. Authentication is handled automatically using the `SILICONFLOW_CN_API_KEY` environment variable.
+Access 75 SiliconFlow (China) models through Mastra's model router. Authentication is handled automatically using the `SILICONFLOW_CN_API_KEY` environment variable.
 
 Learn more in the [SiliconFlow (China) documentation](https://cloud.siliconflow.com/models).
 
@@ -43,6 +43,7 @@ for await (const chunk of stream) {
 | `siliconflow-cn/deepseek-ai/DeepSeek-V3`                  | 164K    |       |           |       |       |       | $0.25      | $1          |
 | `siliconflow-cn/deepseek-ai/DeepSeek-V3.1-Terminus`       | 164K    |       |           |       |       |       | $0.27      | $1          |
 | `siliconflow-cn/deepseek-ai/DeepSeek-V3.2`                | 164K    |       |           |       |       |       | $0.27      | $0.42       |
+| `siliconflow-cn/deepseek-ai/DeepSeek-V4-Flash`            | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
 | `siliconflow-cn/deepseek-ai/DeepSeek-V4-Pro`              | 1.0M    |       |           |       |       |       | $2         | $3          |
 | `siliconflow-cn/deepseek-ai/deepseek-vl2`                 | 4K      |       |           |       |       |       | $0.15      | $0.15       |
 | `siliconflow-cn/inclusionAI/Ling-flash-2.0`               | 131K    |       |           |       |       |       | $0.14      | $0.57       |

package/.docs/models/providers/wafer.ai.md

@@ -1,6 +1,6 @@
 # ![Wafer logo](https://models.dev/logos/wafer.ai.svg)Wafer
 
-Access 7 Wafer models through Mastra's model router. Authentication is handled automatically using the `WAFER_API_KEY` environment variable.
+Access 8 Wafer models through Mastra's model router. Authentication is handled automatically using the `WAFER_API_KEY` environment variable.
 
 Learn more in the [Wafer documentation](https://docs.wafer.ai/wafer-pass).
 
@@ -37,6 +37,7 @@ for await (const chunk of stream) {
 | `wafer.ai/deepseek-v4-flash` | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
 | `wafer.ai/deepseek-v4-pro`   | 1.0M    |       |           |       |       |       | $2         | $3          |
 | `wafer.ai/GLM-5.1`           | 203K    |       |           |       |       |       | $1         | $3          |
+| `wafer.ai/GLM-5.2`           | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `wafer.ai/Kimi-K2.6`         | 262K    |       |           |       |       |       | $0.68      | $3          |
 | `wafer.ai/Qwen3.5-397B-A17B` | 262K    |       |           |       |       |       | $0.43      | $3          |
 | `wafer.ai/Qwen3.6-35B-A3B`   | 256K    |       |           |       |       |       | $0.15      | $1          |

package/.docs/reference/agents/createSkill.md

@@ -0,0 +1,78 @@
+# `createSkill()`
+
+Creates an inline skill that can be passed directly to an agent's `skills` config without a filesystem or workspace.
+
+The returned object implements the `Skill` interface and works anywhere a filesystem-discovered skill works.
+
+## Usage example
+
+```typescript
+import { createSkill } from '@mastra/core/skills'
+
+const reviewSkill = createSkill({
+  name: 'code-review',
+  description: 'Use when reviewing code changes.',
+  instructions: `
+    When reviewing code:
+    1. Check for correctness
+    2. Check for style consistency
+    3. Look for potential bugs
+  `,
+  references: {
+    'checklist.md': '# Review Checklist\n- No unused imports\n- Error handling present',
+  },
+})
+```
+
+## Parameters
+
+**name** (`string`): Unique skill name. Used as the identifier when agents activate the skill. Must be a valid slug (lowercase, hyphens allowed).
+
+**description** (`string`): Short description shown to the agent in the system message. Helps the agent decide when to use the skill.
+
+**instructions** (`string`): The full skill instructions in markdown. Loaded into the conversation when the agent activates the skill.
+
+**references** (`Record<string, string>`): Supporting documents the agent can read with the \`skill\_read\` tool. Keys are filenames, values are file contents.
+
+**license** (`string`): SPDX license identifier for the skill.
+
+**compatibility** (`unknown`): Compatibility requirements. The Agent Skills spec leaves this flexible — can be a string array, object, or any structure your tooling expects.
+
+**user-invocable** (`boolean`): Whether end users can invoke this skill directly. Defaults to \`undefined\` (agent decides).
+
+**metadata** (`Record<string, unknown>`): Arbitrary metadata attached to the skill.
+
+## Return value
+
+Returns an `InlineSkill` object that implements the `Skill` interface:
+
+```typescript
+interface InlineSkill extends Skill {
+  __inline: true
+  __referenceContents: Record<string, string>
+}
+```
+
+The skill is assigned a synthetic path of `inline/<name>` (e.g., `inline/code-review`).
+
+## Validation
+
+`createSkill()` validates inputs using the same rules as filesystem skills:
+
+- `name` is required and must be a valid slug
+- `description` is required
+- `instructions` is required and non-empty
+
+If validation fails, an `Error` is thrown with details about the invalid fields.
+
+```typescript
+// Throws: Invalid skill "": name is required
+createSkill({ name: '', description: 'test', instructions: 'test' })
+```
+
+## Related
+
+- [Agent skills](https://mastra.ai/docs/agents/skills)
+- [Workspace skills](https://mastra.ai/docs/workspace/skills)
+- [`.getSkill()` reference](https://mastra.ai/reference/agents/getSkill)
+- [`.listSkills()` reference](https://mastra.ai/reference/agents/listSkills)

package/.docs/reference/agents/getSkill.md

@@ -0,0 +1,58 @@
+# `.getSkill()`
+
+Retrieves a specific skill by name from the agent's configured skills (both agent-level and workspace skills).
+
+## Usage example
+
+```typescript
+import { agent } from '../mastra/agents'
+
+const skill = await agent.getSkill('code-review')
+
+if (skill) {
+  console.log(skill.name) // "code-review"
+  console.log(skill.description) // "Use when reviewing code changes."
+  console.log(skill.instructions) // Full markdown instructions
+}
+```
+
+## Parameters
+
+**skillName** (`string`): The name of the skill to retrieve.
+
+**options** (`object`): Options for skill resolution.
+
+**options.requestContext** (`RequestContext`): Request context passed to dynamic skill resolvers.
+
+## Return value
+
+Returns `Promise<Skill | null>`.
+
+Returns the `Skill` object if found, or `null` if no skill with that name exists.
+
+```typescript
+interface Skill {
+  name: string
+  description: string
+  instructions: string
+  path: string
+  source: { type: string; projectPath: string }
+  references: string[]
+  scripts: string[]
+  assets: string[]
+  license?: string
+  compatibility?: string[]
+  'user-invocable'?: boolean
+  metadata?: Record<string, unknown>
+}
+```
+
+## Merging behavior
+
+When both agent-level skills and workspace skills are configured, `.getSkill()` searches the merged set. Agent-level skills take precedence on name conflicts.
+
+## Related
+
+- [Agent skills](https://mastra.ai/docs/agents/skills)
+- [`.listSkills()` reference](https://mastra.ai/reference/agents/listSkills)
+- [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)

package/.docs/reference/agents/listSkills.md

@@ -0,0 +1,53 @@
+# `.listSkills()`
+
+Returns metadata for all skills available to the agent, including both agent-level and workspace skills.
+
+## Usage example
+
+```typescript
+import { agent } from '../mastra/agents'
+
+const skills = await agent.listSkills()
+
+for (const skill of skills) {
+  console.log(`${skill.name}: ${skill.description}`)
+}
+```
+
+## Parameters
+
+**options** (`object`): Options for skill resolution.
+
+**options.requestContext** (`RequestContext`): Request context passed to dynamic skill resolvers.
+
+## Return value
+
+Returns `Promise<SkillMetadata[]>`.
+
+Each entry contains the metadata for a discovered skill:
+
+```typescript
+interface SkillMetadata {
+  name: string
+  description: string
+  path: string
+  source: { type: string; projectPath: string }
+  references: string[]
+  scripts: string[]
+  assets: string[]
+  license?: string
+  compatibility?: string[]
+  'user-invocable'?: boolean
+  metadata?: Record<string, unknown>
+}
+```
+
+## Merging behavior
+
+When both agent-level skills and workspace skills are configured, `.listSkills()` returns the merged set. Agent-level skills take precedence on name conflicts — if both define a skill named `code-review`, only the agent-level version appears in the result.
+
+## Related
+
+- [Agent skills](https://mastra.ai/docs/agents/skills)
+- [`.getSkill()` reference](https://mastra.ai/reference/agents/getSkill)
+- [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)

package/.docs/reference/index.md

@@ -7,6 +7,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Agent Class](https://mastra.ai/reference/agents/agent)
 - [Channels](https://mastra.ai/reference/agents/channels)
 - [createInngestAgent()](https://mastra.ai/reference/agents/inngest-agent)
+- [createSkill()](https://mastra.ai/reference/agents/createSkill)
 - [DurableAgent](https://mastra.ai/reference/agents/durable-agent)
 - [.generate()](https://mastra.ai/reference/agents/generate)
 - [.generateLegacy()](https://mastra.ai/reference/agents/generateLegacy)
@@ -19,10 +20,12 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.getMemory()](https://mastra.ai/reference/agents/getMemory)
 - [.getMetadata()](https://mastra.ai/reference/agents/getMetadata)
 - [.getModel()](https://mastra.ai/reference/agents/getModel)
+- [.getSkill()](https://mastra.ai/reference/agents/getSkill)
 - [.getTools()](https://mastra.ai/reference/agents/getTools)
 - [.getVoice()](https://mastra.ai/reference/agents/getVoice)
 - [.listAgents()](https://mastra.ai/reference/agents/listAgents)
 - [.listScorers()](https://mastra.ai/reference/agents/listScorers)
+- [.listSkills()](https://mastra.ai/reference/agents/listSkills)
 - [.listTools()](https://mastra.ai/reference/agents/listTools)
 - [.listWorkflows()](https://mastra.ai/reference/agents/listWorkflows)
 - [.network()](https://mastra.ai/reference/agents/network)

package/.docs/reference/processors/stream-error-retry-processor.md

@@ -30,6 +30,38 @@ The processor checks the error and its cause chain for:
 
 When the error is retryable, the processor returns `{ retry: true }`. It doesn't mutate messages.
 
+When `delayMs` is set, the processor waits before signaling a retry. This is useful for transient network errors like `ECONNRESET` where immediately retrying is likely to fail again. The delay can be a fixed number of milliseconds or a function evaluated with the error args (for example, to implement exponential backoff).
+
+## Delaying retries
+
+Use `delayMs` with a custom matcher to retry transient network resets with a wait:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { StreamErrorRetryProcessor } from '@mastra/core/processors'
+
+const isECONNRESET = (error: unknown) => {
+  if (!error || typeof error !== 'object') return false
+  const code = (error as { code?: unknown }).code
+  if (typeof code === 'string' && code.toUpperCase() === 'ECONNRESET') return true
+  const message = error instanceof Error ? error.message : undefined
+  return typeof message === 'string' && /econnreset|socket hang up/i.test(message)
+}
+
+export const agent = new Agent({
+  name: 'resilient-agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5',
+  errorProcessors: [
+    new StreamErrorRetryProcessor({
+      maxRetries: 2,
+      delayMs: ({ retryCount }) => Math.min(1000 * 2 ** retryCount, 30000),
+      matchers: [isECONNRESET],
+    }),
+  ],
+})
+```
+
 ## Default OpenAI Responses matcher
 
 `isRetryableOpenAIResponsesStreamError` matches OpenAI Responses stream error chunks with `type: 'error'` or `type: 'response.failed'`. It retries known transient OpenAI error codes and, as a fallback, errors with explicit retry guidance such as `You can retry your request`.

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.2.1-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`5c4e9a4`](https://github.com/mastra-ai/mastra/commit/5c4e9a4cfb2216bb3ea7f8988ad3727f3b92bb3a), [`25961e3`](https://github.com/mastra-ai/mastra/commit/25961e3260ff3b1464637af8fcdb36210551c39f), [`7b29f33`](https://github.com/mastra-ai/mastra/commit/7b29f332a357a83e555f29e718e5f2fab9979943), [`24912b1`](https://github.com/mastra-ai/mastra/commit/24912b1f855d29ec36af4ef4bde1f7417e20cdf5), [`7686216`](https://github.com/mastra-ai/mastra/commit/7686216f37e74568feddec17cef3c3d24e10e60a), [`975c59a`](https://github.com/mastra-ai/mastra/commit/975c59ae363ee275fc55062392e1ffd2cbccbd53), [`d95f394`](https://github.com/mastra-ai/mastra/commit/d95f394fd24c8411886930d727679c4d5252aa26), [`f3f0c9d`](https://github.com/mastra-ai/mastra/commit/f3f0c9d7c878db5a13177871ce3523a14f14b311)]:
+  - @mastra/core@1.46.0-alpha.4
+
 ## 1.2.1-alpha.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.1-alpha.4",
+  "version": "1.2.1-alpha.5",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
     "@mastra/mcp": "^1.12.0-alpha.0",
-    "@mastra/core": "1.46.0-alpha.3"
+    "@mastra/core": "1.46.0-alpha.4"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -45,9 +45,9 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.8",
-    "@internal/lint": "0.0.107",
     "@internal/types-builder": "0.0.82",
-    "@mastra/core": "1.46.0-alpha.3"
+    "@internal/lint": "0.0.107",
+    "@mastra/core": "1.46.0-alpha.4"
   },
   "homepage": "https://mastra.ai",
   "repository": {