diff --git a/.claude/agent-memory/review-review-cubic-reviewer/MEMORY.md b/.claude/agent-memory/review-review-cubic-reviewer/MEMORY.md new file mode 100644 index 00000000..5c6f064f --- /dev/null +++ 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 new file mode 100644 index 00000000..b351491c --- /dev/null +++ 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 new file mode 100644 index 00000000..71f2773f --- /dev/null +++ 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//package.json`). +2. Read the SKILL.md shipped *inside that version* at `node_modules//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 `/dist/docs/`: + +``` +node_modules//dist/docs/ +├── SKILL.md # package overview + links +├── assets/SOURCE_MAP.json # export → source file mapping +└── references/ # one .md per topic or exported symbol + ├── docs-.md # concept guides + └── reference-.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/ +``` + +### 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//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 new file mode 100644 index 00000000..69f4e288 --- /dev/null +++ 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//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 new file mode 100644 index 00000000..76bbd692 --- /dev/null +++ b/plugins/mastra/.agents/skills/use-mastra/references/common-errors.md @@ -0,0 +1,199 @@ +# Common Errors + +Symptom → cause → fix for the most frequent Mastra failure modes. Grep this file by error-message fragment before searching source. + +For longer narrative coverage, see the sibling skill's reference at `../../mastra/references/common-errors.md`. + +## `Cannot find module '@mastra/core'` / `Cannot use import statement outside a module` + +**Cause.** Mastra requires native ES modules. CommonJS `tsconfig.json` or a missing `"type": "module"` in `package.json` breaks the import graph. + +**Fix.** + +```jsonc +// tsconfig.json +{ + "compilerOptions": { + "target": "ES2022", + "module": "ES2022", + "moduleResolution": "bundler" + } +} +``` + +```jsonc +// package.json +{ "type": "module" } +``` + +## `Property 'tools' does not exist on type 'Agent'` / `Property 'X' does not exist on type 'AgentConfig'` + +**Cause.** The API changed between Mastra versions; training data is stale. + +**Fix.** Read the SKILL.md and reference shipped with the installed version, not memory: + +```bash +cat node_modules/@mastra/core/dist/docs/SKILL.md +cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | jq '."Agent"' +cat node_modules/@mastra/core/dist/ +``` + +## Agent replies "I don't have access to that tool" even though a tool was defined + +**Cause.** Tool created but not registered on the `Mastra` instance, or the key used in `agent.tools` doesn't match the key used in `mastra.tools`. + +**Fix.** Register the tool in both places with the same key: + +```ts +const mastra = new Mastra({ + agents: { supportAgent }, + tools: { weatherTool }, // same key as below +}); + +const supportAgent = new Agent({ + id: "support-agent", + tools: { weatherTool }, // same key as above + /* ... */ +}); +``` + +## `Cannot read property 'then' of undefined` when running a workflow + +**Cause.** `.commit()` was not called on the workflow chain. Until `.commit()` runs, the workflow is a builder, not a runnable object. + +**Fix.** + +```ts +const workflow = createWorkflow({ /* ... */ }) + .then(step1) + .then(step2) + .commit(); // REQUIRED + +const run = await workflow.createRun(); +await run.start({ inputData }); +``` + +## Agent forgets previous messages across turns + +**Cause.** One of: (a) no `storage` on `Memory`, (b) `memory.thread` differs between calls, (c) `memory.resource` missing or changing. + +**Fix.** Keep both IDs stable across a single user's conversation: + +```ts +await agent.generate("…", { + memory: { + thread: "user-42::support", + resource: "user-42", + }, +}); +``` + +If `storage` is missing, instantiate one (e.g. `new PostgresStore({ connectionString })` from `@mastra/pg`, or `new LibSQLStore(...)` from `@mastra/libsql`) and pass it into `new Memory({ storage, ... })`. + +## `Storage is required for Memory` + +**Cause.** `new Memory({ })` was called without `storage`. + +**Fix.** Always pass a storage adapter: + +```ts +const memory = new Memory({ + id: "chat-memory", + storage, // REQUIRED + options: { lastMessages: 10 }, +}); +``` + +## Semantic recall returns only recent messages (no semantic hits) + +**Cause.** `semanticRecall: true` enabled without `vector` + `embedder` configured. + +**Fix.** Semantic recall needs all three: + +```ts +const memory = new Memory({ + id: "semantic-memory", + storage, + vector: chromaVectorStore, // REQUIRED + embedder: openaiEmbedder, // REQUIRED + options: { + lastMessages: 10, + semanticRecall: true, // REQUIRED + }, +}); +``` + +## Tool input throws `ZodError: Expected X, received Y` + +**Cause.** Tool invocation does not match `inputSchema`. Also — the field is `inputSchema`, not `parameters` (that's the AI SDK name). + +**Fix.** Align the call site with the schema. If a field should be optional, mark it `z.X().optional()`. + +## `Model 'gpt-4' not found` / `Invalid model format` + +**Cause.** Model string missing the provider prefix. + +**Fix.** Always use `provider/model`: + +```ts +const agent = new Agent({ model: "openai/gpt-5.4" }); // ✅ +const agent = new Agent({ model: "anthropic/claude-sonnet-4-5" }); // ✅ +const agent = new Agent({ model: "gpt-4" }); // ❌ +``` + +Enumerate valid providers and current model names with the script shipped in the sibling skill: + +```bash +node plugins/mastra/.agents/skills/mastra/scripts/provider-registry.mjs --list +node plugins/mastra/.agents/skills/mastra/scripts/provider-registry.mjs --provider openai +``` + +Never use model IDs from memory — they change frequently. + +## `connect ECONNREFUSED` against Postgres / LibSQL + +**Cause.** Database not running, wrong connection string, or `storage.init()` not called. + +**Fix.** + +1. Start the database (Docker, local process, managed service, …). +2. Verify `DATABASE_URL` / equivalent. +3. Call `await storage.init()` at app startup so schema tables exist. + +## Tool suspension never resumes + +**Cause.** `context.suspend(...)` called, but nothing later calls `run.resume({ resumeData })` or the resume payload doesn't match `resumeSchema`. + +**Fix.** Define both schemas and resume with matching data: + +```ts +const approvalTool = createTool({ + id: "approval", + inputSchema: z.object({ request: z.string() }), + suspendSchema: z.object({ requestId: z.string() }), + resumeSchema: z.object({ approved: z.boolean() }), + execute: async ({ context }) => { + if (!context.resumeData) { + context.suspend({ requestId: crypto.randomUUID() }); + return; + } + return { approved: context.resumeData.approved }; + }, +}); + +await run.resume({ resumeData: { approved: true } }); +``` + +## When the symptom isn't listed + +1. Grep the installed source for the exact error string: + ```bash + rg -n "error string fragment" node_modules/@mastra/core/dist + rg -n "error string fragment" node_modules/@mastra//dist + ``` +2. Check the bundled reference docs for the nearest API: + ```bash + ls node_modules/@mastra//dist/docs/references/ + ``` +3. Fall back to `https://mastra.ai/docs` or the `@mastra/mcp-docs-server` MCP tool. +4. Verify all `@mastra/*` versions match: `pnpm list | grep @mastra/`. Version skew across the scope is a common silent cause. diff --git a/plugins/mastra/.agents/skills/use-mastra/references/packages.md b/plugins/mastra/.agents/skills/use-mastra/references/packages.md new file mode 100644 index 00000000..bd3e6eb3 --- /dev/null +++ b/plugins/mastra/.agents/skills/use-mastra/references/packages.md @@ -0,0 +1,54 @@ +# Mastra Package Map + +Purpose: one row per Mastra-shipped npm package, with the canonical `dist/docs/` path to read before writing code against it, and whether the package currently bundles documentation or is remote-only. + +Verify the installed version (not the latest published) by reading each package's own `package.json` — `dist/docs/` always reflects the version *installed in the consumer's `node_modules/`*, not the version that shipped these pages. + +## Packages that ship `dist/docs/SKILL.md` + +| Package | Purpose | SKILL path (relative to consumer's `node_modules/`) | +| --- | --- | --- | +| `mastra` | CLI (`mastra dev`, `mastra build`, `mastra start`), project scaffolding, platform REST API reference | `mastra/dist/docs/SKILL.md` | +| `@mastra/core` | Framework core: `Mastra` instance, `Agent`, `createTool`, `createWorkflow`, `createStep`, processors, guardrails, supervisor agents, channels, structured output, browser + editor APIs | `@mastra/core/dist/docs/SKILL.md` | +| `@mastra/memory` | `Memory` class, threads, message history, working memory, observational memory, semantic recall, storage binding | `@mastra/memory/dist/docs/SKILL.md` | +| `@mastra/rag` | `MDocument`, chunking strategies, embeddings, retrieval, reranking, GraphRAG, vector-query tool | `@mastra/rag/dist/docs/SKILL.md` | +| `@mastra/evals` | Scorers (custom + built-in), datasets, experiments, CI-friendly evals harness | `@mastra/evals/dist/docs/SKILL.md` | +| `@mastra/deployer` | Build / package Mastra projects for deployment | `@mastra/deployer/dist/docs/SKILL.md` | +| `@mastra/server` | HTTP handlers and server runtime used by `mastra dev` and production deployments | `@mastra/server/dist/docs/SKILL.md` | +| `@mastra/pg` | Postgres storage + vector adapter | `@mastra/pg/dist/docs/SKILL.md` | +| `@mastra/libsql` | LibSQL / SQLite storage + vector adapter | `@mastra/libsql/dist/docs/SKILL.md` | +| `@mastra/mcp` | MCP (Model Context Protocol) server integration | `@mastra/mcp/dist/docs/SKILL.md` | + +Each package's `dist/docs/` contains a `references/` directory with per-topic and per-symbol markdown files, and an `assets/SOURCE_MAP.json` that maps exported symbols to their compiled type-definition files (`*.d.ts`). + +## Packages without bundled docs (remote-only) + +| Package | Purpose | Where to read | +| --- | --- | --- | +| `@mastra/observability` | Tracing, scoring telemetry, OTLP exporters | `https://mastra.ai/docs/observability` or `https://mastra.ai/llms.txt` | + +Other `@mastra/*` packages exist (framework adapters, auxiliary storage drivers, voice providers, etc.). If a package you care about is not listed here, run `npm pack --dry-run --json | jq '.[0].files[].path' | grep -i docs` to confirm whether it ships `dist/docs/`. If nothing matches, treat it as remote-only. + +## Verifying at runtime + +```bash +# List every @mastra/* package installed in the consumer project +ls node_modules/@mastra/ + +# Check whether a specific one bundles docs +test -f node_modules/@mastra/core/dist/docs/SKILL.md && echo "core ships docs" || echo "core: remote-only" + +# Read its index +cat node_modules/@mastra/core/dist/docs/SKILL.md + +# List every topic / symbol it covers +ls node_modules/@mastra/core/dist/docs/references/ +``` + +## Cross-package topic duplication + +Some topics (agent approval, supervisor agents, agent networks) appear in multiple packages' `references/` directories (e.g. in both `@mastra/core` and `@mastra/memory`) because they touch multiple subsystems. When a doc exists in more than one place, prefer the copy shipped by the package whose API you are calling — that copy matches the installed version of that package. + +## SKILL.md naming note + +Each package's bundled `SKILL.md` sets `name:` to a package-specific value (e.g. `name: mastra`, `name: mastra-core`, `name: mastra-memory`). These are intended to be read as reference documentation, not loaded as Claude Code skills, so they do not collide with the `mastra` and `use-mastra` skills installed in this plugin.