---
name: mastra
description: Reference guide for building agents and workflows with current Mastra APIs. Always verify against embedded docs in node_modules/@mastra/*/dist/docs/ (installed version) or remote docs at https://ma...
---

# mastra

Reference guide for building agents and workflows with current Mastra APIs. Always verify against embedded docs in node_modules/@mastra/*/dist/docs/ (installed version) or remote docs at https://mastra.ai/llms.txt before writing code; training data is outdated Core building blocks: Agents (autonomous, decision-making), Workflows (structured sequences), Tools (extend capabilities), Memory (maintain context), and RAG (external knowledge) Requires ES2022 modules in TypeScript config and model...

# mastraby mastra-ai
Reference guide for building agents and workflows with current Mastra APIs. Always verify against embedded docs in node_modules/@mastra/*/dist/docs/ (installed version) or remote docs at https://mastra.ai/llms.txt before writing code; training data is outdated Core building blocks: Agents (autonomous, decision-making), Workflows (structured sequences), Tools (extend capabilities), Memory (maintain context), and RAG (external knowledge) Requires ES2022 modules in TypeScript config and model...

`npx skills add https://github.com/mastra-ai/skills --skill mastra`Download ZIPGitHub

## Mastra Framework Guide

Build AI applications with Mastra. This skill teaches you how to find current documentation and build agents and workflows.

## Critical: Do not trust internal knowledge

Everything you know about Mastra is likely outdated or wrong. Never rely on memory. Always verify against current documentation.

Your training data contains obsolete APIs, deprecated patterns, and incorrect usage. Mastra evolves rapidly - APIs change between versions, constructor signatures shift, and patterns get refactored.

## Prerequisites

Before writing any Mastra code, check if packages are installed:

```
`ls node_modules/@mastra/
`
```

* If packages exist: Use embedded docs first (most reliable)

* If no packages: Install first or use remote docs

## Resources

### References

User QuestionFirst CheckHow ToCreate/install Mastra project`references/create-mastra.md`Setup guide with CLI and manual stepsChoose Agent/Workflow/Tool/Memory/Storage`references/core-concepts.md`Core concepts and when to use each primitiveHow do I use Agent/Workflow/Tool?`references/embedded-docs.md`Look up in `node_modules/@mastra/*/dist/docs/`How do I use X? (no packages)`references/remote-docs.md`Fetch from `https://mastra.ai/llms.txt`Choose or validate a model`references/model-selection.md`Model format and provider registry lookupI'm getting an error...`references/common-errors.md`Common errors and solutionsUpgrade from v0.x to v1.x`references/migration-guide.md`Version upgrade workflowsInspect/call server resources via CLI`references/mastra-api.md``mastra api` CLI for local, Mastra platform, or remote servers

### Scripts

* `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.

## Priority order for writing code

Never write code without checking current docs first.

*
Embedded docs first (if packages installed)

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`.

*
Source code second (if packages installed)

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`.

*
Remote docs third (if packages not installed)

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`.

## Core concepts

Use `references/core-concepts.md` when choosing between agents, workflows, tools, memory, and storage.

* Agent: Use for open-ended tasks that make decisions and use tools.

* Workflow: Use for defined multi-step processes.

## Mastra Studio

Studio is the interactive UI for building, testing, and managing agents, workflows, and tools. Use Studio when advising a human to inspect or debug visually.

Inside a Mastra project, run:

```
`npm run dev
`
```

Then open `http://localhost:4111` in a browser to show Mastra Studio to your human user.

## Mastra API CLI

Use `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` for usage patterns.

## Critical requirements

### TypeScript config

Mastra requires ES2022 modules. CommonJS will fail. See `references/create-mastra.md` for setup and `references/common-errors.md` for troubleshooting.

### Model format

Always use `"provider/model-name"` when defining models using Mastra's model router.

When 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`.

## When you see errors

Type errors often mean your knowledge is outdated.

Common signs of outdated knowledge:

* `Property X does not exist on type Y`

* `Cannot find module`

* `Type mismatch` errors

* Constructor parameter errors

What to do:

* Check `references/common-errors.md`

* Verify current API in embedded docs

* Don't assume the error is a user mistake - it might be your outdated knowledge

## Development workflow

Always verify before writing code:

* Check whether Mastra packages are installed

* Look up current API

* If installed: Use embedded docs `references/embedded-docs.md`

* If not: Use remote docs `references/remote-docs.md`

* Write code based on current docs

* Test with the project scripts or Studio when available

## More skills from mastra-ai
debugging-difficult-bugsby mastra-aiUse early when debugging a medium or hard bug, especially when tests alone may not reveal the real runtime failure. Trigger this before extended TDD iteration…e2e-frontend-validationby mastra-aiE2E validation workflow for frontend changes in playground packages using Playwright MCPe2e-tests-studioby mastra-aiCRITICAL : Tests must verify that product features WORK correctly, not just that UI elements render.mastra-docsby mastra-aiDocumentation guidelines for Mastra. This skill should be used when writing or editing documentation for Mastra. Triggers on tasks involving documentation…mastra-smoke-testby mastra-aiSmoke test Mastra projects locally or deploy to staging/production. Tests Studio UI, agents, tools, workflows, traces, memory, and more. Supports both local…ralph-planby mastra-aiInteractive planning assistant that helps create focused, well-structured ralph-loop commands through collaborative conversationreact-best-practicesby mastra-aiReact performance optimization guidelines from Mastra Engineering. This skill should be used when writing, reviewing, or refactoring React code to ensure…smoke-testby mastra-aiCreate a Mastra project using create-mastra and smoke test the studio in Chrome using Chrome MCP server

---

**Source**: https://github.com/mastra-ai/skills/tree/HEAD/skills/mastra
**Author**: mastra-ai
**Discovered via**: mcpservers.org