Generic “build an agent” with no Mastra imports → mde-agents or product docs, not framework internals here
CopilotKit v2 (useComponent, slots, headless v2) → defer for mdeapp; use copilotkit-integrations + references/copilotkit.md only for separate-server pattern
Build AI applications with Mastra. This skill teaches you how to find current documentation and build agents and workflows.
Mastra orchestrates batch ingest;searchEventsTool queries approved events only. Verify APIs via Mastra docs MCP before new workflow steps.
⚠️ 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)
Reference index:references/README.md — every references/*.md file has YAML frontmatter (title, description, parent: mastra). Load one ref per task.
Topic routing:references/topic-routing.md — maps tasks (agents, workflows, MCP, deployment, …) to the right links.md section and optional local references/*.md files.
Use mastra-docs when embedded package docs are missing or sparse and you need official, current Mastra documentation. For application code that connects an agent to external MCP tools, follow the official MCP overview: https://mastra.ai/docs/mcp/overview#using-mcpclient-with-an-agent.
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. Example of looking up "Agent" docs in @mastra/core:
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 availablecat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'# Read the actual type definitioncat node_modules/@mastra/core/dist/[path-from-source-map]
Why: Ultimate source of truth if docs are missing or unclear
Studio provides an interactive UI for building, testing, and managing agents, workflows, and tools. It helps with debugging and improving your applications iteratively.
Inside a Mastra project, run:
npm run dev
Then open http://localhost:4111 in your browser to access Mastra Studio.
Critical requirements
TypeScript config
Mastra requires ES2022 modules. CommonJS will fail.
Always use "provider/model-name" when defining models using Mastra's model router.
Use the provider registry script to look up available providers and models:
# List all available providers
node scripts/provider-registry.mjs --list
# List all models for a specific provider (sorted newest first)
node scripts/provider-registry.mjs --provider openai
node scripts/provider-registry.mjs --provider anthropic
When the user asks to use a model or provider, always run the script first to verify the provider key and model name are valid. Do not guess model names from memory as they change frequently.
Example model strings:
"openai/gpt-5.4"
"anthropic/claude-sonnet-4-5"
"google/gemini-2.5-pro"
When you see errors
Type errors often mean your knowledge is outdated.
