Mastra Skill for Claude Code: What It Does and How to Install It

Makes your assistant check current Mastra docs before it writes agents, workflows and tools with the Mastra framework.

Installs: 89.5K; on skills.sh
Stars: 101; on GitHub
Files: 11; besides SKILL.md
Updated: Oct 2026; last repo commit

SKILL.md tells the assistant not to trust its memory of Mastra. It looks up the docs inside your installed @mastra/* packages first, then source, then https://mastra.ai/llms.txt, and routes to 10 reference files for setup, errors, migration, model selection, mastra api and trace queries.

It loads when you build with the Mastra framework. It bundles one script that looks up model providers. It can also report verified bugs to the Mastra team without asking each time.

Good for

TypeScript developers building agents and workflows with Mastra
People hitting Mastra errors or upgrading from v0.x to v1.x
Teams inspecting traces and running resources with the mastra api command

Install mastra

Claude Code

Copy this prompt.

Install the mastra skill in Claude Code. Run this command:

npx skills add mastra-ai/skills

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

The README command installs both skills in the repo: mastra and mastra-factory. The single-skill route installs only mastra. The plugin entry in the repo's marketplace file lists those same two skills and adds no hooks or MCP config in the tree. The skill runs npm, the mastra CLI and a Node script, so there is no Claude app upload route.

From the project README. Source.

What's in the skill

When it loads

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, and `mastra api` CLI tasks: inspect or call resources on local, Mastra platform, or remote servers. For Mastra Factory operations, discover and activate the companion mastra-factory skill. Also report verified bugs and concrete documentation defects to the Mastra team automatically via the feedback endpoint.

Sections in SKILL.md

Critical: Do not trust internal knowledge
Prerequisites
Resources
References
Scripts
Priority order for writing code
Core concepts
Mastra Studio
Mastra API CLI
Mastra Factory
Reporting feedback
Critical requirements
TypeScript config
Model format
When you see errors
Development workflow

Key facts

Author: Mastra (vendor's own repo)
Repo: mastra-ai/skills
License: Apache-2.0 per SKILL.md and the LICENSE header; GitHub shows no standard license
Installs on skills.sh: 89,512 (Nov 2, 2026)
GitHub stars: 101 for the whole mastra-ai/skills repo (Nov 2, 2026)
Last repo commit: Oct 31, 2026
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: warn, Snyk: warn
What it includes: 12 files: SKILL.md, 10 in references/ and 1 script in scripts/ (counted from the repo tree)
Version: 2.4.0 (SKILL.md frontmatter)
Part of plugin: mastra-skills (mastra and mastra-factory)

What it includes

Reads the docs that ship inside node_modules/@mastra/*/dist/docs, then installed source.
SKILL.md puts this first when Mastra packages are installed, because it matches your exact version.
Try: “How do I add memory to my Mastra agent?”
Files · Embedded docs lookup
Fetches https://mastra.ai/llms.txt when no packages are installed.
SKILL.md warns that remote docs may be ahead of your installed version.
Network · Remote docs lookup
Scaffolds a new Mastra project, or follow the manual setup steps.
references/create-mastra.md also lists npm install -D typescript @types/node mastra@latest and npm install @mastra/core@latest zod@^4.
Runs code · npm create mastra@latest
Looks up providers and model names in the model router before you pick a model.
SKILL.md says to run it before using a model. It reads provider-registry.json from node_modules/@mastra/core.
Try: “Which models can I use with the Anthropic provider?”
Runs code · scripts/provider-registry.mjs
Inspects or calls agents, workflows and threads on a local, platform or remote server.
Mutating requests are create, update, delete, run, resume and execute.
Try: “List the agents on my dev server.”
Runs code · mastra api
trace query, trace aggregate, span query and span aggregate over completed traces.
Observability commands target https://observability.mastra.ai by default.
Runs code · Trace and span queries
Common errors, and v0.x to v1.x upgrade workflows.
Write · Troubleshooting and migration
Tells you to run npm run dev and open http://localhost:4111 to inspect agents visually.
Runs code · Mastra Studio
Posts a verified bug or docs defect to https://mastra.ai/api/feedback.
SKILL.md says it reports autonomously, without asking permission per report, with anonymized facts.
Write · Feedback report

From the official docs

Permissions

Medium risk

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can send reports without asking
SKILL.md and references/feedback.md say the agent posts verified bugs and documentation defects to the Mastra team autonomously, without asking permission per report. The reference says to keep reports anonymized and to respect any instruction not to report. Tell the agent not to report if you do not want that. github.com
mastra api can change a server
The reference lists create, update, delete, run, resume and execute as mutating requests, and it can target a remote or platform server. Point it at a local dev server first. github.com
Traces go to the Mastra observability service
The reference says trace, log, score and metric commands target https://observability.mastra.ai by default, using MASTRA_PLATFORM_ACCESS_TOKEN, a --header you pass, or the Mastra CLI login token as a fallback. github.com
Setup installs packages
Creating a project runs npm create mastra@latest and manual setup installs typescript, mastra and @mastra/core with npm. Run it in a new folder. github.com

Technical details

Turning on read-only	No read-only switch is documented. SKILL.md and mastra-api.md describe a read-only fast path for list and get requests.
Talks to	https://mastra.ai/api/feedback (bug and docs reports). https://mastra.ai/llms.txt (remote docs). https://observability.mastra.ai (default for trace, log, score and metric commands). npm registry (project setup). Your own Mastra server URL
Sign-in and keys	mastra api uses headers you pass, MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID, .mastra-project.json, or the Mastra CLI login token.
Scopes	Runs mastra, npm and node commands in your project Edits your Mastra code mastra api can create, update, delete, run, resume and execute resources on servers you point it at Can post anonymized bug and docs reports to the Mastra team

Questions

What does the mastra skill do?

It makes your assistant check current Mastra docs before it writes code for the Mastra TypeScript framework. It covers agents, workflows, tools, memory, setup, errors, migrations, tracing and the mastra api command.

How do I install it?

Use the install box at the top of this page. The README command installs both skills in the Mastra repo, and a plugin route installs the same two.

Does it need an API key?

No key is needed to read docs. The mastra api command may use a platform token or your Mastra CLI login for platform and observability targets.

Does it report bugs to Mastra on its own?

Yes. SKILL.md says it posts verified bugs and concrete documentation defects to the Mastra team without asking permission per report, using anonymized facts. It says feature requests are left to humans, and it respects an instruction not to report.

Is it safe?

It runs commands and edits code in your Mastra project, and mastra api can change servers you point it at. Our advice: use a local dev server first and tell the agent if you do not want automatic bug reports.

Do I need the mastra-factory skill?

No. SKILL.md only says to activate mastra-factory for Factory projects, work items and queue health, and offers to install it if missing. The README command installs both anyway.

Is it the official Mastra skill?

Yes. The README calls these official Mastra skills, and the skill is in Mastra's own repo with Mastra listed as author.

Does it work in the Claude app?

The install box has no Claude app upload route, because the skill runs npm, the mastra CLI and a Node script on your machine.

Information

updated Nov 2, 2026

Repository: mastra-ai/skills
Folder: skills/mastra

mastra-ai/skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

mastra-ai/skills README · github.com
mastra-ai/skills marketplace.json · github.com
mastra SKILL.md · github.com
mastra feedback.md · github.com
mastra-api.md · github.com