Expert Mastra framework assistant for designing architectures, analyzing projects, debugging issues, and building AI agents and workflows.
This plugin gives Claude deep expertise in the Mastra AI framework, enabling it to:
- Design complete architectures from a problem description, with full TypeScript implementation
- Analyze existing projects for bugs, issues, gaps, and improvements — with detailed reports
- Brainstorm solutions interactively, producing reports with task breakdowns
- Scaffold new components (agents, workflows, tools, networks, full projects)
- Migrate between versions with automated change detection and step-by-step plans
- Debug errors by diagnosing root causes against current API documentation
All commands verify APIs against the official Mastra skill and embedded docs in node_modules/@mastra/*/dist/docs/, ensuring generated code matches your installed version.
The official Mastra framework skill (v2.0.0, Apache-2.0). Teaches how to find current documentation, verify API signatures, and build agents and workflows. Covers documentation lookup strategies, core concepts (agents vs workflows, tools, memory, RAG), TypeScript requirements, and common patterns. Includes reference files:
embedded-docs.md— How to look up APIs from installed packages innode_modules/@mastra/*/dist/docs/remote-docs.md— How to fetch latest docs fromhttps://mastra.ai/llms.txtcreate-mastra.md— Complete project creation guide (CLI + manual 9-step setup)common-errors.md— Comprehensive error and troubleshooting guidemigration-guide.md— Version upgrade workflows with pre/post checklists
Domain-agnostic expertise in designing effective AI agent systems. Covers writing agent instructions (prompt engineering), tool design principles, model selection and cost optimization, evaluation strategies, and guardrails. Includes reference files:
tool-design-patterns.md— Read-before-write, pagination, confirmation, composite results, error patternsinstruction-templates.md— Starter templates for support, research, analysis, code review, and orchestrator agents
Advanced Zod schema patterns specifically for Mastra development. Covers self-documenting schemas, constraint patterns, schema composition and reuse, discriminated unions for branching, transforms, refinements, and recursive schemas. Includes:
workflow-schema-patterns.md— Step chain alignment, branch schemas, parallel step schemas, state patterns
Testing strategies at every level of the Mastra testing pyramid. Covers schema validation tests, tool unit tests, workflow tests (including suspend/resume and state), agent integration tests, eval suites with scorers, and Studio testing. Includes:
test-templates.md— Copy-paste templates for tool, agent, workflow, eval suite, and network tests
| Command | Description |
|---|---|
/mastra-design |
Design a complete Mastra architecture for a given problem, with full implementation code |
/mastra-analyze |
Analyze a project for bugs and improvements; produces a detailed report with prioritized task breakdown |
/mastra-brainstorm |
Interactive research session; produces a brainstorm report with recommended direction and next steps |
/mastra-scaffold |
Generate boilerplate for a project, agent, workflow, tool, or agent network |
/mastra-migrate |
Plan and execute migration to a newer Mastra version with breaking change analysis |
/mastra-debug |
Diagnose and fix a specific Mastra error, with root cause analysis |
Automated checks that run before and after Claude's tool calls to catch common Mastra mistakes in real time. Configured in hooks/hooks.json.
Pre-tool checks (run before Bash commands):
| Hook | What it does |
|---|---|
migration-safety-gate |
Blocks package upgrades when there are uncommitted changes, ensuring safe rollback |
check-env-vars |
Verifies required environment variables (API keys, database URLs) are set before running Mastra commands |
check-db-connectivity |
Tests PostgreSQL connectivity before dev/test commands if the project uses PostgresStore |
Post-tool checks (run after file writes and edits):
| Hook | What it does |
|---|---|
check-workflow-commit |
Warns if workflows are missing .commit() calls |
check-model-format |
Validates model strings use provider/model-name format (e.g., anthropic/claude-sonnet-4-5-20250514) |
check-tsconfig |
Verifies tsconfig.json has ES2022 target/module and bundler moduleResolution |
check-package-module |
Ensures package.json includes "type": "module" when using @mastra packages |
check-zod-describe |
Warns when Zod schema fields in tool definitions lack .describe() annotations |
check-mastra-imports |
Verifies imported @mastra symbols exist in the installed version |
detect-deprecated-patterns |
Flags deprecated API patterns like old import paths or renamed functions |
check-import-paths |
Validates that @mastra import subpaths are actually exported by installed packages |
suggest-tests |
Suggests creating test files when new agents, tools, or workflows are written |
suggest-studio |
Reminds about Mastra Studio for interactive testing when components are created |
Post-tool checks (run after Bash commands):
| Hook | What it does |
|---|---|
check-mastra-versions |
Detects version mismatches across installed @mastra packages |
match-error-patterns |
Analyzes command failures and surfaces targeted solutions for common Mastra errors |
suggest-debug-logging |
Recommends enabling verbose logging when commands fail with unclear errors |
A prompt hook also runs after workflow files are written, asking Claude to verify that output schemas align with input schemas across .then() step chains.
/mastra-design Build a customer support system with ticket routing, FAQ lookup, and escalation to humans
/mastra-analyze ./my-mastra-project
/mastra-brainstorm How should I add RAG-based document search to my existing agent?
/mastra-scaffold agent email-assistant
/mastra-scaffold workflow data-pipeline
/mastra-scaffold project my-ai-app
/mastra-migrate latest
/mastra-debug Cannot read property 'then' of undefined in my workflow
No additional configuration required. The official Mastra skill is bundled with this plugin.
For the best experience, ensure your Mastra packages are installed locally so the skill can access embedded documentation that exactly matches your installed package versions.