Mastra Skills

Core principle: Build composable, observable, and testable AI agents.

When to Use This Skill

Always use when:

• Creating new Mastra agents
• Implementing agent tools
• Setting up workflows
• Debugging agent behavior
• Integrating external APIs with agents

Don't use for:

• Non-agent-related code
• Pure frontend components without agent interaction

Documentation Quick Links

• reference.md - Official API documentation links
• examples.md - Official examples and how to use them
• Official Mastra Docs - https://mastra.ai/docs/

Development Checklist

When creating a new agent, use TodoWrite to track:

• Define clear agent purpose and capabilities
• Identify required tools and integrations
• Plan observability and logging strategy
• Design agent memory and state management
• Consider error handling and fallbacks
• Write tests for key scenarios

Essential Requirements

Every Agent Must Have

1. Clear purpose and instructions - Specific, not generic
2. Descriptive name - Not 'agent1' or 'myAgent'
3. Appropriate model selection - Choose based on task complexity
4. Explicit tool registration - No implicit assumptions

Every Tool Must Have

1. Descriptive ID - Clear what it does
2. Clear description - For the LLM to understand
3. Zod schema validation - Type-safe inputs
4. Error handling - Never let tools crash agents
5. Logging - For debugging and observability

Every Workflow Must Have

1. Clear trigger schema - Validated inputs
2. Proper step sequencing - Sequential vs parallel
3. Error handling - In each step
4. Observability hooks - beforeAll/afterAll for logging

Core Patterns

Basic Agent

import { Agent } from '@mastra/core';

const agent = new Agent({
  name: 'descriptive-name',
  instructions: 'Clear, specific instructions',
  model: {
    provider: 'ANTHROPIC',
    name: 'claude-sonnet-4-5',
  },
  tools: { /* ... */ },
});

📚 More details: reference.md | https://mastra.ai/docs/agents/

Basic Tool

import { z } from 'zod';

const tool = {
  id: 'descriptive-id',
  description: 'What this tool does',
  inputSchema: z.object({
    param: z.string().describe('Parameter description'),
  }),
  execute: async ({ context }) => {
    try {
      const result = await operation();
      return { success: true, data: result };
    } catch (error) {
      logger.error('Operation failed', { error, context });
      return { success: false, error: error.message };
    }
  },
};

📚 More examples: examples.md | https://mastra.ai/docs/tools/

Basic Workflow

import { Workflow } from '@mastra/core';

const workflow = new Workflow({
  name: 'workflow-name',
  triggerSchema: z.object({ input: z.string() }),
});

workflow
  .step({ id: 'step1', execute: async () => { /* ... */ } })
  .then({ id: 'step2', execute: async () => { /* ... */ } })
  .commit();

📚 More examples: examples.md | https://mastra.ai/docs/workflows/

Red Flags - Stop If You See

• Agent without clear purpose
• Tools without input validation
• No error handling in tools
• Missing observability/logging
• Hardcoded credentials
• No rate limiting for external APIs
• Unbounded memory growth

Common Rationalizations

Excuse	Reality
"Agent instructions don't need to be specific"	Vague instructions → unpredictable behavior
"Error handling adds complexity"	Unhandled errors → crashed agents
"We can add observability later"	Can't debug what you can't observe
"Tool schemas are optional"	Invalid inputs → runtime failures

Integration Checklist

When integrating external services, use TodoWrite to track:

• Create typed tool interface
• Add input validation with Zod
• Implement error handling
• Add logging for debugging
• Consider rate limiting
• Handle authentication securely
• Test with edge cases
• Document tool usage

Testing Requirements

// Unit test for tools
describe('myTool', () => {
  it('should handle valid input', async () => {
    const result = await myTool.execute({
      context: { param: 'test' },
      mastra: mockMastra,
    });
    expect(result.success).toBe(true);
  });
});

// Integration test for agents
describe('myAgent', () => {
  it('should respond to queries', async () => {
    const response = await myAgent.generate([
      { role: 'user', content: 'test query' }
    ]);
    expect(response.role).toBe('assistant');
  });
});

📚 More examples: examples.md

Quick Workflow

1. Need API details? → Check reference.md
2. Need examples? → Check examples.md
3. Building something? → Follow checklists above, use TodoWrite
4. Stuck? → Check official docs at https://mastra.ai/docs/

Final Rule

Every agent must have:
1. Clear purpose and instructions
2. Type-safe tools with validation
3. Error handling and observability
4. Tests covering key scenarios

Follow these principles for reliable, maintainable Mastra agents.