1---
2name: mastra
3description: "Comprehensive Mastra framework guide. Teaches how to find current documentation, verify API signatures, and build agents and workflows. Covers documentation lookup strategies (embedded docs, remote docs), core concepts (agents vs workflows, tools, memory, RAG), TypeScript requirements, and common patterns. Use this skill for all Mastra development to ensure you're using current APIs from the installed version or latest documentation."
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## Available files
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| "How do I use Agent/Workflow/Tool?" | [`references/embedded-docs.md`](references/embedded-docs.md)     | Look up in `node_modules/@mastra/*/dist/docs/` |
40| "How do I use X?" (no packages)     | [`references/remote-docs.md`](references/remote-docs.md)         | Fetch from `https://mastra.ai/llms.txt`        |
41| "I'm getting an error..."           | [`references/common-errors.md`](references/common-errors.md)     | Common errors and solutions                    |
42| "Upgrade from v0.x to v1.x"         | [`references/migration-guide.md`](references/migration-guide.md) | Version upgrade workflows                      |
43 
44### Scripts
45 
46- `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.
47 
48## Priority order for writing code
49 
50⚠️ Never write code without checking current docs first.
51 
521. **Embedded docs first** (if packages installed)
53 
54   Look up current docs in `node_modules` for a package. Example of looking up "Agent" docs in `@mastra/core`:
55 
56   ```bash
57   grep -r "Agent" node_modules/@mastra/core/dist/docs/references
58   ```
59 
60   - **Why:** Matches your EXACT installed version
61   - **Most reliable source of truth**
62   - **More information:** [`references/embedded-docs.md`](references/embedded-docs.md)
63 
642. **Source code second** (if packages installed)
65 
66   If you can't find what you need in the embedded docs, look directly at the source code. This is more time consuming but can provide insights into implementation details.
67 
68   ```bash
69   # Check what's available
70   cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'
71 
72   # Read the actual type definition
73   cat node_modules/@mastra/core/dist/[path-from-source-map]
74   ```
75 
76   - **Why:** Ultimate source of truth if docs are missing or unclear
77   - **Use when:** Embedded docs don't cover your question
78   - **More information:** [`references/embedded-docs.md`](references/embedded-docs.md)
79 
803. **Remote docs third** (if packages not installed)
81 
82   You can fetch the latest docs from the Mastra website:
83 
84   ```bash
85   https://mastra.ai/llms.txt
86   ```
87 
88   - **Why:** Latest published docs (may be ahead of installed version)
89   - **Use when:** Packages not installed or exploring new features
90   - **More information:** [`references/remote-docs.md`](references/remote-docs.md)
91 
92## Core concepts
93 
94### Agents vs workflows
95 
96**Agent**: Autonomous, makes decisions, uses tools
97Use for: Open-ended tasks (support, research, analysis)
98 
99**Workflow**: Structured sequence of steps
100Use for: Defined processes (pipelines, approvals, ETL)
101 
102### Key components
103 
104- **Tools**: Extend agent capabilities (APIs, databases, external services)
105- **Memory**: Maintain context (message history, working memory, semantic recall, observational memory)
106- **RAG**: Query external knowledge (vector stores, graph relationships)
107- **Storage**: Persist data (Postgres, LibSQL, MongoDB)
108 
109### Mastra Studio
110 
111Studio provides an interactive UI for building, testing, and managing agents, workflows, and tools. It helps with debugging and improving your applications iteratively.
112 
113Inside a Mastra project, run:
114 
115```bash
116npm run dev
117```
118 
119Then open `http://localhost:4111` in your browser to access Mastra Studio.
120 
121## Critical requirements
122 
123### TypeScript config
124 
125Mastra requires **ES2022 modules**. CommonJS will fail.
126 
127```json
128{
129  "compilerOptions": {
130    "target": "ES2022",
131    "module": "ES2022",
132    "moduleResolution": "bundler"
133  }
134}
135```
136 
137### Model format
138 
139Always use `"provider/model-name"` when defining models using Mastra's model router.
140 
141Use the provider registry script to look up available providers and models:
142 
143```bash
144# List all available providers
145node scripts/provider-registry.mjs --list
146 
147# List all models for a specific provider (sorted newest first)
148node scripts/provider-registry.mjs --provider openai
149node scripts/provider-registry.mjs --provider anthropic
150```
151 
152When the user asks to use a model or provider, **always run the script first** to verify the provider key and model name are valid. Do not guess model names from memory as they change frequently.
153 
154Example model strings:
155 
156- `"openai/gpt-5.4"`
157- `"anthropic/claude-sonnet-4-5"`
158- `"google/gemini-2.5-pro"`
159 
160## When you see errors
161 
162**Type errors often mean your knowledge is outdated.**
163 
164**Common signs of outdated knowledge:**
165 
166- `Property X does not exist on type Y`
167- `Cannot find module`
168- `Type mismatch` errors
169- Constructor parameter errors
170 
171**What to do:**
172 
1731. Check [`references/common-errors.md`](references/common-errors.md)
1742. Verify current API in embedded docs
1753. Don't assume the error is a user mistake - it might be your outdated knowledge
176 
177## Development workflow
178 
179**Always verify before writing code:**
180 
1811. **Check packages installed**
182 
183   ```bash
184   ls node_modules/@mastra/
185   ```
186 
1872. **Look up current API**
188   - If installed → Use embedded docs [`references/embedded-docs.md`](references/embedded-docs.md)
189   - If not → Use remote docs [`references/remote-docs.md`](references/remote-docs.md)
190 
1913. **Write code based on current docs**
192 
1934. **Test in Studio**
194   ```bash
195   npm run dev  # http://localhost:4111
196   ```
197 
198## Resources
199 
200- **Setup**: [`references/create-mastra.md`](references/create-mastra.md)
201- **Embedded docs lookup**: [`references/embedded-docs.md`](references/embedded-docs.md) - Start here if packages are installed
202- **Remote docs lookup**: [`references/remote-docs.md`](references/remote-docs.md)
203- **Common errors**: [`references/common-errors.md`](references/common-errors.md)
204- **Migrations**: [`references/migration-guide.md`](references/migration-guide.md)
205