{'>'}_
English 繁體中文 日本語 한국어 Deutsch Español Français
Login

mastra-system-check

goldk3y/mastra-system-check

>

10 stars
0 forks
JavaScript
91 views
View on GitHub Add to Favorites

SKILL.md

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


---

## 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 },
  });

[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