mastra-system-check

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