@balazsbarta/mp-skills 0.1.0

package/.agents/skills/mastra/references/create-mastra.md

@@ -0,0 +1,220 @@
+# Create Mastra Reference
+
+Complete guide for creating new Mastra projects. Includes both quickstart CLI method and detailed manual installation.
+
+**Official documentation: [mastra.ai/docs](https://mastra.ai/docs)**
+
+## Getting Started
+
+Ask: **"How would you like to create your Mastra project?"**
+
+1. **Quick Setup**: Copy and run: `npm create mastra@latest`
+2. **Guided Setup**: I walk you through each step, you approve commands
+3. **Automatic Setup**: I create everything, just give me your API key
+
+> **For AI agents:** The CLI is interactive. Use **Automatic Setup** to create files using the steps in "Automatic Setup / Manual Installation" below.
+
+## Prerequisites
+
+- An API key from a supported model provider (OpenAI, Anthropic, Google, etc.)
+
+## Quick Setup (user runs CLI)
+
+Create a new Mastra project with one command:
+
+```bash
+npm create mastra@latest
+```
+
+**Other package managers:**
+
+```bash
+pnpm create mastra@latest
+yarn create mastra@latest
+bun create mastra@latest
+```
+
+## CLI flags
+
+**Skip the example agent:**
+
+```bash
+npm create mastra@latest --no-example
+```
+
+**Use a specific template:**
+
+```bash
+npm create mastra@latest --template <template-name>
+```
+
+## Automatic setup / manual installation
+
+**Use this for automatic setup** (AI creates all files) or when you prefer manual control.
+
+Follow these steps to create a complete Mastra project:
+
+### Step 1: Create project directory
+
+```bash
+mkdir my-first-agent && cd my-first-agent
+npm init -y
+```
+
+### Step 2: Install dependencies
+
+```bash
+npm install -D typescript @types/node mastra@latest
+npm install @mastra/core@latest zod@^4
+```
+
+### Step 3: Configure package scripts
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "mastra dev",
+    "build": "mastra build"
+  }
+}
+```
+
+### Step 4: Configure TypeScript
+
+Create `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+**Important:** Mastra requires `"module": "ES2022"` and `"moduleResolution": "bundler"`. CommonJS will cause errors.
+
+### Step 5: Create environment file
+
+Create `.env` with your API key:
+
+```env
+GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>
+```
+
+Or use `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.
+
+### Step 6: Create weather tool
+
+Create `src/mastra/tools/weather-tool.ts`:
+
+```typescript
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const weatherTool = createTool({
+  id: "get-weather",
+  description: "Get current weather for a location",
+  inputSchema: z.object({
+    location: z.string().describe("City name"),
+  }),
+  outputSchema: z.object({
+    output: z.string(),
+  }),
+  execute: async () => {
+    return { output: "The weather is sunny" };
+  },
+});
+```
+
+### Step 7: Create weather agent
+
+Create `src/mastra/agents/weather-agent.ts`:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { weatherTool } from "../tools/weather-tool";
+
+export const weatherAgent = new Agent({
+  id: "weather-agent",
+  name: "Weather Agent",
+  instructions: `
+      You are a helpful weather assistant that provides accurate weather information.
+
+      Your primary function is to help users get weather details for specific locations. When responding:
+      - Always ask for a location if none is provided
+      - If the location name isn't in English, please translate it
+      - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
+      - Include relevant details like humidity, wind conditions, and precipitation
+      - Keep responses concise but informative
+
+      Use the weatherTool to fetch current weather data.
+`,
+  model: "google/gemini-2.5-pro",
+  tools: { weatherTool },
+});
+```
+
+**Note:** Model format is `"provider/model-name"`. Examples:
+
+- `"google/gemini-2.5-pro"`
+- `"openai/gpt-4o"`
+- `"anthropic/claude-3-5-sonnet-20241022"`
+
+### Step 8: Create mastra entry point
+
+Create `src/mastra/index.ts`:
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { weatherAgent } from "./agents/weather-agent";
+
+export const mastra = new Mastra({
+  agents: { weatherAgent },
+});
+```
+
+### Step 9: Launch development server
+
+```bash
+npm run dev
+```
+
+Access Studio at `http://localhost:4111` to test your agent.
+
+## Next steps
+
+After creating your project with `create mastra`:
+
+- **Customize the example agent** in `src/mastra/agents/weather-agent.ts`
+- **Add new agents** - see [Agents documentation](https://mastra.ai/docs/agents/overview)
+- **Create workflows** - see [Workflows documentation](https://mastra.ai/docs/workflows/overview)
+- **Add more tools** to extend agent capabilities
+- **Integrate into your app** - see framework guides at [mastra.ai/docs](https://mastra.ai/docs)
+
+## Troubleshooting
+
+| Issue              | Solution                                                                             |
+| ------------------ | ------------------------------------------------------------------------------------ |
+| API key not found  | Make sure your `.env` file has the correct key                                       |
+| Studio won't start | Check that port 4111 is available                                                    |
+| CommonJS errors    | Ensure `tsconfig.json` uses `"module": "ES2022"` and `"moduleResolution": "bundler"` |
+| Command not found  | Ensure you're using Node.js 20+                                                      |
+
+## Resources
+
+- [Docs](https://mastra.ai/docs)
+- [Installation](https://mastra.ai/docs/getting-started/installation)
+- [Agents](https://mastra.ai/docs/agents/overview)
+- [Workflows](https://mastra.ai/docs/workflows/overview)
+- [GitHub](https://github.com/mastra-ai/mastra)

package/.agents/skills/mastra/references/embedded-docs.md

@@ -0,0 +1,123 @@
+# Embedded Docs Reference
+
+Look up API signatures from embedded docs in `node_modules/@mastra/*/dist/docs/` - these match the installed version.
+
+**Use this FIRST** when Mastra packages are installed locally. Embedded docs are always accurate for the installed version.
+
+## Why use embedded docs
+
+- **Version accuracy**: Embedded docs match the exact installed version
+- **No network required**: All docs are local in `node_modules/`
+- **Mastra evolves quickly**: APIs change rapidly, embedded docs stay in sync
+- **TypeScript definitions**: Includes JSDoc, type signatures, and examples
+- **Training data may be outdated**: Claude's knowledge cutoff may not reflect latest APIs
+
+## Documentation structure
+
+```
+node_modules/@mastra/core/dist/docs/
+├── SKILL.md           # Package overview, exports
+├── SOURCE_MAP.json    # Export→file mappings
+└── [topics]/          # Feature docs (agents/, workflows/, etc.)
+```
+
+## Lookup process
+
+### 1. Check if packages are installed
+
+```bash
+ls node_modules/@mastra/
+```
+
+If you see packages like `core`, `memory`, `rag`, etc., proceed with embedded docs lookup.
+
+### 2. Find the export in SOURCE_MAP.json
+
+```bash
+cat node_modules/@mastra/core/dist/docs/SOURCE_MAP.json | grep '"Agent"'
+```
+
+Returns: `{ "Agent": { "types": "dist/agent/agent.d.ts", ... } }`
+
+### 3. Read the type definition
+
+```bash
+cat node_modules/@mastra/core/dist/agent/agent.d.ts
+```
+
+This shows the exact TypeScript interface, constructor parameters, and JSDoc.
+
+### 4. Check topic docs (optional)
+
+```bash
+cat node_modules/@mastra/core/dist/docs/agents/01-overview.md
+```
+
+Topic docs provide conceptual explanations and usage examples.
+
+## Common packages
+
+| Package          | Path                                     | Contains                                  |
+| ---------------- | ---------------------------------------- | ----------------------------------------- |
+| `@mastra/core`   | `node_modules/@mastra/core/dist/docs/`   | Agents, Workflows, Tools, Mastra instance |
+| `@mastra/memory` | `node_modules/@mastra/memory/dist/docs/` | Memory systems, conversation history      |
+| `@mastra/rag`    | `node_modules/@mastra/rag/dist/docs/`    | RAG features, vector stores               |
+| `@mastra/pg`     | `node_modules/@mastra/pg/dist/docs/`     | PostgreSQL storage                        |
+| `@mastra/libsql` | `node_modules/@mastra/libsql/dist/docs/` | LibSQL/SQLite storage                     |
+
+## Quick commands reference
+
+```bash
+# List installed @mastra packages
+ls node_modules/@mastra/
+
+# Find specific export in SOURCE_MAP
+cat node_modules/@mastra/core/dist/docs/SOURCE_MAP.json | grep '"ExportName"'
+
+# Read type definition from path
+cat node_modules/@mastra/core/dist/[path-from-source-map]
+
+# List available topic documentation
+ls node_modules/@mastra/core/dist/docs/
+
+# View package overview
+cat node_modules/@mastra/core/dist/docs/SKILL.md
+
+# Search for specific functionality in source
+grep -r "functionName" node_modules/@mastra/core/src/
+```
+
+## Example: Looking up agent constructor
+
+**1. Find Agent in SOURCE_MAP:**
+
+```bash
+cat node_modules/@mastra/core/dist/docs/SOURCE_MAP.json | grep '"Agent"'
+```
+
+**2. Read the type definition:**
+
+```bash
+cat node_modules/@mastra/core/dist/agent/agent.d.ts
+```
+
+**3. Check topic docs for usage examples:**
+
+```bash
+cat node_modules/@mastra/core/dist/docs/agents/01-overview.md
+```
+
+## When embedded docs are not available
+
+If packages aren't installed or `dist/docs/` doesn't exist:
+
+1. **Recommend installation**: Suggest installing packages to access embedded docs
+2. **Fall back to remote docs**: See `references/remote-docs.md`
+
+## Best Practices
+
+1. **Always check SOURCE_MAP.json first** to find the correct file path
+2. **Read type definitions** for exact parameter names and types
+3. **Check topic docs** for conceptual understanding and patterns
+4. **Search source code** if docs don't answer the question
+5. **Verify imports** match what's exported in the type definitions

package/.agents/skills/mastra/references/migration-guide.md

@@ -0,0 +1,180 @@
+# Migration Guide
+
+Guide for upgrading Mastra versions using official documentation and current API verification.
+
+## Migration strategy
+
+For version upgrades, follow this process:
+
+### 1. Check official migration docs
+
+**Always start with the official migration documentation:** `https://mastra.ai/llms.txt`
+
+Look for the **Migrations** or **Guides** section, which will have:
+
+- Breaking changes for each version
+- Automated migration tools
+- Step-by-step upgrade instructions
+
+**Example sections to look for:**
+
+- `/guides/migrations/upgrade-to-v1/`
+- `/guides/migrations/upgrade-to-v2/`
+- Breaking changes lists
+
+### 2. Use embedded docs for current APIs
+
+After identifying breaking changes, verify the new APIs:
+
+**Check your installed version:**
+
+```bash
+cat node_modules/@mastra/core/dist/docs/SOURCE_MAP.json | grep '"ApiName"'
+cat node_modules/@mastra/core/dist/[path-from-source-map]
+```
+
+See [`embedded-docs.md`](embedded-docs.md) for detailed lookup instructions.
+
+### 3. Use remote docs for latest info
+
+If packages aren't updated yet, check what APIs will look like: `https://mastra.ai/reference/[topic]`
+
+See [`remote-docs.md`](remote-docs.md) for detailed lookup instructions.
+
+## Quick migration workflow
+
+```bash
+# 1. Check current version
+npm list @mastra/core
+
+# 2. Fetch migration guide from official docs
+# Use WebFetch: https://mastra.ai/llms.txt
+# Find relevant migration section
+
+# 3. Update dependencies
+npm install @mastra/core@latest @mastra/memory@latest @mastra/rag@latest mastra@latest
+
+# 4. Run automated migration (if available)
+npx @mastra/codemod@latest v1  # or whatever version
+
+# 5. Check embedded docs for new APIs
+cat node_modules/@mastra/core/dist/docs/SOURCE_MAP.json
+
+# 6. Fix breaking changes using embedded docs lookup
+# See embedded-docs.md for how to look up each API
+
+# 7. Test
+npm run dev
+npm test
+```
+
+## Common migration patterns
+
+### Finding what changed
+
+**Check official migration docs:** `https://mastra.ai/guides/migrations/upgrade-to-v1/overview.md`
+
+This will list:
+
+- Breaking changes
+- Deprecated APIs
+- New features
+- Migration tools
+
+### Updating API usage
+
+**For each breaking change:**
+
+1. **Find the old API** in your code
+2. **Look up the new API** using embedded docs:
+   ```bash
+   cat node_modules/@mastra/core/dist/docs/SOURCE_MAP.json | grep '"NewApi"'
+   cat node_modules/@mastra/core/dist/[path]
+   ```
+3. **Update your code** based on the type signatures
+4. **Test** the change
+
+### Example: Tool execute signature change
+
+**Official docs say:** "Tool execute signature changed"
+
+**Look up current signature:**
+
+```bash
+cat node_modules/@mastra/core/dist/docs/SOURCE_MAP.json | grep '"createTool"'
+cat node_modules/@mastra/core/dist/tools/tool.d.ts
+```
+
+**Update based on type definition:**
+
+```typescript
+// Old (from docs)
+execute: async (input) => { ... }
+
+// New (from embedded docs)
+execute: async (inputData, context) => { ... }
+```
+
+## Pre-migration checklist
+
+- [ ] Backup code (git commit)
+- [ ] Check official migration docs: `https://mastra.ai/llms.txt`
+- [ ] Note current version: `npm list @mastra/core`
+- [ ] Read breaking changes list
+- [ ] Tests are passing
+
+## Post-migration checklist
+
+- [ ] All dependencies updated together
+- [ ] TypeScript compiles: `npx tsc --noEmit`
+- [ ] Tests pass: `npm test`
+- [ ] Studio works: `npm run dev`
+- [ ] No console warnings
+- [ ] APIs verified against embedded docs
+
+## Migration resources
+
+| Resource                               | Use For                                       |
+| -------------------------------------- | --------------------------------------------- |
+| `https://mastra.ai/llms.txt`           | Finding migration guides and breaking changes |
+| [`embedded-docs.md`](embedded-docs.md) | Looking up new API signatures after updating  |
+| [`remote-docs.md`](remote-docs.md)     | Checking latest docs before updating          |
+| [`common-errors.md`](common-errors.md) | Fixing migration errors                       |
+
+## Version-specific notes
+
+### General principles
+
+1. **Always update all @mastra packages together**
+
+   ```bash
+   npm install @mastra/core@latest @mastra/memory@latest @mastra/rag@latest mastra@latest
+   ```
+
+2. **Check for automated migration tools**
+
+   ```bash
+   npx @mastra/codemod@latest [version]
+   ```
+
+3. **Verify Node.js version requirements**
+   - Check official migration docs for minimum Node version
+
+4. **Run database migrations if using storage**
+   - Follow storage migration guide in official docs
+
+## Getting help
+
+1. **Check official migration docs**: `https://mastra.ai/llms.txt` → Migrations section
+2. **Look up new APIs**: See [`embedded-docs.md`](embedded-docs.md)
+3. **Check for errors**: See [`common-errors.md`](common-errors.md)
+4. **Ask in Discord**: https://discord.gg/BTYqqHKUrf
+5. **File issues**: https://github.com/mastra-ai/mastra/issues
+
+## Key principles
+
+1. **Official docs are source of truth** - Start with `https://mastra.ai/llms.txt`
+2. **Verify with embedded docs** - Check installed version APIs
+3. **Update incrementally** - Don't skip major versions
+4. **Test thoroughly** - Run tests after each change
+5. **Use automation** - Use codemods when available