Mastra Best Practices

What it does

This skill provides a quick reference guide for adhering to Mastra conventions, a framework for building AI agents and workflows. It outlines essential configurations, project structure guidelines, and coding practices to ensure tasks align with industry best practices, optimizing quality and efficiency. The full documentation can be found at mastra.ai/docs.

When to use it

This skill is helpful when:

• You are starting a new Mastra agent or workflow development project.
• You need a reminder of key Mastra conventions and coding standards.
• You're troubleshooting issues related to module resolution (specifically avoiding CommonJS).
• You want to understand the difference between using an Agent versus a Workflow within the Mastra framework.

Key capabilities

• Agent Creation: Provides code snippets for creating basic agents with configurations like ID, name, instructions, and model selection.
• Workflow Definition: Demonstrates how to define workflows with input/output schemas.
• Structured Output Handling: Shows how to use structured output with a defined schema (using z objects).
• Streaming Support: Includes an example of streaming responses from an agent.
• Environment Variable Usage: Emphasizes the importance of using environment variables for API keys.
• Module System Requirements: Specifies that ES2022 modules are required, and CommonJS is not supported.

Example prompts

Here are some examples of how you might use this skill:

• "Show me an example of creating a basic Mastra agent."
• "What's the recommended project structure for a Mastra project?"
• "How do I define a workflow with input and output schemas in Mastra?"
• "Remind me how to use structured output in Mastra."

Tips & gotchas

• Module Resolution: Ensure you are using ES2022 modules; CommonJS will cause errors.
• API Keys: Always store your API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY) in environment variables.
• Accessing Agent/Workflow Instances: Use mastra.getAgent('name') and mastra.getWorkflow('name') instead of direct imports.