name: mastra-system-check
description: >
Comprehensive system check for Mastra AI agent projects. Validates configuration,
agents, workflows, memory, tools, prompts, and security across 66 rules organized
by priority. Use when setting up new projects, debugging issues, reviewing code,
or preparing for production deployment.
license: MIT
metadata:
author: stan
x: "https://x.com/goldkey"
version: "1.1.0"

Mastra System Check

Validates Mastra AI agent projects with 66 checks across 10 categories.
Finds configuration errors, missing best practices, and potential issues before they cause problems.

Trigger Keywords

Activate this skill when the user mentions:

Quick Checks (Run First)

Before deep analysis, verify these 4 common issues that cause most failures:

1. Storage Configured?

grep "storage:" src/mastra/index.ts

If missing → Add storage: new LibSQLStore({ url: "file:./mastra.db" })

2. API Keys Set?

cat .env | grep -E "(OPENAI|ANTHROPIC|GOOGLE)_API_KEY"

If missing → Add the required API key for the model provider being used

3. Model Format Correct?

grep -r "model:" src/mastra/ | grep -v "provider/"

All models must use provider/model-name format (e.g., openai/gpt-4o)

4. Workflows Committed?

grep -r "new Workflow" src/mastra/ -A 20 | grep "\.commit()"

Every workflow chain must end with .commit()

If any quick check fails, fix it before proceeding with full analysis.

Execution Steps

When this skill activates, follow these steps IN ORDER:

Step 1: Locate Entry Point

# Find the main Mastra instance
cat src/mastra/index.ts

Verify: Named export mastra exists with proper configuration.

Step 2: Check Dependencies

# Verify required packages
cat package.json | grep -E "@mastra|zod|@ai-sdk"

Required: @mastra/core. Check Zod is v4+ for schema compatibility.

Step 3: Scan for Agents

grep -rn "new Agent" src/

For each agent found, check: id, model format, instructions, tools, memory.

Step 4: Scan for Workflows

grep -rn "new Workflow" src/

For each workflow, check: .commit() called, steps connected, schemas defined.

Step 5: Check Configuration Files

• .env / .env.local → API keys present
• tsconfig.json → Module ES2022+, moduleResolution bundler/node16

Step 6: Run Category Checks

Apply rules from AGENTS.md in this priority order:
1. 🔴 CRITICAL (config-) - Fix immediately
2. 🟠 HIGH (agent-, workflow-, context-, prompt-) - Fix before deployment
3. 🟡 MEDIUM (memory-, tool-, security-) - Fix when possible
4. 🟢 LOW (optimization-*) - Nice to have

Step 7: Report Findings

Present issues sorted by priority with specific file locations and fixes.

File Patterns to Check

Priority Legend

Check Categories Summary

Total: 66 rules across 10 categories

*Observability checks are conditional - only apply if telemetry/evals are configured.

Output Format

For each issue found, report in this format:

### 🔴 CRITICAL Issues (count)

**[rule-id] Rule Name**
- **Location:** `file/path.ts:lineNumber`
- **Issue:** Clear description of what's wrong
- **Fix:**
  ```typescript
  // Corrected code example
  ```
- **Docs:** https://mastra.ai/docs/relevant-section

Example Output

## Mastra System Check Results

**Project:** my-mastra-app
**Scanned:** 12 files
**Duration:** 2.3s

---

### 🔴 CRITICAL Issues (2)

**[config-storage-provider] Missing Storage Provider**
- **Location:** `src/mastra/index.ts:8`
- **Issue:** No storage configured - memory, workflows, and traces won't persist
- **Fix:**
  ```typescript
  import { LibSQLStore } from "@mastra/libsql";

  export const mastra = new Mastra({
    storage: new LibSQLStore({
      url: process.env.DATABASE_URL || "file:./mastra.db",
    }),
    agents: { myAgent },
  });
  ```
- **Docs:** https://mastra.ai/docs/storage

