Mastra

MastraOfficialCreated by Mastra

Skill
Tool integration
Software development
Apache-2.0
Low risk
Has scripts

From the author

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

— the description by Mastra

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The Mastra skill provides a comprehensive framework for developing AI agents, workflows, and tools. It emphasizes a strict development workflow that prioritizes current documentation over internal knowledge to account for the framework's rapid evolution. The skill covers project setup, API verification, observability, deployment to the Mastra Platform, and troubleshooting common errors. It also provides guidance on using the Mastra CLI for resource inspection and managing state, ensuring developers use native capabilities before implementing custom solutions.

What it does

Provides a structured approach to discovering and using native Mastra capabilities.
Offers guidance on choosing between agents, workflows, tools, memory, and storage.
Facilitates debugging through Mastra Studio and common error resolution patterns.
Supports deployment workflows to the Mastra Platform via CLI and API.
Enables autonomous reporting of verified bugs and documentation defects.
Includes instructions for CLI-based resource inspection and trace querying.

When to use it

When starting a new Mastra project or migrating existing code.
When you need to verify the latest API signatures or model registry entries.
When troubleshooting build, configuration, or runtime errors in a Mastra application.
When you need to deploy an application or inspect resources on the Mastra Platform.
When you need to implement observability, logging, or trace aggregation.

Advantages

Reduces errors by enforcing a 'verify-first' approach using embedded documentation.
Ensures compatibility by prioritizing installed package versions over training data.
Streamlines development with clear patterns for agents, workflows, and memory.
Provides direct paths for reporting issues to the Mastra team.
Centralizes access to CLI tools for local and remote resource management.

Usage examples

“How do I set up a new Mastra project?”: The agent will guide you through the CLI and manual setup steps found in the project's reference documentation.
“I am getting a 'Property tools does not exist on type Agent' error.”: The agent will check the embedded documentation to identify if you are using an outdated API and provide the correct constructor pattern.
“How do I deploy my Mastra app to the platform?”: The agent will walk you through the platform authentication, project creation, and deployment steps using the Mastra CLI.
“Which model should I use for my agent?”: The agent will run the provider registry script to verify available models and providers before making a recommendation.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/mastra-ai/mastra/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip mastra.zip -d .agents/skills
```

Documentation by Mastra

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 Question	First Check	How To
Create/install Mastra project	`references/create-mastra.md`	Setup guide with CLI and manual steps
Choose Agent/Workflow/Tool/Memory/Storage	`references/core-concepts.md`	Core concepts and when to use each primitive
Add logging or set up tracing	`references/embedded-docs.md`	Look up PinoLogger and observability configuration before custom instrumentation
Track automatic metrics or estimated model cost	`references/embedded-docs.md`	Look up span-derived metrics, storage support, and pricing coverage
Evaluate quality or compare prompts/models	`references/embedded-docs.md`	Look up datasets, experiments, and scorers
How 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 lookup
I'm getting an error...	`references/common-errors.md`	Common errors and solutions
Upgrade from v0.x to v1.x	`references/migration-guide.md`	Version upgrade workflows
Inspect/call server resources via CLI	`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`	Platform REST APIs, credentials, and `mastra deploy` without browser automation
Find exact traces with complex predicates	`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`	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`	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`	Aggregate spans with `mastra api span aggregate`, grouped by span fields
Report a bug / documentation defect to Mastra	`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.

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.

For exact trace selection that needs recursive predicates or conditions over related spans, read references/trace-query.md. Before using mastra api trace query, confirm that the installed CLI exposes the command. Use --schema for the target's request/response shape and structural constraints, and use the canonical documentation found through references/remote-docs.md for supported fields, operators, and semantics. Preserve opaque pagination cursors and fetch trace or span details only after selecting candidates.

Deploy to Mastra Platform

When the user asks to deploy to Mastra, whether to build a new app and deploy it or to deploy an existing Mastra project, read references/platform.md before running any deploy or Platform API command. It covers which steps need the human (sign-up and sign-in only), credentials, REST discovery and project creation, PlatformFilesystem and PlatformSandbox, mastra deploy, and verification. Build or locate the app first with the references above, then follow platform.md to deploy.

Mastra Factory

