@balazsbarta/mp-skills 0.1.0

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

@@ -0,0 +1,193 @@
+# Remote Docs Reference
+
+How to look up current documentation from https://mastra.ai when local packages aren't available or you need conceptual guidance.
+
+**Use this when:**
+
+- Mastra packages aren't installed locally
+- You need conceptual explanations or guides
+- You want the latest documentation (may be ahead of installed version)
+
+## Documentation site structure
+
+Mastra docs are organized at **https://mastra.ai**:
+
+- **Docs**: Core documentation covering concepts, features, and implementation details
+- **Models**: Mastra provides a unified interface for working with LLMs across multiple providers
+- **Guides**: Step-by-step tutorials for building specific applications
+- **Reference**: API reference documentation
+
+## Finding relevant documentation
+
+### Method 1: Use llms.txt (Recommended)
+
+The main llms.txt file provides an agent-friendly overview of all documentation: https://mastra.ai/llms.txt
+
+This returns a structured markdown document with:
+
+- Documentation organization and hierarchy
+- All available topics and sections
+- Direct links to relevant documentation
+- Agent-optimized content structure
+
+**Use this first** to understand what documentation is available and where to find specific topics.
+
+### Method 2: Direct URL patterns
+
+Documentation follows predictable URL patterns:
+
+- Overview pages: `https://mastra.ai/docs/{topic}/overview`
+- API reference: `https://mastra.ai/reference/{topic}/`
+- Guides: `https://mastra.ai/guides/{topic}/`
+
+**Examples:**
+
+- `https://mastra.ai/docs/agents/overview`
+- `https://mastra.ai/docs/workflows/overview`
+- `https://mastra.ai/reference/workflows/workflow-methods/`
+
+## Agent-friendly documentation
+
+**Critical feature**: Send the `text-markdown` request header or add `.md` to any documentation URL to get clean, agent-friendly markdown.
+
+### Standard URL:
+
+```
+https://mastra.ai/reference/workflows/workflow-methods/then
+```
+
+### Agent-friendly URL (Markdown):
+
+```
+https://mastra.ai/reference/workflows/workflow-methods/then.md
+```
+
+The `.md` version:
+
+- Removes navigation, headers, footers
+- Returns pure markdown content
+- Optimized for LLM consumption
+- Includes all code examples and explanations
+
+## Lookup Workflow
+
+### 1. Check the main documentation index
+
+**Start here** to understand what's available:
+
+```
+https://mastra.ai/llms.txt
+```
+
+This provides:
+
+- Complete documentation structure
+- Available topics and sections
+- Links to relevant documentation pages
+
+### 2. Find relevant documentation
+
+**Option A: Use information from llms.txt**
+The main llms.txt will guide you to the right section.
+
+**Option B: Construct URL directly**
+
+```
+https://mastra.ai/docs/{topic}/overview
+https://mastra.ai/reference/{topic}/
+```
+
+### 3. Fetch agent-friendly version
+
+Add `.md` to the end of any documentation URL:
+
+```
+https://mastra.ai/reference/workflows/workflow-methods/then.md
+```
+
+### 4. Extract relevant information
+
+The markdown will include:
+
+- Function signatures
+- Parameter descriptions
+- Return types
+- Usage examples
+- Best practices
+
+## Common documentation paths
+
+### Agents
+
+- Overview: `https://mastra.ai/docs/agents/overview`
+- Creating agents: `https://mastra.ai/docs/agents/creating-agents`
+- Agent tools: `https://mastra.ai/docs/agents/tools`
+- Memory: `https://mastra.ai/docs/agents/memory`
+
+### Workflows
+
+- Overview: `https://mastra.ai/docs/workflows/overview`
+- Creating workflows: `https://mastra.ai/docs/workflows/creating-workflows`
+- Workflow methods: `https://mastra.ai/reference/workflows/workflow-methods/`
+
+### Tools
+
+- Overview: `https://mastra.ai/docs/tools/overview`
+- Creating tools: `https://mastra.ai/docs/tools/creating-tools`
+
+### Memory
+
+- Overview: `https://mastra.ai/docs/memory/overview`
+- Configuration: `https://mastra.ai/docs/memory/configuration`
+
+### RAG
+
+- Overview: `https://mastra.ai/docs/rag/overview`
+- Vector stores: `https://mastra.ai/docs/rag/vector-stores`
+
+## Example: Looking up workflow .then() method
+
+### 1. Check main documentation index
+
+```
+WebFetch({
+  url: "https://mastra.ai/llms.txt",
+  prompt: "Where can I find documentation about workflow methods like .then()?"
+})
+```
+
+This will point you to the workflows reference section.
+
+### 2. Fetch specific method documentation
+
+```
+https://mastra.ai/reference/workflows/workflow-methods/then.md
+```
+
+### 3. Use WebFetch tool
+
+```
+WebFetch({
+  url: "https://mastra.ai/reference/workflows/workflow-methods/then.md",
+  prompt: "What are the parameters for the .then() method and how do I use it?"
+})
+```
+
+## When to use remote vs embedded docs
+
+| Situation                  | Use                                                 |
+| -------------------------- | --------------------------------------------------- |
+| Packages installed locally | **Embedded docs** (guaranteed version match)        |
+| Packages not installed     | **Remote docs**                                     |
+| Need conceptual guides     | **Remote docs**                                     |
+| Need exact API signatures  | **Embedded docs** (if available)                    |
+| Exploring new features     | **Remote docs** (may be ahead of installed version) |
+| Need working examples      | **Both** (embedded for types, remote for guides)    |
+
+## Best practices
+
+1. **Always use .md** for fetching documentation
+2. **Check sitemap.xml** when unsure about URL structure
+3. **Prefer embedded docs** when packages are installed (version accuracy)
+4. **Use remote docs** for conceptual understanding and guides
+5. **Combine both** for comprehensive understanding