**[config-env-variables] Missing API Key**
- **Location:** `.env`
- **Issue:** OPENAI_API_KEY not set but `openai/gpt-4o` model is used
- **Fix:** Add to `.env`:
  ```bash
  OPENAI_API_KEY=sk-your-key-here
  ```

---

### 🟠 HIGH Issues (1)

**[prompt-right-altitude] Under-specified Agent Instructions**
- **Location:** `src/mastra/agents/assistant.ts:12`
- **Issue:** Agent has minimal instructions: "You are a helpful assistant"
- **Fix:**
  ```typescript
  instructions: `
    <role>
    You are a customer support agent for Acme Corp.
    </role>

    <capabilities>
    - Answer product questions using search_products tool
    - Check order status using order_lookup tool
    </capabilities>

    <guidelines>
    - Be concise and helpful
    - Escalate billing issues to human support
    </guidelines>
  `,
  ```

---

### 🟡 MEDIUM Issues (0)

No medium-priority issues found.

---

### 🟢 LOW Issues (1)

**[optimization-model-selection] Expensive Model for Simple Task**
- **Location:** `src/mastra/agents/classifier.ts:6`
- **Issue:** Using `gpt-4o` for classification - `gpt-4o-mini` would be more cost-effective
- **Fix:** Change model to `openai/gpt-4o-mini` for simple classification tasks

---

### ✅ Summary

| Priority | Issues |
|----------|--------|
| 🔴 CRITICAL | 2 |
| 🟠 HIGH | 1 |
| 🟡 MEDIUM | 0 |
| 🟢 LOW | 1 |

**Passed: 62/66 checks**

**Next Steps:**
1. Fix CRITICAL issues immediately - system won't work without them
2. Address HIGH issues before deployment
3. Consider LOW optimizations to reduce costs

Conditional Checks

Some rules only apply in specific situations:

Observability Section (Conditional)

Only check if telemetry or observability is configured, or if evals/scorers are used.

// If you see this in the codebase, run observability checks:
telemetry: { enabled: true, ... }
// or
evals: { scorers: [...] }

If NOT configured: Skip observability section entirely - it's optional.

Memory Checks (Conditional)

Only check if agents have memory configured.

Workflow Storage (Conditional)

Only check if workflows use suspend() for human-in-the-loop.

Scope Limitations

This skill does NOT:
- ❌ Deploy projects or run the dev server
- ❌ Make changes without user approval
- ❌ Check runtime behavior (static analysis only)
- ❌ Validate external API integrations
- ❌ Test actual LLM responses
- ❌ Run the project's test suite

This skill DOES:
- ✅ Static code analysis
- ✅ Configuration validation
- ✅ Best practice review
- ✅ Security pattern detection
- ✅ Provide specific code fixes

Documentation Links

Include these when suggesting fixes:

Full Rules Reference

For complete details on all 66 rules with code examples and fixes, read AGENTS.md in this skill directory.

Common Fix Patterns

Missing Storage (Most Common)

import { LibSQLStore } from "@mastra/libsql";

export const mastra = new Mastra({
  storage: new LibSQLStore({
    url: process.env.DATABASE_URL || "file:./mastra.db",
  }),
  agents: { /* ... */ },
});

Wrong Model Format

// ❌ Wrong
model: "gpt-4o"

// ✅ Correct
model: "openai/gpt-4o"

Missing Workflow Commit

// ❌ Wrong
const workflow = new Workflow({ id: "my-flow" })
  .step("step1", { execute: async () => ({ done: true }) });

// ✅ Correct
const workflow = new Workflow({ id: "my-flow" })
  .step("step1", { execute: async () => ({ done: true }) })
  .commit();  // Required!

Memory Without Thread/Resource

// ❌ Wrong
await agent.generate("Hello");

// ✅ Correct
await agent.generate("Hello", {
  memory: {
    thread: `session-${sessionId}`,
    resource: `user-${userId}`,
  },
});

Version History

• 1.1.0 - Enhanced triggering, quick checks, execution steps, example output
• 1.0.0 - Initial release with 66 rules across 10 categories