For Factory projects, work items, queue health, decisions, session history, memory inspection, or authorized operations, activate the mastra-factory skill. Factory is an operational control plane, not a reason to scaffold or deploy a new Mastra app.

If the skill is missing, offer to install it from this repository:

npx skills add mastra-ai/skills --skill mastra-factory

Choose the user's intended agent and scope interactively. For global installation, target a supported agent explicitly with --agent <agent> -g; PromptScript does not support global installs. Verify installation and referenced files for the intended agent even if another agent target fails.

The Factory skill covers CLI checks, mastra auth whoami / authorized mastra auth login, and connecting via the user's actual instance URL from any directory. A deployed repository or .mastra-project.json is not required with --url. Never guess a shared Factory host or project IDs. Its connection and session-inspection references cover deployment-specific authentication, project discovery, threads, and observational memory limitations.

Reporting feedback

Report verified Mastra bugs and concrete documentation defects autonomously when the criteria in references/feedback.md are met, without asking permission per report. Leave feature requests to humans; do not submit them or reclassify them as defects. Do not report the same issue again within the current task or conversation. Capture only anonymized facts for feedback while solving the task. Skip automatic reporting when a finding remains unverified or its relevance is unclear; do not interrupt the user merely to classify it. Respect any user instruction not to report something.

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:

Identify whether Mastra already provides the requested behavior using references/core-concepts.md, before designing custom infrastructure.
Check installed packages and versions, then verify the capability's APIs, configuration, and limits.
- If installed: Use embedded docs references/embedded-docs.md and installed types/source.
- If not: Use remote docs references/remote-docs.md; verify compatibility before adopting newer features.
Use the native capability where it fits; implement custom logic only for the identified gap or application-owned requirements.
Test with the project scripts or Studio when available.

Files

ATTRIBUTION.mdAdded by AutoGineer878 B
LICENSELicence file added by AutoGineer588 B
SKILL.md11.5 KiB
references/common-errors.md10.2 KiB
references/core-concepts.md1.2 KiB
references/create-mastra.md6.0 KiB
references/embedded-docs.md3.5 KiB
references/feedback.md10.6 KiB
references/mastra-api.md10.6 KiB
references/migration-guide.md5.1 KiB
references/model-selection.md925 B
references/platform.md12.9 KiB
references/remote-docs.md5.4 KiB
references/trace-query.md12.1 KiB
scripts/provider-registry.mjsScript5.6 KiB

scripts/provider-registry.mjs

#!/usr/bin/env node

import { readFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";

const __dirname = dirname(fileURLToPath(import.meta.url));

function findRegistryPath() {
  const rel = join('node_modules', '@mastra', 'core', 'dist', 'provider-registry.json');
  // Walk up from script location to find project root with node_modules
  let dir = __dirname;
  for (let i = 0; i < 10; i++) {
    try {
      const p = join(dir, rel);
      readFileSync(p, "utf-8");
      return p;
    } catch {
      dir = dirname(dir);
    }
  }
  // Fall back to cwd
  return join(process.cwd(), rel);
}

function loadRegistry() {
  const path = findRegistryPath();
  try {
    return JSON.parse(readFileSync(path, "utf-8"));
  } catch (e) {
    console.error(`Error: Could not load provider registry at ${path}`);
    console.error(e.message);
    process.exit(1);
  }
}

/**
 * Extract version numbers from a model name for sorting.
 * Returns an array of numeric segments, e.g. "gpt-5.4" → [5, 4].
 * Handles dot-separated (3.5), hyphen-separated (3-7), and mixed formats.
 * Models without detectable version numbers return null.
 */
function extractVersion(name) {
  // Use named capture to grab version-like sequences along with their context.
  // We capture digits separated by dots/hyphens, plus any trailing letter for filtering.
  const regex = /(\d+(?:[.\-]\d+)*)([a-zA-Z])?/g;
  const candidates = [];
  let match;
  while ((match = regex.exec(name)) !== null) {
    const numStr = match[1];
    const suffix = match[2] || "";
    candidates.push({ numStr, suffix, index: match.index });
  }
  if (candidates.length === 0) return null;

  // Process candidates: filter and clean up non-version parts
  const processed = [];
  for (const c of candidates) {
    let parts = c.numStr.split(/[.\-]/).map(Number);
    // If followed by a size suffix (b/B/k/K/m/M/t/T) — e.g. "8b", "70B", "1t" —
    // strip the last numeric part (param count) but keep earlier parts as the version
    if (/^[bBkKmMtT]$/.test(c.suffix)) {
      parts = parts.slice(0, -1);
      if (parts.length === 0) continue;
    }
    // Strip date-like segments (>= 2020 or YYYYMMDD-style 8-digit numbers)
    parts = parts.filter((p) => p < 2020);
    if (parts.length === 0) continue;
    // Skip very large standalone numbers (parameter counts, IDs)
    if (parts.length === 1 && parts[0] >= 100 && candidates.length > 1) continue;
    // Skip trailing date-like patterns (MM-DD) in the latter half of the name
    if (
      parts.length === 2 &&
      parts[0] >= 1 && parts[0] <= 12 &&
      parts[1] >= 1 && parts[1] <= 31 &&
      c.index > name.length / 2 &&
      candidates.length > 1
    ) continue;
    processed.push(parts);
  }

  if (processed.length === 0) return null;

  // Return the first valid version candidate (versions appear early in model names)
  return processed[0];
}

function compareVersionsDesc(a, b) {
  const va = extractVersion(a);
  const vb = extractVersion(b);

  // Models without versions go to the end
  if (!va && !vb) return a.localeCompare(b);
  if (!va) return 1;
  if (!vb) return -1;

  // Compare version tuples numerically, descending
  const len = Math.max(va.length, vb.length);
  for (let i = 0; i < len; i++) {
    const ai = va[i] ?? 0;
    const bi = vb[i] ?? 0;
    if (bi !== ai) return bi - ai;
  }
  // Same version — secondary sort by full name descending
  return b.localeCompare(a);
}

function printUsage() {
  console.log(`Usage: provider-registry.mjs [options]

Options:
  --list               List all available model providers
  --provider <name>    List all models for a provider (sorted newest first)
  --help               Show this help message

Examples:
  node provider-registry.mjs --list
  node provider-registry.mjs --provider openai
  node provider-registry.mjs --provider anthropic`);
}

function listProviders(registry) {
  const entries = Object.entries(registry.providers)
    .map(([key, val]) => ({ key, name: val.name || key }))
    .sort((a, b) => a.key.localeCompare(b.key));

  const maxKey = Math.max(...entries.map((e) => e.key.length));
  const maxName = Math.max(...entries.map((e) => e.name.length));

  console.log(`${"PROVIDER".padEnd(maxKey)}  ${"NAME".padEnd(maxName)}  MODELS`);
  console.log(`${"─".repeat(maxKey)}  ${"─".repeat(maxName)}  ${"─".repeat(6)}`);
  for (const entry of entries) {
    const modelCount = registry.providers[entry.key].models.length;
    console.log(`${entry.key.padEnd(maxKey)}  ${entry.name.padEnd(maxName)}  ${modelCount}`);
  }
  console.log(`\n${entries.length} providers`);
}

function listModels(registry, providerName) {
  const provider = registry.providers[providerName];
  if (!provider) {
    console.error(`Error: Provider "${providerName}" not found.`);
    console.error(`Run with --list to see available providers.`);
    process.exit(1);
  }

  const models = [...provider.models].sort(compareVersionsDesc);

  console.log(`${provider.name || providerName} — ${models.length} models\n`);
  for (const model of models) {
    console.log(`  ${model}`);
  }
}

const args = process.argv.slice(2);

if (args.includes("--help") || args.length === 0) {
  printUsage();
  process.exit(0);
}

if (args.includes("--list")) {
  listProviders(loadRegistry());
  process.exit(0);
}

const providerIdx = args.indexOf("--provider");
if (providerIdx !== -1) {
  const name = args[providerIdx + 1];
  if (!name) {
    console.error("Error: --provider requires a provider name.");
    process.exit(1);
  }
  listModels(loadRegistry(), name);
  process.exit(0);
}

console.error("Error: Unknown arguments:", args.join(" "));
printUsage();
process.exit(1);

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

What our scanner noticed· Low risk

Instructions that use the network
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Mastra

Publisher

Mastra (Official)

Source

mastra-ai/skills · skills/mastra · commit 3020257

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by Mastra.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download mastra.zip