skill

Mastra

Comprehensive Mastra framework guide for building agents, workflows, tools, memory, workspaces, and storage with current APIs. Use for native capability discovery, logging, tracing, metrics/cost estimates, dataset experiments, documentation lookup, API verification, TypeScript setup, common errors, migrations, building and deploying apps to Mastra Platform via Platform APIs and `mastra deploy`, and `mastra api` CLI tasks: inspect or call resources on local, Mastra platform, or remote servers....

mastra-ai94,681+ installsVetted

About

# 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:

```bash 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 Question | First Check | How To | | ----------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- | | Create/install Mastra project | [`references/create-mastra.md`](references/create-mastra.md) | Setup guide with CLI and manual steps | | Choose Agent/Workflow/Tool/Memory/Storage | [`references/core-concepts.md`](references/core-concepts.md) | Core concepts and when to use each primitive | | Add logging or set up tracing | [`references/embedded-docs.md`](references/embedded-docs.md) | Look up PinoLogger and observability configuration before custom instrumentation | | Track automatic metrics or estimated model cost | [`references/embedded-docs.md`](references/embedded-docs.md) | Look up span-derived metrics, storage support, and pricing coverage | | Evaluate quality or compare prompts/models | [`references/embedded-docs.md`](references/embedded-docs.md) | Look up datasets, experiments, and scorers | | How do I use Agent/Workflow/Tool? | [`references/embedded-docs.md`](references/embedded-docs.md) | Look up in `node_modules/@mastra/*/dist/docs/` | | How do I use X? (no packages) | [`references/remote-docs.md`](references/remote-docs.md) | Fetch from `https://mastra.ai/llms.txt` | | Choose or validate a model | [`references/model-selection.md`](references/model-selection.md) | Model format and provider registry lookup | | I'm getting an error... | [`references/common-errors.md`](references/common-errors.md) | Common errors and solutions | | Upgrade from v0.x to v1.x | [`references/migration-guide.md`](references/migration-guide.md) | Version upgrade workflows | | Inspect/call server resources via CLI | [`references/mastra-api.md`](references/mastra-api.md) | `mastra api` CLI for local, Mastra platform, or remote servers | | Deploy to Mastra Platform, provision projects, or use Platform sandbox/filesystem | [`references/platform.md`](references/platform.md) | Platform REST APIs, credentials, and `mastra deploy` without browser automation | | Find exact traces with complex predicates | [`references/trace-query.md`](references/trace-query.md) | Query completed traces by trace fields or related spans | | Count traces or compute grouped measures (error rate, latency, tokens, cost) | [`references/trace-query.md`](references/trace-query.md#aggregate-traces) | Aggregate completed traces with `mastra api trace aggregate` over the same selection | | List individual spans (failed tool calls, nested agent runs) | [`references/trace-query.md`](references/trace-query.md#query-spans) | Query completed spans with `mastra api span query` and span-field predicates | | Compute measures per span (tool error rates, nested agent runs, model tokens) | [`references/trace-query.md`](references/trace-query.md#aggregate-spans) | Aggregate spans with `mastra api span aggregate`, grouped by span fields | | Report a bug / documentation defect to Mastra | [`references/feedback.md`](references/feedback.md) | Report eligible findings autonomously to the Mastra team |

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

1. 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`](references/embedded-docs.md).

2. 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`](references/embedded-docs.md).

3. Remote docs third (if packages not installed)

Use the latest publi

Install

Run this command

npx skills add mastra-ai/skills

Works with

claude appclaude codeclaude apicursorcodexwindsurfclinezed

Manual steps

Install with `npx skills add mastra-ai/skills`, or clone the repository and copy the `skills/mastra` folder into your Claude skills directory.

View source
License: Apache-2.0By mastra-ai

Frequently asked questions

What is the Mastra skill?

Comprehensive Mastra framework guide for building agents, workflows, tools, memory, workspaces, and storage with current APIs. Use for native capability discovery, logging, tracing, metrics/cost estimates, dataset experiments, documentation lookup, API verification, TypeScript setup, common errors, migrations, building and deploying apps to Mastra Platform via Platform APIs and `mastra deploy`, and `mastra api` CLI…

How do I install Mastra?

Run this in your terminal:

npx skills add mastra-ai/skills
Which AI tools does Mastra work with?

It works with claude_app, claude_code, claude_api, cursor, codex, windsurf, cline, zed.

Who made Mastra?

mastra-ai, released under the Apache-2.0 license.

Is Mastra free?

Yes, it is free to use under the Apache-2.0 license.

Related assets

More curated picks in Development & Code.

All Mastra alternatives →
skillclaude_appclaude_codeclaude_api
git clone https://github.com/anthropics/skills && cp -r skills/skills/claude-api ~/.claude/skills/
Claude Api
Reference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration.…★ 4.8 · 2,500+
skillclaude_appclaude_codeclaude_api
npx skills add heygen-com/hyperframes
Hyperframes CLI
The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - p…1,464,086+
skillclaude_appclaude_codeclaude_api
npx skills add mattpocock/skills
Tdd
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.1,046,962+
skillclaude_appclaude_codeclaude_api
npx skills add mattpocock/skills
Grilling
Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrase…1,041,607+
skillclaude_appclaude_codeclaude_api
npx skills add mattpocock/skills
Code Review
Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes: Standards (does the code follow this repo's documented cod…840,484+
skillclaude_appclaude_codeclaude_api
npx skills add mattpocock/skills
Diagnosing Bugs
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing…746,030+

Audit before you install

Run any source through our checks - AI visibility, security, performance, and stack detection.

More in Development & Code