--- title: "mastra-ai/skills" description: "Official agent skills for coding agents working with the Mastra AI framework" source: https://github.com/mastra-ai/skills ref: main license: null licenseName: "Other" canonical: https://skillsdocs.com/mastra-ai/skills base: https://github.com/mastra-ai/skills/blob/main/ provenance: authored chapters: 2 inlined: 2 withheld: 0 words: 1310 updated: 2026-09-24T12:43:11Z generator: "Skills Docs" --- > **mastra-ai/skills** — every Agent Skill in this repository, inlined verbatim. > > Canonical HTML: https://skillsdocs.com/mastra-ai/skills > Per-skill Markdown: https://skillsdocs.com/mastra-ai/skills/.md > Machine manifest: https://skillsdocs.com/mastra-ai/skills/.well-known/agent-skills/index.json > JSON: https://skillsdocs.com/api/v1/books/mastra-ai/skills > Install: `npx skills add mastra-ai/skills` > Upstream: https://github.com/mastra-ai/skills @ `main` > Licence: Other > > Content is mirrored from GitHub and © its authors, served unmodified. Takedown: https://github.com/DreambaseAI/skillsdocs/issues/new?labels=takedown&title=Takedown+request # mastra-ai/skills Official agent skills for coding agents working with the Mastra AI framework - **Skills:** 2 - **Inlined:** 2 (licence detected) - **Words:** 1,310 - **Reading time:** 6 min - **Stars:** 86 ## Table of contents 1. [mastra-factory](https://skillsdocs.com/mastra-ai/skills/mastra-factory.md) — Operate and supervise Mastra Factory through `mastra api factory`. Use for first-time Factory connection and login, status or queue summaries, project and work… 2. [mastra](https://skillsdocs.com/mastra-ai/skills/mastra.md) — Comprehensive Mastra framework guide for building agents, workflows, tools, memory, workspaces, and storage with current APIs. Use for documentation lookup, AP… ## Front matter _The repository README, verbatim except that relative links are resolved against https://github.com/mastra-ai/skills/blob/main/._ # Mastra Agent Skills Official Mastra skills for agents working with the [Mastra framework](https://mastra.ai). Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack. ## Installation ```bash npx skills add mastra-ai/skills ``` Mastra also supports the [`.well-known` skills discovery standard](https://github.com/cloudflare/agent-skills-discovery-rfc): ```bash npx skills add https://mastra.ai/ ``` ## Included skills ### mastra Single comprehensive skill for all Mastra development. Uses progressive disclosure with reference files covering: - **Setup & Installation** (`references/create-mastra.md`): CLI and manual project setup - **Embedded Docs Lookup** (`references/embedded-docs.md`): Find APIs in `node_modules/@mastra/*/dist/docs/` - **Remote Docs Lookup** (`references/remote-docs.md`): Fetch from `https://mastra.ai/llms.txt` - **Troubleshooting** (`references/common-errors.md`): Common errors and solutions - **Migrations** (`references/migration-guide.md`): Version upgrade workflows - **Mastra API CLI** (`references/mastra-api.md`): Inspect and call resources on local, platform, or remote servers - **Advanced Trace Queries** (`references/trace-query.md`): Select completed traces with recursive predicates and cursor pagination - **Trace Intelligence** (`references/trace-intelligence.md`): Query recurring themes across agent traces on the Mastra platform Main skill file teaches core concepts and routes to appropriate reference files based on user questions. ### mastra-factory Standalone Factory supervisor skill for coding agents using `mastra api factory`. Covers first-use CLI/login checks and URL-based connection from any directory, project and queue summaries, work-item session/thread and memory inspection, health interpretation, and user-authorized operations. - [Connection and installation](https://github.com/mastra-ai/skills/blob/main/skills/mastra-factory/references/connection.md): connect to your own deployment without a repository or project link file; choose the correct agent and installation scope. - [Session and memory inspection](https://github.com/mastra-ai/skills/blob/main/skills/mastra-factory/references/session-inspection.md): find your work, inspect progress and OM evidence, and distinguish findings from repair authorization. - [Supervisor commands](https://github.com/mastra-ai/skills/blob/main/skills/mastra-factory/references/factory-supervisor.md): contracts, output control, and safe mutations. Install just the Factory skill with interactive agent/scope selection: ```bash npx skills add mastra-ai/skills --skill mastra-factory ``` For a global install, specify your supported agent explicitly (`--agent -g`). PromptScript does not support global installation; use project scope for that agent instead, and confirm the skill is linked (a copied-but-"not linked" result means it is not active yet). Multi-agent installs can partially succeed: verify the intended agent with `npx skills list` (add `-g` for global scope) and confirm its skill references are present. ## Manual installation ```bash git clone https://github.com/mastra-ai/skills.git ``` Then configure your agent to load skills from the cloned directory. ## `.well-known` skills discovery This repository is served via the [RFC 8615 Well-Known URI](https://github.com/cloudflare/agent-skills-discovery-rfc) at `https://mastra.ai/.well-known/skills/`. Agents can discover available skills by fetching: - **Index**: `https://mastra.ai/.well-known/skills/index.json` - **Mastra skill**: `https://mastra.ai/.well-known/skills/mastra/SKILL.md` - **Factory skill**: `https://mastra.ai/.well-known/skills/mastra-factory/SKILL.md` This enables automatic skill discovery without manual configuration. ## Contributing Contributions welcome! 1. Fork the repository 2. Make improvements to `SKILL.md` files 3. Test with actual development workflows 4. Submit a pull request ## Resources - [Mastra Docs](https://mastra.ai/docs) - [Mastra GitHub](https://github.com/mastra-ai/mastra) - [Agent Skills Spec](https://agentskills.io) - [`.well-known` Skills RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) - [Discord](https://discord.gg/BTYqqHKUrf) ## License Apache-2.0 - See [LICENSE](https://github.com/mastra-ai/skills/blob/main/LICENSE) for details --- ## 1. mastra-factory - **Source:** https://github.com/mastra-ai/skills/blob/main/skills/mastra-factory/SKILL.md - **Raw:** https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra-factory/SKILL.md - **Markdown:** https://skillsdocs.com/mastra-ai/skills/mastra-factory.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (3), referenced from this skill's directory: - `references/connection.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra-factory/references/connection.md - `references/factory-supervisor.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra-factory/references/factory-supervisor.md - `references/session-inspection.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra-factory/references/session-inspection.md --- name: mastra-factory description: "Operate and supervise Mastra Factory through `mastra api factory`. Use for first-time Factory connection and login, status or queue summaries, project and work-item inspection, thread history and memory, metrics, health, decisions, attention, supervisor sessions, and user-authorized autonomous or interactive Factory operations on hosted, local, remote, or self-hosted servers." license: Apache-2.0 metadata: author: Mastra version: "1.0.0" repository: https://github.com/mastra-ai/skills --- # Mastra Factory Supervisor Use `mastra api factory` as the operational control plane for Factory. ## First use: connect before inspecting Read [`references/connection.md`](references/connection.md). Check CLI availability, establish the user's actual Factory URL, and for platform-hosted deployments run `mastra auth whoami`. If logged out, offer `mastra auth login` rather than silently starting browser login. Local/self-hosted authentication may differ. An explicit `mastra api --url "$FACTORY_URL" factory project list` works from an empty directory; no deployed repository or `.mastra-project.json` is required. Never assume a shared host, organization, project name, or ID. Preserve the explicit target on subsequent commands. ## Default behavior For status, inspection, diagnosis, queue review, or recommendation requests: 1. Stay read-only. 2. Select the sole or explicitly named project; report choices when ambiguous. 3. Inspect project state, work items, metrics, thresholds, decisions, attention, and supervisor health/session. 4. Correlate stages, revisions, sessions, decisions, and health findings. 5. Report active/queued work, blocked or unhealthy items, running sessions, pending decisions, human attention, and one recommended next action. 6. Execute a recommendation only when the current request or a previously granted operating scope authorizes it. ## Required reference Read [`references/factory-supervisor.md`](references/factory-supervisor.md) before running Factory commands for output control, contracts, the read-only workflow, mutation protocol, governance constraints, durable-session limitations, and error handling. For “my work,” actual execution progress, thread messages, memory, or health interpretation, also read [`references/session-inspection.md`](references/session-inspection.md). Distinguish card stages from running agents, historical messages from current memory, and agent claims from verified repository outcomes. ## Safety boundary - Never read or reveal `.env`, bearer tokens, saved login contents, or platform/provider credentials. - Never invent IDs, stages, revisions, request IDs, or sessions. - Establish the user's operating scope before mutating. Authorization may cover one action or grant standing autonomy over named projects, resources, action types, or objectives. - Within a clear delegated scope, act without asking for confirmation before every mutation. Ask only when an action is ambiguous, outside scope, or materially more destructive than the granted authority. - Fetch current state before a write, make the smallest in-scope change, then refetch and report IDs, revisions, and final state. - Use transitions—not metadata updates—for stage changes, with the current revision and a fresh UUID request ID. - Never use private HTTP routes to bypass unsupported CLI operations. - If `work-item start` lacks a supported durable user session, report the block; never substitute the supervisor session or invent a session UUID. --- ## 2. mastra - **Source:** https://github.com/mastra-ai/skills/blob/main/skills/mastra/SKILL.md - **Raw:** https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra/SKILL.md - **Markdown:** https://skillsdocs.com/mastra-ai/skills/mastra.md - **Licence:** Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html Bundled files (11), referenced from this skill's directory: - `references/common-errors.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra/references/common-errors.md - `references/core-concepts.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra/references/core-concepts.md - `references/create-mastra.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra/references/create-mastra.md - `references/embedded-docs.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra/references/embedded-docs.md - `references/mastra-api.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra/references/mastra-api.md - `references/migration-guide.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra/references/migration-guide.md - `references/model-selection.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra/references/model-selection.md - `references/remote-docs.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra/references/remote-docs.md - `references/trace-intelligence.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra/references/trace-intelligence.md - `references/trace-query.md` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra/references/trace-query.md - `scripts/provider-registry.mjs` — https://raw.githubusercontent.com/mastra-ai/skills/main/skills/mastra/scripts/provider-registry.mjs --- name: mastra description: "Comprehensive Mastra framework guide for building agents, workflows, tools, memory, workspaces, and storage with current APIs. Use for documentation lookup, API verification, TypeScript setup, common errors, migrations, and `mastra api` CLI tasks: inspect or call resources on local, Mastra platform, Trace Intelligence, or remote servers. For Mastra Factory operations, discover and activate the companion mastra-factory skill." license: Apache-2.0 metadata: author: Mastra version: "2.2.0" repository: https://github.com/mastra-ai/skills --- # 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 ## Resources ### References | 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 | | Choose Agent/Workflow/Tool/Memory/Storage | [`references/core-concepts.md`](references/core-concepts.md) | Core concepts and when to use each primitive | | 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` | | Choose or validate a model | [`references/model-selection.md`](references/model-selection.md) | Model format and provider registry lookup | | 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 | | Inspect/call server resources via CLI | [`references/mastra-api.md`](references/mastra-api.md) | `mastra api` CLI for local, Mastra platform, or remote servers | | Find exact traces with complex predicates | [`references/trace-query.md`](references/trace-query.md) | Query completed traces by trace fields or related spans, scores, and feedback | | Investigate agent health, recurring failures, or improvement opportunities | [`references/trace-intelligence.md`](references/trace-intelligence.md) | Start with aggregate Trace Intelligence themes, then inspect trace/log evidence | ### Scripts - `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. ## 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. This matches the exact installed version and is the most reliable source of truth. See [`references/embedded-docs.md`](references/embedded-docs.md). 2. Source code second (if packages installed) If embedded docs don't cover the question, inspect the installed source and type definitions. This is the source of truth when docs are missing or unclear. See [`references/embedded-docs.md`](references/embedded-docs.md). 3. Remote docs third (if packages not installed) Use the latest published docs when packages are not installed or when exploring new features. Remote docs may be ahead of the user's installed version. See [`references/remote-docs.md`](references/remote-docs.md). ## Core concepts Use [`references/core-concepts.md`](references/core-concepts.md) when choosing between agents, workflows, tools, memory, and storage. - Agent: Use for open-ended tasks that make decisions and use tools. - Workflow: Use for defined multi-step processes. ## Mastra Studio Studio is the interactive UI for building, testing, and managing agents, workflows, and tools. Use Studio when advising a human to inspect or debug visually. Inside a Mastra project, run: ```bash npm run dev ``` Then open `http://localhost:4111` in a browser to show Mastra Studio to your human user. ## Mastra API CLI Use `mastra api` to inspect or call resources on local dev servers, Mastra platform deployments, or remote Mastra endpoints. It is useful for agent-readable state, execution, traces, logs, scores, threads, and workflow operations. See [`references/mastra-api.md`](references/mastra-api.md) for usage patterns. For exact trace selection that needs recursive predicates or conditions over related spans, scores, or feedback, read [`references/trace-query.md`](references/trace-query.md). Before using `mastra api trace query`, confirm that the installed CLI exposes the command. Use `--schema` for the target's request/response shape and structural constraints, and use the canonical documentation found through [`references/remote-docs.md`](references/remote-docs.md) for supported fields, operators, and semantics. Preserve opaque pagination cursors and fetch trace or span details only after selecting candidates. ## Mastra Factory For Factory projects, work items, queue health, decisions, session history, memory inspection, or authorized operations, activate the **`mastra-factory`** skill. Factory is an operational control plane, not a reason to scaffold or deploy a new Mastra app. If the skill is missing, offer to install it from this repository: ```bash npx skills add mastra-ai/skills --skill mastra-factory ``` Choose the user's intended agent and scope interactively. For global installation, target a supported agent explicitly with `--agent -g`; PromptScript does not support global installs. Verify installation and referenced files for the intended agent even if another agent target fails. The Factory skill covers CLI checks, `mastra auth whoami` / authorized `mastra auth login`, and connecting via the user's actual instance URL from any directory. A deployed repository or `.mastra-project.json` is not required with `--url`. Never guess a shared Factory host or project IDs. Its connection and session-inspection references cover deployment-specific authentication, project discovery, threads, and observational memory limitations. ## Trace Intelligence Trace Intelligence (private beta on the Mastra platform) clusters completed agent traces into recurring themes across four trace signals: goal, outcome, behavior, and sentiment. Use it first for aggregate agent-health questions: what users ask for, where outcomes fail or get blocked, which behaviors recur, how sentiment shifts, and where the agent can improve. Then use `mastra api trace`, `log`, `metric`, and `score` commands for concrete execution evidence from specific traces. Query Trace Intelligence with `mastra api learning` CLI commands, or over HTTP via the local dev server proxy or the platform endpoint. See [`references/trace-intelligence.md`](references/trace-intelligence.md) for the investigation workflow, CLI commands, and route reference. ## Critical requirements ### TypeScript config Mastra requires ES2022 modules. CommonJS will fail. See [`references/create-mastra.md`](references/create-mastra.md) for setup and [`references/common-errors.md`](references/common-errors.md) for troubleshooting. ### Model format Always use `"provider/model-name"` when defining models using Mastra's model router. When the user asks to use a model or provider, always run `scripts/provider-registry.mjs` first to verify the provider key and model name are valid. Do not guess model names from memory as they change frequently. See [`references/model-selection.md`](references/model-selection.md). ## When you see errors Type errors often mean your knowledge is outdated. Common signs of outdated knowledge: - `Property X does not exist on type Y` - `Cannot find module` - `Type mismatch` errors - Constructor parameter errors What to do: 1. Check [`references/common-errors.md`](references/common-errors.md) 2. Verify current API in embedded docs 3. Don't assume the error is a user mistake - it might be your outdated knowledge ## Development workflow Always verify before writing code: 1. Check whether Mastra packages are installed 2. Look up current API - If installed: Use embedded docs [`references/embedded-docs.md`](references/embedded-docs.md) - If not: Use remote docs [`references/remote-docs.md`](references/remote-docs.md) 3. Write code based on current docs 4. Test with the project scripts or Studio when available