package/.agents/skills/next-js/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: next-js
+description: "Next.js App Router development guide. Covers App Router conventions, API routes, caching and revalidation, metadata/SEO, and common errors. Use this skill when building or debugging Next.js applications using the App Router."
+license: MIT
+metadata:
+  author: Balazs Barta
+  version: "2.0.0"
+  repository: https://github.com/balazsbarta/mp-skills
+  tags:
+    - next-js
+    - react
+    - app-router
+    - server-components
+    - full-stack
+---
+
+# Next.js Guide
+
+Build full-stack web applications with Next.js App Router.
+
+## ⚠️ Critical: Do not trust internal knowledge
+
+**Everything you know about Next.js may be outdated or wrong. Never rely on memory. Always verify against current documentation.**
+
+Next.js evolves rapidly between major versions. App Router APIs, caching behavior, and conventions change frequently. Always check the references in this skill.
+
+## Prerequisites
+
+**Before writing Next.js code**, validate installed version and local project config:
+
+```bash
+npx next --version
+cat node_modules/next/package.json | grep '"version"'
+ls next.config.* 2>/dev/null
+npx next info
+```
+
+- If installed, follow repository behavior and config first.
+- If configuration is unclear, use this skill's lookup flow before coding.
+
+## Documentation lookup guide
+
+### Quick reference
+
+| User Question | First Check | How To |
+| --- | --- | --- |
+| "What works in this repo version?" | [`references/embedded-docs.md`](references/embedded-docs.md) | Check local version, config, and route structure |
+| "How do I create pages/layouts?" | [`references/app-router.md`](references/app-router.md) | File conventions, layouts, loading/error states |
+| "How do I create an API endpoint?" | [`references/api-routes.md`](references/api-routes.md) | Route Handlers with GET/POST/etc. |
+| "How does caching work?" | [`references/caching-revalidation.md`](references/caching-revalidation.md) | Caching layers and revalidation strategies |
+| "How do I set metadata/SEO?" | [`references/metadata-seo.md`](references/metadata-seo.md) | Static and dynamic metadata, Open Graph |
+| "I'm getting an error..." | [`references/common-errors.md`](references/common-errors.md) | Common errors and solutions |
+| "I need official latest behavior" | [`references/remote-docs.md`](references/remote-docs.md) | Use official docs and llms index |
+
+### Priority order for writing code
+
+1. **Embedded/local project docs first**
+
+   - Use `references/embedded-docs.md`.
+   - Confirm actual behavior with local config and `npx next build`.
+
+2. **Local skill references second**
+
+   - Use App Router/API/caching/metadata reference files in this skill.
+
+3. **Official docs third**
+
+   - Use `references/remote-docs.md` and `https://nextjs.org/docs/llms.txt`.
+
+## Core concepts
+
+### App Router file conventions
+
+```
+app/
+├── layout.tsx           # Root layout (required)
+├── page.tsx             # Home page (/)
+├── loading.tsx          # Loading UI
+├── error.tsx            # Error boundary
+├── not-found.tsx        # 404 page
+├── about/
+│   └── page.tsx         # /about
+├── blog/
+│   ├── page.tsx         # /blog
+│   └── [slug]/
+│       └── page.tsx     # /blog/:slug
+└── api/
+    └── users/
+        └── route.ts     # API: /api/users
+```
+
+### Server vs Client Components
+
+| Feature | Server Component (default) | Client Component (`'use client'`) |
+| --- | --- | --- |
+| Rendering | Server only | Server + Client |
+| Interactivity | No (no useState, onClick) | Yes |
+| Data fetching | Direct (async/await) | Via hooks or API |
+| Bundle size | Not in JS bundle | In JS bundle |
+
+### When to use `'use client'`
+
+- Interactive UI (forms, buttons with handlers)
+- Browser APIs (localStorage, window)
+- React hooks (useState, useEffect, useContext)
+- Event handlers (onClick, onChange)
+
+## Critical requirements
+
+### Root layout is required
+
+```typescript
+// app/layout.tsx — REQUIRED
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+### Pages must export a default component
+
+```typescript
+// app/page.tsx
+export default function Home() {
+  return <h1>Hello World</h1>;
+}
+```
+
+## When you see errors
+
+**Most Next.js issues are version/config mismatches before they are code logic bugs.**
+
+1. Re-check local version and config.
+2. Verify route conventions in local files.
+3. Confirm behavior in official docs (`references/remote-docs.md`).
+
+## Step-by-step workflow
+
+### 1. Create a Next.js project
+
+```bash
+npx create-next-app@latest my-app --typescript --app --tailwind
+cd my-app
+```
+
+### 2. Start development
+
+```bash
+npm run dev
+```
+
+### 3. Build for production
+
+```bash
+npm run build
+npm start
+```
+
+### 4. Check build output
+
+```bash
+npx next build
+# Review the output for page types: Static, SSR, ISR
+```
+
+## Error handling
+
+### Common issues
+
+| Symptom | Likely Cause | Fix |
+| --- | --- | --- |
+| "useState is not defined" | Using hooks in Server Component | Add `'use client'` directive |
+| "Hydration mismatch" | Server/client HTML differs | Check for browser-only code in render |
+| "Dynamic server usage" | Using dynamic features in static page | Add `export const dynamic = 'force-dynamic'` |
+| Build takes too long | Large pages or data fetching | Check data fetching, use ISR |
+
+## Expected outputs
+
+```bash
+# Successful build
+Route (app)                   Size     First Load JS
+┌ ○ /                         5.2 kB   90 kB
+├ ○ /about                    1.1 kB   86 kB
+├ λ /api/users                0 B      0 B
+└ ● /blog/[slug]              2.3 kB   87 kB
+
+○  (Static)   prerendered as static content
+●  (SSG)      prerendered as static HTML (uses getStaticProps)
+λ  (Dynamic)  server-rendered on demand
+```
+
+## Cross-references
+
+- **Vitest**: [../vitest/SKILL.md](../vitest/SKILL.md) — Unit testing Next.js components
+- **Playwright**: [../playwright/SKILL.md](../playwright/SKILL.md) — E2E testing Next.js applications
+- **Supabase**: [../supabase/SKILL.md](../supabase/SKILL.md) — Backend services for Next.js
+
+## Resources
+
+- **App Router**: [`references/app-router.md`](references/app-router.md)
+- **API routes**: [`references/api-routes.md`](references/api-routes.md)
+- **Caching and revalidation**: [`references/caching-revalidation.md`](references/caching-revalidation.md)
+- **Metadata and SEO**: [`references/metadata-seo.md`](references/metadata-seo.md)
+- **Common errors**: [`references/common-errors.md`](references/common-errors.md)
+- **Embedded docs lookup**: [`references/embedded-docs.md`](references/embedded-docs.md)
+- **Official docs lookup**: [`references/remote-docs.md`](references/remote-docs.md)

package/.agents/skills/next-js/references/api-routes.md

@@ -0,0 +1,213 @@
+# API Routes (Route Handlers)
+
+Create API endpoints using Next.js App Router Route Handlers.
+
+## When to use this reference
+
+- Creating REST API endpoints in Next.js
+- Handling different HTTP methods (GET, POST, PUT, DELETE)
+- Working with request/response objects
+- Streaming responses
+
+## Basic Route Handler
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET() {
+  const users = await getUsers();
+  return NextResponse.json(users);
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const user = await createUser(body);
+  return NextResponse.json(user, { status: 201 });
+}
+```
+
+## HTTP methods
+
+Export named functions matching HTTP methods:
+
+| Export | Method | Use For |
+| --- | --- | --- |
+| `GET` | GET | Fetch data |
+| `POST` | POST | Create data |
+| `PUT` | PUT | Replace data |
+| `PATCH` | PATCH | Partial update |
+| `DELETE` | DELETE | Remove data |
+| `HEAD` | HEAD | Headers only |
+| `OPTIONS` | OPTIONS | CORS preflight |
+
+## Route parameters
+
+```typescript
+// app/api/users/[id]/route.ts
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const user = await getUser(id);
+
+  if (!user) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  }
+
+  return NextResponse.json(user);
+}
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  await deleteUser(id);
+  return new NextResponse(null, { status: 204 });
+}
+```
+
+## Request handling
+
+### Query parameters
+
+```typescript
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams;
+  const page = searchParams.get('page') || '1';
+  const limit = searchParams.get('limit') || '10';
+  // ...
+}
+```
+
+### Request body
+
+```typescript
+export async function POST(request: NextRequest) {
+  // JSON body
+  const body = await request.json();
+
+  // Form data
+  const formData = await request.formData();
+  const name = formData.get('name');
+}
+```
+
+### Headers
+
+```typescript
+export async function GET(request: NextRequest) {
+  const authHeader = request.headers.get('Authorization');
+
+  return NextResponse.json(data, {
+    headers: {
+      'Cache-Control': 'no-store',
+    },
+  });
+}
+```
+
+## Response patterns
+
+### JSON response
+
+```typescript
+return NextResponse.json({ message: 'Success' });
+return NextResponse.json({ error: 'Not found' }, { status: 404 });
+```
+
+### Redirect
+
+```typescript
+import { redirect } from 'next/navigation';
+redirect('/login');
+
+// Or with NextResponse
+return NextResponse.redirect(new URL('/login', request.url));
+```
+
+### Streaming
+
+```typescript
+export async function GET() {
+  const stream = new ReadableStream({
+    async start(controller) {
+      for (let i = 0; i < 10; i++) {
+        controller.enqueue(`data: ${i}\n\n`);
+        await new Promise((r) => setTimeout(r, 1000));
+      }
+      controller.close();
+    },
+  });
+
+  return new Response(stream, {
+    headers: { 'Content-Type': 'text/event-stream' },
+  });
+}
+```
+
+## Route configuration
+
+```typescript
+// app/api/users/route.ts
+
+// Force dynamic (no caching)
+export const dynamic = 'force-dynamic';
+
+// Set max duration (for long-running handlers)
+export const maxDuration = 30;
+
+// Set runtime
+export const runtime = 'edge'; // or 'nodejs' (default)
+```
+
+## CORS handling
+
+```typescript
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    headers: {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+    },
+  });
+}
+```
+
+## Middleware for API routes
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  if (request.nextUrl.pathname.startsWith('/api/')) {
+    const authHeader = request.headers.get('Authorization');
+    if (!authHeader) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+  }
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: '/api/:path*',
+};
+```
+
+## Troubleshooting
+
+### Route not found
+
+- File must be named `route.ts` (not `api.ts` or `handler.ts`)
+- Cannot have both `route.ts` and `page.tsx` in same directory
+- Check export matches HTTP method name (uppercase)
+
+### Body already consumed
+
+- `request.json()` and `request.text()` can only be called once
+- Store the result in a variable