npx skills add ...
npx skills add mastra-ai/mastra --skill smoke-test
npx skills add mastra-ai/mastra --skill smoke-test
Create a Mastra project using create-mastra and smoke test the studio in Chrome using Chrome MCP server
Creates a new Mastra project using create-mastra@<tag> and performs smoke testing of the Mastra Studio in Chrome.
This skill is for Claude Code with Chrome MCP server. For MastraCode with built-in browser tools, use mastracode-smoke-test instead.
| Parameter | Short | Description | Required | Default |
|---|---|---|---|---|
--directory | -d | Parent directory where project will be created | Yes | - |
--name | -n | Project name (will be created as subdirectory) | Yes | - |
--tag | -t | Version tag for create-mastra (e.g., latest, alpha, 0.10.6) | Yes | - |
--pm | -p | Package manager: npm, yarn, pnpm, or bun | No | npm |
--llm | -l | LLM provider: openai, anthropic, groq, google, cerebras, mistral | No | openai |
CRITICAL: Before proceeding, parse the ARGUMENTS and validate:
--directory or -d: REQUIRED - fail if missing--name or -n: REQUIRED - fail if missing--tag or -t: REQUIRED - fail if missing--pm or -p: Default to npm if not provided--llm or -l: Default to openai if not providedpm must be one of: npm, yarn, pnpm, bunllm must be one of: openai, anthropic, groq, google, cerebras, mistraldirectory must exist (or will be created)name should be a valid directory name (no spaces, special chars)If validation fails: Stop and show usage help with the missing/invalid parameters.
If -h or --help is passed: Show this usage information and stop.
This skill requires the Chrome MCP server (Claude-in-Chrome) for browser automation. Ensure it's configured and running.
The Chrome MCP server provides tools like tabs_create_mcp, tabs_context_mcp, navigate_mcp, click_mcp, type_mcp, and screenshot_mcp.
Run the create-mastra command with explicit parameters to avoid interactive prompts:
Flags explained:
-c agents,tools,workflows,scorers - Include all components-l <provider> - Set the LLM provider-e - Include example codeBeing explicit with all parameters ensures the CLI runs non-interactively.
Wait for the installation to complete. This may take 1-2 minutes depending on network speed.
After creation, verify the project has:
package.json with mastra dependenciessrc/mastra/index.ts exporting a Mastra instance.env file (may need to be created)To test browser functionality, add a browser-enabled agent:
src/mastra/agents/:Based on the selected LLM provider, check for the required API key:
| Provider | Required Environment Variable |
|---|---|
| openai | OPENAI_API_KEY |
| anthropic | ANTHROPIC_API_KEY |
| groq | GROQ_API_KEY |
GOOGLE_GENERATIVE_AI_API_KEY | |
| cerebras | CEREBRAS_API_KEY |
| mistral | MISTRAL_API_KEY |
Check in this order:
Check global environment first: Run echo $<ENV_VAR_NAME> to see if the key is already set globally
.env file neededCheck project .env file: If not set globally, check if .env exists in the project and contains the key
Ask user only if needed: If the key is not available globally or in .env:
.env file with the provided keyOnly check for the ONE key matching the selected provider - don't check for all providers.
Navigate to the project directory and start the dev server:
The server typically starts on http://localhost:4111. Wait for the server to be ready before proceeding.
Use the Chrome browser automation tools to test the Mastra Studio.
tabs_context_mcptabs_create_mcphttp://localhost:4111Perform the following smoke tests using the Chrome automation tools:
Navigation & Basic Loading
Agents Page (/agents)
--default)Agent Detail (/agents/<agentId>/chat)
Agent Chat
Browser Agent (/agents/browser-agent/chat) - if browser agent was added
Tools Page (/tools)
Tool Execution (/tools/get-weather)
Workflows Page (/workflows)
Workflow Execution (/workflows/weather-workflow)
Settings Page (/settings)
Observability Page (/observability)
Scorers Page (/evaluation?tab=scorers)
/evaluation?tab=scorers (NOT /scorers - that route doesn't exist)Additional Pages (verify load only)
/templates) - Gallery of starter templates/request-context) - JSON editor/processors) - Empty state OK/mcps) - Empty state OKAfter completing all tests, provide a summary:
| Step | Action |
|---|---|
| Create Project | cd <directory> && npx create-mastra@<tag> <name> -c agents,tools,workflows,scorers -l <provider> -e |
| Install Deps | Automatic during creation |
| Set Env Vars | Check global env first, then .env, ask user only if needed |
| Start Server | cd <directory>/<name> && npm run dev |
| Studio URL | http://localhost:4111 |
Server won't start
.env has required API key<pm> install to reinstall dependenciesBrowser can't connect
Agent chat fails
Browser agent fails
pnpm exec playwright install chromium| Feature | Route |
|---|---|
| Agents | /agents |
| Workflows | /workflows |
| Tools | /tools |
| Evaluation | /evaluation |
| Scorers | /evaluation?tab=scorers |
| Observability | /observability/traces |
| Logs | /observability/logs |
| MCP Servers | /mcps |
| Processors | /processors |
| Templates | /templates |
| Request Context | /request-context |
| Settings | /settings |
-e flag includes example agents, making smoke testing meaningful-c, -l, -e) to ensure non-interactive execution# For npm
npx create-mastra@<tag> <project-name> -c agents,tools,workflows,scorers -l <llmProvider> -e
# For yarn
yarn create mastra@<tag> <project-name> -c agents,tools,workflows,scorers -l <llmProvider> -e
# For pnpm
pnpm create mastra@<tag> <project-name> -c agents,tools,workflows,scorers -l <llmProvider> -e
# For bun
bunx create-mastra@<tag> <project-name> -c agents,tools,workflows,scorers -l <llmProvider> -e<pm> add @mastra/stagehand
# or for deterministic browser automation:
<pm> add @mastra/agent-browserimport { Agent } from '@mastra/core/agent';
import { Memory } from '@mastra/memory';
import { StagehandBrowser } from '@mastra/stagehand';
export const browserAgent = new Agent({
id: 'browser-agent',
name: 'Browser Agent',
instructions: `You are a helpful assistant that can browse the web to find information.`,
model: '<provider>/<model>', // e.g., 'openai/gpt-4o'
memory: new Memory(),
browser: new StagehandBrowser({
headless: false,
}),
});import { browserAgent } from './agents/browser-agent';
// In Mastra config:
agents: { weatherAgent, browserAgent },cd <directory>/<project-name>
<packageManager> run dev