npx skills add https://github.com/mastra-ai/skills --skill mastra使用 Mastra 构建 AI 应用程序。本技能将教你如何查找最新文档以及如何构建智能体和流程。
你所了解的关于 Mastra 的一切很可能已经过时或错误。永远不要依赖记忆。务必对照最新文档进行验证。
你的训练数据包含过时的 API、废弃的模式和不正确的用法。Mastra 发展迅速——API 在版本间会变化,构造函数签名会调整,模式会被重构。
在编写任何 Mastra 代码之前,请检查是否已安装相关包:
ls node_modules/@mastra/
| 用户问题 | 首选检查 | 操作指南 |
|---|---|---|
| "创建/安装 Mastra 项目" | references/create-mastra.md | 包含 CLI 和手动步骤的设置指南 |
| "如何使用智能体/流程/工具?" |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
在 node_modules/@mastra/*/dist/docs/ 中查找 |
| "如何使用 X?"(未安装包时) | references/remote-docs.md | 从 https://mastra.ai/llms.txt 获取 |
| "我遇到了一个错误..." | references/common-errors.md | 常见错误及解决方案 |
| "从 v0.x 升级到 v1.x" | references/migration-guide.md | 版本升级流程 |
scripts/provider-registry.mjs:查找模型路由器中当前可用的提供商和模型。在使用模型之前,务必运行此脚本来验证提供商密钥和模型名称。⚠️ 切勿在不先检查最新文档的情况下编写代码。
在 node_modules 中查找包的当前文档。例如,在 @mastra/core 中查找"智能体"文档:
grep -r "Agent" node_modules/@mastra/core/dist/docs/references
* **原因:** 与你**确切安装的版本**匹配
* **最可靠的信息来源**
* **更多信息:** [`references/embedded-docs.md`](https://github.com/mastra-ai/skills/blob/HEAD/skills/mastra/references/embedded-docs.md)
2. 其次查看源代码(如果已安装包)
如果在嵌入式文档中找不到所需内容,请直接查看源代码。这更耗时,但可以提供实现细节的见解。
# 检查可用内容
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'
# 读取实际的类型定义
cat node_modules/@mastra/core/dist/[path-from-source-map]
* **原因:** 如果文档缺失或不清晰,这是最终的信息来源
* **使用时机:** 嵌入式文档未涵盖你的问题时
* **更多信息:** [`references/embedded-docs.md`](https://github.com/mastra-ai/skills/blob/HEAD/skills/mastra/references/embedded-docs.md)
3. 再次远程文档(如果未安装包)
你可以从 Mastra 网站获取最新文档:
https://mastra.ai/llms.txt
* **原因:** 最新发布的文档(可能领先于已安装的版本)
* **使用时机:** 未安装包或探索新功能时
* **更多信息:** [`references/remote-docs.md`](https://github.com/mastra-ai/skills/blob/HEAD/skills/mastra/references/remote-docs.md)
智能体:自主决策,使用工具。适用于:开放式任务(支持、研究、分析)
流程:结构化的步骤序列。适用于:定义明确的流程(管道、审批、ETL)
Studio 提供了一个交互式 UI,用于构建、测试和管理智能体、流程和工具。它有助于迭代式地调试和改进你的应用程序。
在 Mastra 项目内运行:
npm run dev
然后在浏览器中打开 http://localhost:4111 以访问 Mastra Studio。
Mastra 要求使用 ES2022 模块。CommonJS 将失败。
{
"compilerOptions": {
"target": "ES2022",
"module": "ES2022",
"moduleResolution": "bundler"
}
}
在使用 Mastra 的模型路由器定义模型时,始终使用 "提供商/模型名称" 格式。
使用提供商注册表脚本来查找可用的提供商和模型:
# 列出所有可用的提供商
node scripts/provider-registry.mjs --list
# 列出特定提供商的所有模型(按最新排序)
node scripts/provider-registry.mjs --provider openai
node scripts/provider-registry.mjs --provider anthropic
当用户要求使用某个模型或提供商时,务必先运行脚本以验证提供商密钥和模型名称是否有效。不要凭记忆猜测模型名称,因为它们经常变化。
模型字符串示例:
"openai/gpt-5.4""anthropic/claude-sonnet-4-5""google/gemini-2.5-pro"类型错误通常意味着你的知识已经过时。
知识过时的常见迹象:
类型 Y 上不存在属性 X找不到模块类型不匹配 错误应对措施:
references/common-errors.md编写代码前务必验证:
检查是否已安装包
ls node_modules/@mastra/
查找当前 API
references/embedded-docs.mdreferences/remote-docs.md基于当前文档编写代码
在 Studio 中测试
npm run dev # http://localhost:4111
references/create-mastra.mdreferences/embedded-docs.md - 如果已安装包,请从这里开始references/remote-docs.mdreferences/common-errors.mdreferences/migration-guide.md每周安装量
8.3K
代码仓库
GitHub 星标数
35
首次出现
2026年1月28日
安全审计
安装于
claude-code5.9K
cursor5.2K
codex4.5K
opencode4.4K
github-copilot4.1K
gemini-cli3.9K
Build AI applications with Mastra. This skill teaches you how to find current documentation and build agents and workflows.
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.
Before writing any Mastra code, check if packages are installed:
ls node_modules/@mastra/
| 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 |
scripts/provider-registry.mjs: Look up current providers and models available in the model router. Always run this before using a model to verify provider keys and model names.⚠️ Never write code without checking current docs first.
Look up current docs in node_modules for a package. Example of looking up "Agent" docs in @mastra/core:
grep -r "Agent" node_modules/@mastra/core/dist/docs/references
* **Why:** Matches your EXACT installed version
* **Most reliable source of truth**
* **More information:** [`references/embedded-docs.md`](https://github.com/mastra-ai/skills/blob/HEAD/skills/mastra/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.
# 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
* **More information:** [`references/embedded-docs.md`](https://github.com/mastra-ai/skills/blob/HEAD/skills/mastra/references/embedded-docs.md)
3. Remote docs third (if packages not installed)
You can fetch the latest docs from the Mastra website:
https://mastra.ai/llms.txt
* **Why:** Latest published docs (may be ahead of installed version)
* **Use when:** Packages not installed or exploring new features
* **More information:** [`references/remote-docs.md`](https://github.com/mastra-ai/skills/blob/HEAD/skills/mastra/references/remote-docs.md)
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)
Studio provides an interactive UI for building, testing, and managing agents, workflows, and tools. It helps with debugging and improving your applications iteratively.
Inside a Mastra project, run:
npm run dev
Then open http://localhost:4111 in your browser to access Mastra Studio.
Mastra requires ES2022 modules. CommonJS will fail.
{
"compilerOptions": {
"target": "ES2022",
"module": "ES2022",
"moduleResolution": "bundler"
}
}
Always use "provider/model-name" when defining models using Mastra's model router.
Use the provider registry script to look up available providers and models:
# List all available providers
node scripts/provider-registry.mjs --list
# List all models for a specific provider (sorted newest first)
node scripts/provider-registry.mjs --provider openai
node scripts/provider-registry.mjs --provider anthropic
When the user asks to use a model or provider, always run the script first to verify the provider key and model name are valid. Do not guess model names from memory as they change frequently.
Example model strings:
"openai/gpt-5.4""anthropic/claude-sonnet-4-5""google/gemini-2.5-pro"Type errors often mean your knowledge is outdated.
Common signs of outdated knowledge:
Property X does not exist on type YCannot find moduleType mismatch errorsWhat to do:
references/common-errors.mdAlways verify before writing code:
Check packages installed
ls node_modules/@mastra/
Look up current API
references/embedded-docs.mdreferences/remote-docs.mdWrite code based on current docs
Test in Studio
npm run dev # http://localhost:4111
references/create-mastra.mdreferences/embedded-docs.md - Start here if packages are installedreferences/remote-docs.mdreferences/common-errors.mdreferences/migration-guide.mdWeekly Installs
8.3K
Repository
GitHub Stars
35
First Seen
Jan 28, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
claude-code5.9K
cursor5.2K
codex4.5K
opencode4.4K
github-copilot4.1K
gemini-cli3.9K
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
102,200 周安装