mastra-ai/mastra-observational-memory-workshop/mastra
Claude Code and agent skill by mastra-ai/mastra-observational-memory-workshop
- community
Checking that the SKILL.md file is still in the repository.
Comprehensive Mastra framework guide. Teaches how to find current documentation, verify API signatures, and build agents and workflows. Covers documentation lookup strategies (embedded docs, remote docs), core concepts (agents vs workflows, tools, memory, RAG), TypeScript requirements, and common patterns. Use this skill for all Mastra development to ensure you're using current APIs from the installed version or latest documentation.
Install
npx vskill@latest install mastra-ai/mastra-observational-memory-workshop/mastraSKILL.md
The same SKILL.md was published earlier as comeonoliver/skillshub/mastra.
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:
- 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` | Setup guide with CLI and manual steps | |
| "How do I use Agent/Workflow/Tool?" | `references/embedded-docs.md` | Look up in node_modules/@mastra/*/dist/docs/ | |
| "How do I use X?" (no packages) | `references/remote-docs.md` | Fetch from https://mastra.ai/llms.txt | |
| "I'm getting an error..." | `references/common-errors.md` | Common errors and solutions | |
| "Upgrade from v0.x to v1.x" | `references/migration-guide.md` | Version upgrade workflows |
Priority order for writing code
⚠️ Never write code without checking current docs first
- Embedded docs first (if packages installed)
```bash # Check what's available cat node_modules/@mastra/core/dist/docs/SOURCE_MAP.json | grep '"Agent"'
# Read the actual type definition cat node_modules/@mastra/core/dist/[path-from-source-map] ```
- Why: Matches your EXACT installed version
- Most reliable source of truth
- See: `references/embedded-docs.md`
- Remote docs second (if packages not installed)
``bash # Fetch latest docs # 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`
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.
Model format
Always use "provider/model-name":
"openai/gpt-4o""anthropic/claude-3-5-sonnet-20241022""google/gemini-2.5-pro"
When you see errors
Type errors often mean your knowledge is outdated.
Common signs of outdated knowledge:
Property X does not exist on type YCannot find moduleType mismatcherrors- Constructor parameter errors
What to do:
- Check `references/common-errors.md`
- Verify current API in embedded docs
- Don't assume the error is a user mistake - it might be your outdated knowledge
Development workflow
Always verify before writing code:
- Check packages installed
``bash ls node_modules/@mastra/ ``
- Look up current API
- If installed → Use embedded docs `references/embedded-docs.md`
- If not → Use remote docs `references/remote-docs.md`
- Write code based on current docs
- Test in Studio
``bash npm run dev # http://localhost:4111 ``
Resources
- Setup: `references/create-mastra.md`
- Embedded docs lookup: `references/embedded-docs.md` - Start here if packages are installed
- Remote docs lookup: `references/remote-docs.md`
- Common errors: `references/common-errors.md`
- Migrations: `references/migration-guide.md`
- Official site: https://mastra.ai (verify against embedded docs first)
Security
- Security scanPassed, 90 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingexamples/00-personal-assistant-agent/.agents/skills/mastra/SKILL.md
Popularity
- 7-day trend score
- 0
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/mastra-ai/mastra-observational-memory-workshop/mastra)