---

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:

| Category | Example Phrases | |----------|-----------------| | General Check | "check my mastra project", "mastra system check", "validate mastra", "review my mastra code" | | Setup Issues | "mastra not working", "agent won't start", "can't find mastra instance" | | Memory Issues | "memory not persisting", "conversation lost", "agent forgets context" | | Workflow Issues | "workflow stuck", "workflow not executing", "steps not running" | | Context Issues | "context not propagating", "requestcontext empty", "can't access user data" | | Deployment | "prepare for production", "production checklist", "deploy mastra" | | Debugging | "debug mastra", "troubleshoot agent", "why is my agent..." |

---

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

| Pattern | Purpose | Priority | |---------|---------|----------| | src/mastra/index.ts | Main Mastra instance, storage, agents | CRITICAL | | src/mastra/agents/*.ts | Agent definitions | HIGH | | src/mastra/workflows/*.ts | Workflow definitions | HIGH | | src/mastra/tools/*.ts | Tool definitions | MEDIUM | | package.json | Dependencies, versions | CRITICAL | | tsconfig.json | TypeScript module config | CRITICAL | | .env / .env.local | API keys, secrets | CRITICAL | | src/**/middleware*.ts | RequestContext setup | HIGH |

---

Priority Legend

| Badge | Level | Meaning | Action | |-------|-------|---------|--------| | 🔴 | CRITICAL | System won't function | Fix immediately | | 🟠 | HIGH | Major functionality issues | Fix before deployment | | 🟡 | MEDIUM | Quality/maintainability | Fix when possible | | 🟢 | LOW | Performance/cost optimization | Nice to have |

---

Check Categories Summary

| Category | Rules | Priority | Key Checks | |----------|-------|----------|------------| | Configuration | 6 | 🔴 CRITICAL | Storage, env vars, TypeScript, entry point | | Agents | 6 | 🟠 HIGH | Model format, instructions, tools, memory | | Workflows | 6 | 🟠 HIGH | .commit(), schemas, connections, suspend | | Context | 8 | 🟠 HIGH | RequestContext typing, propagation, access | | Prompts | 10 | 🟠 HIGH | Token efficiency, structure, examples | | Memory | 6 | 🟡 MEDIUM | Storage, threads, vector stores | | Tools | 6 | 🟡 MEDIUM | Schemas, descriptions, error handling | | Observability | 6 | 🟡 MEDIUM* | Tracing, scorers, exporters | | Security | 6 | 🟡 MEDIUM | Auth, CORS, PII, secrets | | Optimization | 6 | 🟢 LOW | Model selection, caching, timeouts |

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

```markdown
## 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:

  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:

  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.

```typescript
// 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:

| Topic | URL | |-------|-----| | Mastra Docs | https://mastra.ai/docs | | Storage Setup | https://mastra.ai/docs/storage | | Memory Guide | https://mastra.ai/docs/memory | | Workflows | https://mastra.ai/docs/workflows | | Agents | https://mastra.ai/docs/agents | | Tools | https://mastra.ai/docs/tools | | AI SDK | https://sdk.vercel.ai/docs |

---

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