mastra

Files (6)

• SKILL.md
• common-errors.md · references/
• create-mastra.md · references/
• embedded-docs.md · references/
• migration-guide.md · references/
• remote-docs.md · references/

SKILL.md (first lines)

# 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:

```bash
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`](references/create-mastra.md)     | Setup guide with CLI and manual steps          |
| "How do I use Agent/Workflow/Tool?" | [`references/embedded-docs.md`](references/embedded-docs.md)     | Look up in `node_modules/@mastra/*/dist/docs/` |
| "How do I use X?" (no packages)     | [`references/remote-docs.md`](references/remote-docs.md)         | Fetch from `https://mastra.ai/llms.txt`        |
| "I'm getting an error..."           | [`references/common-errors.md`](references/common-errors.md)     | Common errors and solutions                    |
| "Upgrade from v0.x to v1.x"         | [`references/migration-guide.md`](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`:

   ```bash
   grep -r "Agent" node_modules/@mastra/core/dist/docs/references
   ```

   - **Why:** Matches your EXACT installed version
   - **Most reliable source of truth**
   - **See:** [`references/embedded-docs.md`](references/embedded-docs.md)

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.

   ```bash
   # 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`](references/embedded-docs.md)

3. **Remote docs third** (if packages not installed)

   You can fetch the latest docs from the Mastra website:

   ```bash
   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`](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.

```json
{
  "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

From IkramBagban/helmsman, Apache-2.0.

More from IkramBagban/helmsman