Skip to content

Commit b8b4eb5

Browse files
amondnetamondnet
committed
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).
1 parent 5bde14b commit b8b4eb5

4 files changed

Lines changed: 553 additions & 0 deletions

File tree

‎plugins/mastra/.agents/skills/use-mastra/SKILL.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
name: use-mastra
3+
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".'
4+
---
5+
6+
## Prerequisites
7+
8+
Before writing Mastra code, verify the relevant package is installed in the current project:
9+
10+
```bash
11+
ls node_modules/mastra 2>/dev/null # CLI + project scaffolding + platform API
12+
ls node_modules/@mastra/ 2>/dev/null # scoped packages (core, memory, rag, ...)
13+
```
14+
15+
If the needed package is missing, install **only** what the task requires using the project's package manager (detect via lockfile):
16+
17+
```bash
18+
# root CLI / platform (only when invoking `mastra dev`, `mastra build`, etc.)
19+
pnpm add mastra # or: bun add mastra / npm i mastra / yarn add mastra
20+
21+
# scoped packages — add what you actually use
22+
pnpm add @mastra/core @mastra/memory @mastra/rag
23+
```
24+
25+
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`.
26+
27+
## Critical: Do Not Trust Internal Knowledge
28+
29+
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.
30+
31+
When working with Mastra:
32+
33+
1. Resolve the installed version first (`node_modules/<pkg>/package.json`).
34+
2. Read the SKILL.md shipped *inside that version* at `node_modules/<pkg>/dist/docs/SKILL.md` before coding.
35+
3. Verify every constructor, export, and option against `dist/docs/references/*.md` or `dist/docs/assets/SOURCE_MAP.json`.
36+
4. Run typecheck after every change — Mastra APIs are type-heavy and silent drift is rare.
37+
5. Never invent provider strings, plugin names, or adapter imports. Enumerate first.
38+
6. Surface deprecations to the user instead of silently picking one pattern.
39+
40+
If documentation cannot be found locally or remotely to back an answer, say so explicitly.
41+
42+
## Finding Documentation
43+
44+
### Bundled docs in `node_modules/`
45+
46+
Every Mastra package that ships documentation places it at `<pkg>/dist/docs/`:
47+
48+
```
49+
node_modules/<pkg>/dist/docs/
50+
├── SKILL.md # package overview + links
51+
├── assets/SOURCE_MAP.json # export → source file mapping
52+
└── references/ # one .md per topic or exported symbol
53+
├── docs-<topic>.md # concept guides
54+
└── reference-<symbol>.md # API reference
55+
```
56+
57+
Packages confirmed to ship `dist/docs/` (v1.6.2 / core 1.27.0 as of 2026-04):
58+
59+
| Package | What it covers |
60+
| --- | --- |
61+
| `mastra` | CLI commands (`mastra dev`, `mastra build`), platform REST API |
62+
| `@mastra/core` | `Mastra`, `Agent`, `createTool`, `createWorkflow`, `createStep`, processors, guardrails, browser/editor |
63+
| `@mastra/memory` | `Memory`, threads, working memory, semantic recall, storage |
64+
| `@mastra/rag` | `MDocument`, chunking, embeddings, retrieval, GraphRAG, rerankers |
65+
| `@mastra/evals` | Scorers, datasets, experiments, CI harness |
66+
| `@mastra/deployer`, `@mastra/server` | Build / deploy / serve Mastra projects |
67+
| `@mastra/pg`, `@mastra/libsql`, `@mastra/mcp` | Storage adapters, MCP server integration |
68+
69+
See [`references/packages.md`](references/packages.md) for purpose + SKILL path per package, plus which packages currently lack bundled docs (remote-only).
70+
71+
### Canonical lookup flow
72+
73+
```bash
74+
# 1. Start from the overview shipped with the installed version
75+
cat node_modules/@mastra/core/dist/docs/SKILL.md
76+
77+
# 2. Grep references/ for the topic or symbol
78+
grep -rli "Agent" node_modules/@mastra/core/dist/docs/references/
79+
grep -rli "createWorkflow" node_modules/@mastra/core/dist/docs/references/
80+
81+
# 3. Resolve an exported symbol back to its type definition
82+
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | jq '."Agent"'
83+
cat node_modules/@mastra/core/dist/<path-from-source-map>
84+
```
85+
86+
### Remote fallbacks
87+
88+
If the package is not installed, or a doc is missing from `dist/docs/`:
89+
90+
1. `https://mastra.ai/llms.txt` — index of current docs (fetch and grep).
91+
2. `https://mastra.ai/docs/` — full documentation site.
92+
3. The `@mastra/mcp-docs-server` MCP server (configured by this plugin in `plugin.json`) — returns the same docs over MCP tool calls.
93+
94+
Remote docs track `main` and may be ahead of the installed version; always prefer bundled docs when both are available.
95+
96+
## Mastra Package Map
97+
98+
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).
99+
100+
| Need | Package | Typical import |
101+
| --- | --- | --- |
102+
| `Mastra`, `Agent`, `createTool`, `createWorkflow`, `createStep` | `@mastra/core` | `@mastra/core`, `@mastra/core/agent`, `@mastra/core/workflows`, `@mastra/core/tools` |
103+
| Threads, working memory, semantic recall | `@mastra/memory` | `@mastra/memory` |
104+
| RAG pipeline — chunk, embed, retrieve, rerank | `@mastra/rag` | `@mastra/rag` |
105+
| Scorers, datasets, experiments | `@mastra/evals` | `@mastra/evals` |
106+
| Postgres / LibSQL storage + vectors | `@mastra/pg`, `@mastra/libsql` | `@mastra/pg`, `@mastra/libsql` |
107+
| MCP server integration | `@mastra/mcp` | `@mastra/mcp` |
108+
| CLI + Studio + platform API | `mastra` | `mastra` (dev dependency for CLI; runtime for platform clients) |
109+
| Build & deploy | `@mastra/deployer`, `@mastra/server` | usually only invoked via CLI |
110+
111+
## Building Agents & Workflows
112+
113+
Concise recipes — each one ends with "verify against `dist/docs/` before shipping": [`references/agents-and-workflows.md`](references/agents-and-workflows.md).
114+
115+
Rules of thumb:
116+
117+
- **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.
118+
- **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.
119+
- **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.
120+
- **`.commit()`** is required on workflows. Forgetting it is the #1 cause of `Cannot read property 'then' of undefined`.
121+
- **`threadId` + `resourceId`** must be stable across turns for memory to persist.
122+
- **Typecheck** after every change: `pnpm tsc --noEmit` (or `bun tsc --noEmit`, `npm run typecheck`).
123+
124+
## When Typecheck or Runtime Fails
125+
126+
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.
127+
128+
If the symptom is not listed:
129+
130+
```bash
131+
# resolve the error string inside installed source
132+
rg -n "error string fragment" node_modules/@mastra/core/dist
133+
rg -n "error string fragment" node_modules/@mastra/<subpkg>/dist
134+
```
135+
136+
## Relationship to the `mastra` skill
137+
138+
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.
139+
140+
`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.
141+
142+
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.
143+
144+
## References
145+
146+
- [`references/packages.md`](references/packages.md) — every Mastra package, its purpose, and the exact `dist/docs/` path to read
147+
- [`references/agents-and-workflows.md`](references/agents-and-workflows.md) — canonical recipes: agent with tools + memory, workflow with steps, Mastra-instance registration
148+
- [`references/common-errors.md`](references/common-errors.md) — symptom → cause → fix for the most frequent Mastra failures

‎plugins/mastra/.agents/skills/use-mastra/references/agents-and-workflows.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Agents & Workflows Recipes
2+
3+
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.
4+
5+
Assumes `@mastra/core` is installed. If not, install it first (see [`../SKILL.md`](../SKILL.md) § Prerequisites).
6+
7+
## Recipe 1 — Agent with tools + memory
8+
9+
```ts
10+
import { Mastra } from "@mastra/core";
11+
import { Agent } from "@mastra/core/agent";
12+
import { createTool } from "@mastra/core/tools";
13+
import { Memory } from "@mastra/memory";
14+
import { PostgresStore } from "@mastra/pg";
15+
import { z } from "zod";
16+
17+
// 1. Tools — `inputSchema` / `outputSchema` are Zod; never call them `parameters`.
18+
const weatherTool = createTool({
19+
id: "get-weather",
20+
description: "Look up current weather by city name.",
21+
inputSchema: z.object({ city: z.string() }),
22+
outputSchema: z.object({ temperatureC: z.number(), condition: z.string() }),
23+
execute: async ({ context }) => {
24+
// fetch from your upstream service
25+
return { temperatureC: 21, condition: "clear" };
26+
},
27+
});
28+
29+
// 2. Memory — storage is REQUIRED; so is an embedder + vector if you turn on semantic recall.
30+
const storage = new PostgresStore({ connectionString: process.env.DATABASE_URL! });
31+
const memory = new Memory({
32+
id: "chat-memory",
33+
storage,
34+
options: { lastMessages: 10 }, // set semanticRecall/vector/embedder together or not at all
35+
});
36+
37+
// 3. Agent — bind the tool by the exact key used in Mastra.tools below.
38+
export const supportAgent = new Agent({
39+
id: "support-agent",
40+
name: "Support agent",
41+
instructions: "Answer questions about weather and escalate anything else.",
42+
model: "openai/gpt-5.4", // always "provider/model" — never a bare ID
43+
tools: { weatherTool },
44+
memory,
45+
});
46+
47+
// 4. Mastra instance — registering tools here is the step most often skipped.
48+
export const mastra = new Mastra({
49+
agents: { supportAgent },
50+
tools: { weatherTool },
51+
storage,
52+
});
53+
54+
// 5. Invocation — threadId + resourceId must be stable across turns for memory to persist.
55+
await supportAgent.generate("What's the weather in Berlin?", {
56+
threadId: "user-42::support",
57+
resourceId: "user-42",
58+
});
59+
```
60+
61+
Verify against installed version before shipping:
62+
63+
```bash
64+
cat node_modules/@mastra/core/dist/docs/references/docs-agents-overview.md
65+
cat node_modules/@mastra/core/dist/docs/references/docs-agents-using-tools.md
66+
cat node_modules/@mastra/memory/dist/docs/references/docs-memory-overview.md
67+
```
68+
69+
## Recipe 2 — Workflow with steps
70+
71+
```ts
72+
import { Mastra } from "@mastra/core";
73+
import { createWorkflow, createStep } from "@mastra/core/workflows";
74+
import { z } from "zod";
75+
76+
const fetchUser = createStep({
77+
id: "fetchUser",
78+
inputSchema: z.object({ userId: z.string() }),
79+
outputSchema: z.object({ userId: z.string(), email: z.string() }),
80+
execute: async ({ inputData }) => {
81+
// call your DB / API
82+
return { userId: inputData.userId, email: "user@example.com" };
83+
},
84+
});
85+
86+
const sendEmail = createStep({
87+
id: "sendEmail",
88+
inputSchema: z.object({ userId: z.string(), email: z.string() }),
89+
outputSchema: z.object({ messageId: z.string() }),
90+
execute: async ({ inputData }) => {
91+
return { messageId: `msg_${inputData.userId}` };
92+
},
93+
});
94+
95+
const notifyUserWorkflow = createWorkflow({
96+
id: "notify-user",
97+
inputSchema: z.object({ userId: z.string() }),
98+
outputSchema: z.object({ messageId: z.string() }),
99+
})
100+
.then(fetchUser)
101+
.then(sendEmail)
102+
.commit(); // REQUIRED — forgetting this yields "Cannot read property 'then' of undefined" at run time.
103+
104+
export const mastra = new Mastra({
105+
workflows: { notifyUserWorkflow },
106+
});
107+
108+
// Invocation
109+
const run = await notifyUserWorkflow.createRun();
110+
const result = await run.start({ inputData: { userId: "u_123" } });
111+
```
112+
113+
Verify against installed version before shipping:
114+
115+
```bash
116+
ls node_modules/@mastra/core/dist/docs/references/ | grep -i workflow
117+
cat node_modules/@mastra/core/dist/docs/references/reference-core-createWorkflow.md 2>/dev/null
118+
cat node_modules/@mastra/core/dist/docs/references/reference-core-createStep.md 2>/dev/null
119+
```
120+
121+
(The exact filenames differ per version — list the directory and pick the matching reference file.)
122+
123+
## Recipe 3 — RAG pipeline
124+
125+
```ts
126+
import { Mastra } from "@mastra/core";
127+
import { MDocument } from "@mastra/rag";
128+
129+
const doc = MDocument.fromText(sourceText);
130+
const chunks = await doc.chunk({ strategy: "recursive", size: 512, overlap: 50 });
131+
132+
// Use your vector store's `upsert` + your embedder to persist the chunks; then wire a
133+
// vector-query tool into an agent via `createTool` from @mastra/rag.
134+
```
135+
136+
Verify against installed version before shipping:
137+
138+
```bash
139+
cat node_modules/@mastra/rag/dist/docs/SKILL.md
140+
cat node_modules/@mastra/rag/dist/docs/references/docs-rag-chunking-and-embedding.md
141+
cat node_modules/@mastra/rag/dist/docs/references/reference-tools-vector-query-tool.md
142+
```
143+
144+
## General verification commands
145+
146+
```bash
147+
# Typecheck — Mastra APIs are type-heavy; silent drift is rare.
148+
pnpm tsc --noEmit # or: bun tsc --noEmit / npm run typecheck
149+
150+
# Interactive check — launch Studio, exercise the agent/workflow end-to-end.
151+
pnpm mastra dev # open http://localhost:4111
152+
```
153+
154+
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.

0 commit comments

Comments
 (0)