mastra-ai avatar
32

This skill provides guidance on building AI applications with the Mastra framework, emphasizing the use of documentation and workflows for development. It covers key concepts such as agents, workflows, tools, and memory, while highlighting the importance of verifying current documentation due to rapid API changes. Suitable for developers working with Mastra, it offers resources for setup, troubleshooting, and staying updated with the latest API information.

npx skills add https://github.com/mastra-ai/skills --skill 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

Documentation lookup guide

Quick Reference

User Question First Check How To "Create/install Mastra project" references/create-mastra.md Setup guide with CLI and manual steps "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 "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

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. Example of looking up "Agent" docs in @mastra/core: 
    grep -r "Agent" node_modules/@mastra/core/dist/docs/references
  2. Source code second (if packages installed) 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. 
    # Check what's available
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'
# Read the actual type definition
cat node_modules/@mastra/core/dist/[path-from-source-map]
    • Why: Ultimate source of truth if docs are missing or unclear
    • Use when: Embedded docs don't cover your question
    • See: references/embedded-docs.md
  3. Remote docs third (if packages not installed) You can fetch the latest docs from the Mastra website: 
    https://mastra.ai/llms.txt
    • Why: Latest published docs (may be ahead of installed version)
    • Use when: Packages not installed or exploring new features
    • See: references/remote-docs.md

Core concepts

Agents vs workflows

Agent: Autonomous, makes decisions, uses tools Use for: Open-ended tasks (support, research, analysis) Workflow: Structured sequence of steps Use for: Defined processes (pipelines, approvals, ETL)

Key components

  • Tools: Extend agent capabilities (APIs, databases, external services)
  • Memory: Maintain context (message history, working memory, semantic recall)
  • RAG: Query external knowledge (vector stores, graph relationships)
  • Storage: Persist data (Postgres, LibSQL, MongoDB)

Critical requirements

TypeScript config

Mastra requires ES2022 modules. CommonJS will fail.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler"
  }
}

Model format

Always use "provider/model-name":

  • "openai/gpt-5.2"
  • "anthropic/claude-sonnet-4-5"
  • "google/gemini-2.5-pro"

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:
  1. Check references/common-errors.md
  2. Verify current API in embedded docs
  3. Don't assume the error is a user mistake - it might be your outdated knowledge

Development workflow

Always verify before writing code:

  1. Check packages installed 
    ls node_modules/@mastra/
  2. Look up current API
  3. Write code based on current docs
  4. Test in Studio 
    npm run dev  # http://localhost:4111

Resources

GitHub Owner

Owner: mastra-ai

GitHub Links

Files

create-mastra.md

embedded-docs.md

remote-docs.md

common-errors.md

migration-guide.md

embedded-docs.md

embedded-docs.md

remote-docs.md

common-errors.md

embedded-docs.md

remote-docs.md

create-mastra.md

embedded-docs.md

remote-docs.md

common-errors.md

migration-guide.md

SKILL.md

name: mastra description: "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." license: Apache-2.0 metadata: author: Mastra version: "2.0.0" repository: https://github.com/mastra-ai/skills

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

Documentation lookup guide

Quick Reference

User QuestionFirst CheckHow To
"Create/install Mastra project"references/create-mastra.mdSetup guide with CLI and manual steps
"How do I use Agent/Workflow/Tool?"references/embedded-docs.mdLook up in node_modules/@mastra/*/dist/docs/
"How do I use X?" (no packages)references/remote-docs.mdFetch from https://mastra.ai/llms.txt
"I'm getting an error..."references/common-errors.mdCommon errors and solutions
"Upgrade from v0.x to v1.x"references/migration-guide.mdVersion upgrade workflows

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. Example of looking up "Agent" docs in @mastra/core: 
    grep -r "Agent" node_modules/@mastra/core/dist/docs/references
  2. Source code second (if packages installed) 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. 
    # Check what's available
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'
# Read the actual type definition
cat node_modules/@mastra/core/dist/[path-from-source-map]
    • Why: Ultimate source of truth if docs are missing or unclear
    • Use when: Embedded docs don't cover your question
    • See: references/embedded-docs.md
  3. Remote docs third (if packages not installed) You can fetch the latest docs from the Mastra website: 
    https://mastra.ai/llms.txt
    • Why: Latest published docs (may be ahead of installed version)
    • Use when: Packages not installed or exploring new features
    • See: references/remote-docs.md

Core concepts

Agents vs workflows

Agent: Autonomous, makes decisions, uses tools Use for: Open-ended tasks (support, research, analysis) Workflow: Structured sequence of steps Use for: Defined processes (pipelines, approvals, ETL)

Key components

  • Tools: Extend agent capabilities (APIs, databases, external services)
  • Memory: Maintain context (message history, working memory, semantic recall)
  • RAG: Query external knowledge (vector stores, graph relationships)
  • Storage: Persist data (Postgres, LibSQL, MongoDB)

Critical requirements

TypeScript config

Mastra requires ES2022 modules. CommonJS will fail.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler"
  }
}

Model format

Always use "provider/model-name":

  • "openai/gpt-5.2"
  • "anthropic/claude-sonnet-4-5"
  • "google/gemini-2.5-pro"

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:
  1. Check references/common-errors.md
  2. Verify current API in embedded docs
  3. Don't assume the error is a user mistake - it might be your outdated knowledge

Development workflow

Always verify before writing code:

  1. Check packages installed 
    ls node_modules/@mastra/
  2. Look up current API
  3. Write code based on current docs
  4. Test in Studio 
    npm run dev  # http://localhost:4111

Resources

More skills

BU
Browser Use

browser-use

V
Turborepo

vercel

G
Web Coder

github