1---
2name: mastra
3description: "Comprehensive Mastra framework guide for building agents, workflows, tools, memory, workspaces, and storage with current APIs. Use for documentation lookup, API verification, TypeScript setup, common errors, migrations, and `mastra api` CLI tasks: inspect or call resources on local, Mastra platform, or remote servers."
4license: Apache-2.0
5metadata:
6  author: Mastra
7  version: "2.0.0"
8  repository: https://github.com/mastra-ai/skills
9---
10 
11# Mastra Framework Guide
12 
13Build AI applications with Mastra. This skill teaches you how to find current documentation and build agents and workflows.
14 
15## Critical: Do not trust internal knowledge
16 
17Everything you know about Mastra is likely outdated or wrong. Never rely on memory. Always verify against current documentation.
18 
19Your training data contains obsolete APIs, deprecated patterns, and incorrect usage. Mastra evolves rapidly - APIs change between versions, constructor signatures shift, and patterns get refactored.
20 
21## Prerequisites
22 
23Before writing any Mastra code, check if packages are installed:
24 
25```bash
26ls node_modules/@mastra/
27```
28 
29- If packages exist: Use embedded docs first (most reliable)
30- If no packages: Install first or use remote docs
31 
32## Resources
33 
34### References
35 
36| User Question                       | First Check                                                      | How To                                         |
37| ----------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
38| Create/install Mastra project     | [`references/create-mastra.md`](references/create-mastra.md)     | Setup guide with CLI and manual steps          |
39| Choose Agent/Workflow/Tool/Memory/Storage | [`references/core-concepts.md`](references/core-concepts.md) | Core concepts and when to use each primitive |
40| How do I use Agent/Workflow/Tool? | [`references/embedded-docs.md`](references/embedded-docs.md)     | Look up in `node_modules/@mastra/*/dist/docs/` |
41| How do I use X? (no packages)     | [`references/remote-docs.md`](references/remote-docs.md)         | Fetch from `https://mastra.ai/llms.txt`        |
42| Choose or validate a model        | [`references/model-selection.md`](references/model-selection.md) | Model format and provider registry lookup      |
43| I'm getting an error...           | [`references/common-errors.md`](references/common-errors.md)     | Common errors and solutions                    |
44| Upgrade from v0.x to v1.x         | [`references/migration-guide.md`](references/migration-guide.md) | Version upgrade workflows                      |
45| Inspect/call server resources via CLI | [`references/mastra-api.md`](references/mastra-api.md)       | `mastra api` CLI for local, Mastra platform, or remote servers |
46 
47### Scripts
48 
49- `scripts/provider-registry.mjs`: Look up current providers and models available in the model router. Always run this before using a model to verify provider keys and model names.
50 
51## Priority order for writing code
52 
53Never write code without checking current docs first.
54 
551. Embedded docs first (if packages installed)
56 
57   Look up current docs in `node_modules` for a package. This matches the exact installed version and is the most reliable source of truth. See [`references/embedded-docs.md`](references/embedded-docs.md).
58 
592. Source code second (if packages installed)
60 
61   If embedded docs don't cover the question, inspect the installed source and type definitions. This is the source of truth when docs are missing or unclear. See [`references/embedded-docs.md`](references/embedded-docs.md).
62 
633. Remote docs third (if packages not installed)
64 
65   Use the latest published docs when packages are not installed or when exploring new features. Remote docs may be ahead of the user's installed version. See [`references/remote-docs.md`](references/remote-docs.md).
66 
67## Core concepts
68 
69Use [`references/core-concepts.md`](references/core-concepts.md) when choosing between agents, workflows, tools, memory, and storage.
70 
71- Agent: Use for open-ended tasks that make decisions and use tools.
72- Workflow: Use for defined multi-step processes.
73 
74## Mastra Studio
75 
76Studio is the interactive UI for building, testing, and managing agents, workflows, and tools. Use Studio when advising a human to inspect or debug visually.
77 
78Inside a Mastra project, run:
79 
80```bash
81npm run dev
82```
83 
84Then open `http://localhost:4111` in a browser to show Mastra Studio to your human user.
85 
86## Mastra API CLI
87 
88Use `mastra api` to inspect or call resources on local dev servers, Mastra platform deployments, or remote Mastra endpoints. It is useful for agent-readable state, execution, traces, logs, scores, threads, and workflow operations. See [`references/mastra-api.md`](references/mastra-api.md) for usage patterns.
89 
90## Critical requirements
91 
92### TypeScript config
93 
94Mastra requires ES2022 modules. CommonJS will fail. See [`references/create-mastra.md`](references/create-mastra.md) for setup and [`references/common-errors.md`](references/common-errors.md) for troubleshooting.
95 
96### Model format
97 
98Always use `"provider/model-name"` when defining models using Mastra's model router.
99 
100When the user asks to use a model or provider, always run `scripts/provider-registry.mjs` first to verify the provider key and model name are valid. Do not guess model names from memory as they change frequently. See [`references/model-selection.md`](references/model-selection.md).
101 
102## When you see errors
103 
104Type errors often mean your knowledge is outdated.
105 
106Common signs of outdated knowledge:
107 
108- `Property X does not exist on type Y`
109- `Cannot find module`
110- `Type mismatch` errors
111- Constructor parameter errors
112 
113What to do:
114 
1151. Check [`references/common-errors.md`](references/common-errors.md)
1162. Verify current API in embedded docs
1173. Don't assume the error is a user mistake - it might be your outdated knowledge
118 
119## Development workflow
120 
121Always verify before writing code:
122 
1231. Check whether Mastra packages are installed
1242. Look up current API
125   - If installed: Use embedded docs [`references/embedded-docs.md`](references/embedded-docs.md)
126   - If not: Use remote docs [`references/remote-docs.md`](references/remote-docs.md)
1273. Write code based on current docs
1284. Test with the project scripts or Studio when available
129