feat(mastra): add use-mastra workflow skill (#161)

amondnet · web-flow · commit dd0ad46ae87c · 2026-04-23T23:35:40.000+09:00
* feat(mastra): add use-mastra workflow skill Add a hand-written `use-mastra` skill under `plugins/mastra/.agents/skills/use-mastra/` that mirrors Vercel's `use-ai-sdk` workflow skill in structure and intent. Teaches coding agents to install the relevant `mastra` / `@mastra/*` package and read the docs shipped at `node_modules/<pkg>/dist/docs/SKILL.md` (and `references/*.md`) instead of relying on stale training-data APIs. Confirmed via `npm pack` that these packages ship `dist/docs/`: mastra, @mastra/core, @mastra/memory, @mastra/rag, @mastra/evals, @mastra/deployer, @mastra/server, @mastra/pg, @mastra/libsql, @mastra/mcp. Only @mastra/observability is remote-only. Keeps the existing `mastra` primer skill (v2.0.0, installed via skills.sh from `mastra-ai/skills`) untouched; `use-mastra` is the task-triggered workflow complement. Bumps plugins/mastra from 1.2.0 to 1.3.0 and logs the change in CHANGELOG.md (matching PR #159's format). * chore(mastra): apply AI code review suggestions - Update agent.generate() calls to nested memory: { thread, resource } API instead of the deprecated top-level threadId/resourceId fields (agents-and-workflows.md and common-errors.md). - Use createVectorQueryTool from @mastra/rag instead of createTool for the vector-query recipe in agents-and-workflows.md. Addresses cubic-dev-ai P1 + P2 suggestions on PR #161. * chore: update agent memory for cubic review PR #161
diff --git a/.claude/agent-memory/review-review-cubic-reviewer/MEMORY.md b/.claude/agent-memory/review-review-cubic-reviewer/MEMORY.md
@@ -0,0 +1,3 @@
+# Agent Memory — review-review-cubic-reviewer
+
+- [Mastra skill review (PR #161)](pr161-mastra-skill.md) — cubic found no issues after correctness fixes were applied
diff --git a/.claude/agent-memory/review-review-cubic-reviewer/pr161-mastra-skill.md b/.claude/agent-memory/review-review-cubic-reviewer/pr161-mastra-skill.md
@@ -0,0 +1,17 @@
+---
+name: Mastra skill review (PR #161)
+description: cubic review result for PR #161 adding use-mastra workflow skill; clean after two prior correctness fixes
+type: project
+---
+
+PR #161 (branch: amondnet/use-mastra-skill) adds `plugins/mastra/.agents/skills/use-mastra/` with SKILL.md, packages.md, agents-and-workflows.md, and common-errors.md.
+
+Two fixes were applied before this cubic run:
+1. `agent.generate(...)` updated to nested `memory: { thread, resource }` (deprecated top-level `threadId`/`resourceId` removed) in agents-and-workflows.md and common-errors.md.
+2. `createTool` → `createVectorQueryTool` for the RAG vector-query recipe in agents-and-workflows.md.
+
+**Why:** Mastra API changed — top-level threadId/resourceId are deprecated; correct vector query tool name is createVectorQueryTool.
+
+cubic result: 0 issues (clean pass). Review state saved at commit b8b4eb5.
+
+**How to apply:** When reviewing Mastra skill files, watch for deprecated memory API patterns and incorrect tool names as common false-positive-free issues cubic catches.
diff --git a/plugins/mastra/.agents/skills/use-mastra/SKILL.md b/plugins/mastra/.agents/skills/use-mastra/SKILL.md
@@ -0,0 +1,148 @@
+---
+name: use-mastra
+description: 'Answer questions about the Mastra AI framework and help build agents, workflows, tools, memory, and RAG features. Use when developers: (1) ask about Mastra APIs like `Mastra`, `Agent`, `createWorkflow`, `createTool`, `createStep`, `Memory`, or run the `mastra` CLI; (2) wire up agents, workflows, or step-based orchestration; (3) integrate `@mastra/*` packages (`@mastra/core`, `@mastra/memory`, `@mastra/rag`, `@mastra/evals`, `@mastra/deployer`, `@mastra/server`, `@mastra/pg`, `@mastra/libsql`, `@mastra/mcp`); (4) debug TypeScript errors from Mastra APIs or model-router strings. Triggers on: "Mastra", "@mastra/core", "mastra agent", "mastra workflow", "createWorkflow", "createTool", "createStep", "mastra memory", "semantic recall", "mastra rag", "mastra deployer", "mastra evals", "mastra studio", "provider/model".'
+---
+
+## Prerequisites
+
+Before writing Mastra code, verify the relevant package is installed in the current project:
+
+```bash
+ls node_modules/mastra 2>/dev/null          # CLI + project scaffolding + platform API
+ls node_modules/@mastra/ 2>/dev/null        # scoped packages (core, memory, rag, ...)
+```
+
+If the needed package is missing, install **only** what the task requires using the project's package manager (detect via lockfile):
+
+```bash
+# root CLI / platform (only when invoking `mastra dev`, `mastra build`, etc.)
+pnpm add mastra        # or: bun add mastra / npm i mastra / yarn add mastra
+
+# scoped packages — add what you actually use
+pnpm add @mastra/core @mastra/memory @mastra/rag
+```
+
+Do not install packages you do not yet need. Mastra is opinionated about module format — confirm TypeScript target before writing: `target: ES2022`, `module: ES2022`, `moduleResolution: bundler`.
+
+## Critical: Do Not Trust Internal Knowledge
+
+Mastra evolves rapidly. Constructor signatures, exported symbol names, workflow step APIs, memory option shapes, and model-router providers shift between minor versions. Training-data recollection of Mastra APIs is likely wrong.
+
+When working with Mastra:
+
+1. Resolve the installed version first (`node_modules/<pkg>/package.json`).
+2. Read the SKILL.md shipped *inside that version* at `node_modules/<pkg>/dist/docs/SKILL.md` before coding.
+3. Verify every constructor, export, and option against `dist/docs/references/*.md` or `dist/docs/assets/SOURCE_MAP.json`.
+4. Run typecheck after every change — Mastra APIs are type-heavy and silent drift is rare.
+5. Never invent provider strings, plugin names, or adapter imports. Enumerate first.
+6. Surface deprecations to the user instead of silently picking one pattern.
+
+If documentation cannot be found locally or remotely to back an answer, say so explicitly.
+
+## Finding Documentation
+
+### Bundled docs in `node_modules/`
+
+Every Mastra package that ships documentation places it at `<pkg>/dist/docs/`:
+
+```
+node_modules/<pkg>/dist/docs/
+├── SKILL.md                       # package overview + links
+├── assets/SOURCE_MAP.json         # export → source file mapping
+└── references/                    # one .md per topic or exported symbol
+    ├── docs-<topic>.md            # concept guides
+    └── reference-<symbol>.md      # API reference
+```
+
+Packages confirmed to ship `dist/docs/` (v1.6.2 / core 1.27.0 as of 2026-04):
+
+| Package | What it covers |
+| --- | --- |
+| `mastra` | CLI commands (`mastra dev`, `mastra build`), platform REST API |
+| `@mastra/core` | `Mastra`, `Agent`, `createTool`, `createWorkflow`, `createStep`, processors, guardrails, browser/editor |
+| `@mastra/memory` | `Memory`, threads, working memory, semantic recall, storage |
+| `@mastra/rag` | `MDocument`, chunking, embeddings, retrieval, GraphRAG, rerankers |
+| `@mastra/evals` | Scorers, datasets, experiments, CI harness |
+| `@mastra/deployer`, `@mastra/server` | Build / deploy / serve Mastra projects |
+| `@mastra/pg`, `@mastra/libsql`, `@mastra/mcp` | Storage adapters, MCP server integration |
+
+See [`references/packages.md`](references/packages.md) for purpose + SKILL path per package, plus which packages currently lack bundled docs (remote-only).
+
+### Canonical lookup flow
+
+```bash
+# 1. Start from the overview shipped with the installed version
+cat node_modules/@mastra/core/dist/docs/SKILL.md
+
+# 2. Grep references/ for the topic or symbol
+grep -rli "Agent" node_modules/@mastra/core/dist/docs/references/
+grep -rli "createWorkflow" node_modules/@mastra/core/dist/docs/references/
+
+# 3. Resolve an exported symbol back to its type definition
+cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | jq '."Agent"'
+cat node_modules/@mastra/core/dist/<path-from-source-map>
+```
+
+### Remote fallbacks
+
+If the package is not installed, or a doc is missing from `dist/docs/`:
+
+1. `https://mastra.ai/llms.txt` — index of current docs (fetch and grep).
+2. `https://mastra.ai/docs/` — full documentation site.
+3. The `@mastra/mcp-docs-server` MCP server (configured by this plugin in `plugin.json`) — returns the same docs over MCP tool calls.
+
+Remote docs track `main` and may be ahead of the installed version; always prefer bundled docs when both are available.
+
+## Mastra Package Map
+
+Concise map of what each package exports and where its docs live. Full table with docs paths and verification notes: [`references/packages.md`](references/packages.md).
+
+| Need | Package | Typical import |
+| --- | --- | --- |
+| `Mastra`, `Agent`, `createTool`, `createWorkflow`, `createStep` | `@mastra/core` | `@mastra/core`, `@mastra/core/agent`, `@mastra/core/workflows`, `@mastra/core/tools` |
+| Threads, working memory, semantic recall | `@mastra/memory` | `@mastra/memory` |
+| RAG pipeline — chunk, embed, retrieve, rerank | `@mastra/rag` | `@mastra/rag` |
+| Scorers, datasets, experiments | `@mastra/evals` | `@mastra/evals` |
+| Postgres / LibSQL storage + vectors | `@mastra/pg`, `@mastra/libsql` | `@mastra/pg`, `@mastra/libsql` |
+| MCP server integration | `@mastra/mcp` | `@mastra/mcp` |
+| CLI + Studio + platform API | `mastra` | `mastra` (dev dependency for CLI; runtime for platform clients) |
+| Build & deploy | `@mastra/deployer`, `@mastra/server` | usually only invoked via CLI |
+
+## Building Agents & Workflows
+
+Concise recipes — each one ends with "verify against `dist/docs/` before shipping": [`references/agents-and-workflows.md`](references/agents-and-workflows.md).
+
+Rules of thumb:
+
+- **Agent vs Workflow.** Use `Agent` for open-ended tasks (research, chat, triage). Use `createWorkflow` + `createStep` for deterministic pipelines with a fixed shape and explicit state.
+- **Register everything on `Mastra`.** Tools, agents, workflows, storage, and logger all hang off a single `Mastra` instance. Passing tools to an agent without also registering them on `Mastra` is a common bug.
+- **Model strings.** Always `provider/model` (e.g. `openai/gpt-5.4`, `anthropic/claude-sonnet-4-5`). Never bare model IDs. The provider-registry script shipped with the existing `mastra` skill (`plugins/mastra/.agents/skills/mastra/scripts/provider-registry.mjs`) enumerates valid provider keys and current model names — run it before generating code that references a model.
+- **`.commit()`** is required on workflows. Forgetting it is the #1 cause of `Cannot read property 'then' of undefined`.
+- **`threadId` + `resourceId`** must be stable across turns for memory to persist.
+- **Typecheck** after every change: `pnpm tsc --noEmit` (or `bun tsc --noEmit`, `npm run typecheck`).
+
+## When Typecheck or Runtime Fails
+
+Before searching source code, grep [`references/common-errors.md`](references/common-errors.md) for the failing symptom. It indexes the most frequent Mastra failure modes (ESM/CJS mismatch, tools registered but not called, memory without storage, semantic recall without a vector store, workflow missing `.commit()`, invalid model string, wrong `threadId`) against the canonical fix.
+
+If the symptom is not listed:
+
+```bash
+# resolve the error string inside installed source
+rg -n "error string fragment" node_modules/@mastra/core/dist
+rg -n "error string fragment" node_modules/@mastra/<subpkg>/dist
+```
+
+## Relationship to the `mastra` skill
+
+This plugin ships a separate, richer primer at `plugins/mastra/.agents/skills/mastra/SKILL.md` (v2.0.0, sourced from `mastra-ai/skills`). That skill is a **framework primer** — concepts, doc-lookup strategy, upgrade guides, migration notes, extensive common-errors coverage.
+
+`use-mastra` is the **task-triggered workflow skill** — concise, trigger-heavy, focused on redirecting agents to version-accurate `dist/docs/` and stopping training-data hallucinations. The two are complementary; Claude Code will auto-activate whichever matches the task framing.
+
+When in doubt, read the primer first (`plugins/mastra/.agents/skills/mastra/SKILL.md`) and use this skill's references for quick per-package lookup paths and concise recipes.
+
+## References
+
+- [`references/packages.md`](references/packages.md) — every Mastra package, its purpose, and the exact `dist/docs/` path to read
+- [`references/agents-and-workflows.md`](references/agents-and-workflows.md) — canonical recipes: agent with tools + memory, workflow with steps, Mastra-instance registration
+- [`references/common-errors.md`](references/common-errors.md) — symptom → cause → fix for the most frequent Mastra failures
diff --git a/plugins/mastra/.agents/skills/use-mastra/references/agents-and-workflows.md b/plugins/mastra/.agents/skills/use-mastra/references/agents-and-workflows.md
@@ -0,0 +1,156 @@
+# Agents & Workflows Recipes
+
+Concise, correctness-oriented recipes for the three most common Mastra building tasks. Each recipe ends with the lookup command to run against `dist/docs/` before shipping the code.
+
+Assumes `@mastra/core` is installed. If not, install it first (see [`../SKILL.md`](../SKILL.md) § Prerequisites).
+
+## Recipe 1 — Agent with tools + memory
+
+```ts
+import { Mastra } from "@mastra/core";
+import { Agent } from "@mastra/core/agent";
+import { createTool } from "@mastra/core/tools";
+import { Memory } from "@mastra/memory";
+import { PostgresStore } from "@mastra/pg";
+import { z } from "zod";
+
+// 1. Tools — `inputSchema` / `outputSchema` are Zod; never call them `parameters`.
+const weatherTool = createTool({
+  id: "get-weather",
+  description: "Look up current weather by city name.",
+  inputSchema: z.object({ city: z.string() }),
+  outputSchema: z.object({ temperatureC: z.number(), condition: z.string() }),
+  execute: async ({ context }) => {
+    // fetch from your upstream service
+    return { temperatureC: 21, condition: "clear" };
+  },
+});
+
+// 2. Memory — storage is REQUIRED; so is an embedder + vector if you turn on semantic recall.
+const storage = new PostgresStore({ connectionString: process.env.DATABASE_URL! });
+const memory = new Memory({
+  id: "chat-memory",
+  storage,
+  options: { lastMessages: 10 }, // set semanticRecall/vector/embedder together or not at all
+});
+
+// 3. Agent — bind the tool by the exact key used in Mastra.tools below.
+export const supportAgent = new Agent({
+  id: "support-agent",
+  name: "Support agent",
+  instructions: "Answer questions about weather and escalate anything else.",
+  model: "openai/gpt-5.4", // always "provider/model" — never a bare ID
+  tools: { weatherTool },
+  memory,
+});
+
+// 4. Mastra instance — registering tools here is the step most often skipped.
+export const mastra = new Mastra({
+  agents: { supportAgent },
+  tools: { weatherTool },
+  storage,
+});
+
+// 5. Invocation — thread + resource IDs must be stable across turns for memory to persist.
+await supportAgent.generate("What's the weather in Berlin?", {
+  memory: {
+    thread: "user-42::support",
+    resource: "user-42",
+  },
+});
+```
+
+Verify against installed version before shipping:
+
+```bash
+cat node_modules/@mastra/core/dist/docs/references/docs-agents-overview.md
+cat node_modules/@mastra/core/dist/docs/references/docs-agents-using-tools.md
+cat node_modules/@mastra/memory/dist/docs/references/docs-memory-overview.md
+```
+
+## Recipe 2 — Workflow with steps
+
+```ts
+import { Mastra } from "@mastra/core";
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const fetchUser = createStep({
+  id: "fetchUser",
+  inputSchema: z.object({ userId: z.string() }),
+  outputSchema: z.object({ userId: z.string(), email: z.string() }),
+  execute: async ({ inputData }) => {
+    // call your DB / API
+    return { userId: inputData.userId, email: "user@example.com" };
+  },
+});
+
+const sendEmail = createStep({
+  id: "sendEmail",
+  inputSchema: z.object({ userId: z.string(), email: z.string() }),
+  outputSchema: z.object({ messageId: z.string() }),
+  execute: async ({ inputData }) => {
+    return { messageId: `msg_${inputData.userId}` };
+  },
+});
+
+const notifyUserWorkflow = createWorkflow({
+  id: "notify-user",
+  inputSchema: z.object({ userId: z.string() }),
+  outputSchema: z.object({ messageId: z.string() }),
+})
+  .then(fetchUser)
+  .then(sendEmail)
+  .commit(); // REQUIRED — forgetting this yields "Cannot read property 'then' of undefined" at run time.
+
+export const mastra = new Mastra({
+  workflows: { notifyUserWorkflow },
+});
+
+// Invocation
+const run = await notifyUserWorkflow.createRun();
+const result = await run.start({ inputData: { userId: "u_123" } });
+```
+
+Verify against installed version before shipping:
+
+```bash
+ls node_modules/@mastra/core/dist/docs/references/ | grep -i workflow
+cat node_modules/@mastra/core/dist/docs/references/reference-core-createWorkflow.md 2>/dev/null
+cat node_modules/@mastra/core/dist/docs/references/reference-core-createStep.md 2>/dev/null
+```
+
+(The exact filenames differ per version — list the directory and pick the matching reference file.)
+
+## Recipe 3 — RAG pipeline
+
+```ts
+import { Mastra } from "@mastra/core";
+import { MDocument } from "@mastra/rag";
+
+const doc = MDocument.fromText(sourceText);
+const chunks = await doc.chunk({ strategy: "recursive", size: 512, overlap: 50 });
+
+// Use your vector store's `upsert` + your embedder to persist the chunks; then wire a
+// vector-query tool into an agent via `createVectorQueryTool` from @mastra/rag.
+```
+
+Verify against installed version before shipping:
+
+```bash
+cat node_modules/@mastra/rag/dist/docs/SKILL.md
+cat node_modules/@mastra/rag/dist/docs/references/docs-rag-chunking-and-embedding.md
+cat node_modules/@mastra/rag/dist/docs/references/reference-tools-vector-query-tool.md
+```
+
+## General verification commands
+
+```bash
+# Typecheck — Mastra APIs are type-heavy; silent drift is rare.
+pnpm tsc --noEmit   # or: bun tsc --noEmit / npm run typecheck
+
+# Interactive check — launch Studio, exercise the agent/workflow end-to-end.
+pnpm mastra dev     # open http://localhost:4111
+```
+
+Do not ship code whose APIs you have not cross-checked against `node_modules/<pkg>/dist/docs/`. If a symbol, option, or import path differs between this recipe and the bundled docs, trust the bundled docs — they match the installed version.
diff --git a/plugins/mastra/.agents/skills/use-mastra/references/common-errors.md b/plugins/mastra/.agents/skills/use-mastra/references/common-errors.md
diff --git a/plugins/mastra/.agents/skills/use-mastra/references/packages.md b/plugins/mastra/.agents/skills/use-mastra/references/packages.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Agent Memory — review-review-cubic-reviewer`
	`2`	`+`
	`3`	`+- [Mastra skill review (PR #161)](pr161-mastra-skill.md) — cubic found no issues after correctness fixes were applied`