claude-code-arcane 1.0.1 → 1.1.1

package/skills/nextjs-best-practices/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: nextjs-best-practices
+description: "React + Next.js performance: 64 reglas en 8 categorías (waterfalls, bundle, server, client fetching, re-render, rendering, JS, advanced) priorizadas por impacto, de Vercel Engineering. Usar al escribir/optimizar React o Next.js."
+category: "frontend"
+argument-hint: "[waterfalls|bundle|server|rerender|rendering|js|all]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# nextjs-best-practices — Performance priorizada por impacto
+
+64 reglas de optimización de performance para React y Next.js, de Vercel Engineering, organizadas en 8 categorías priorizadas de **CRITICAL** a **LOW**. Detalle por categoría en `references/`.
+
+## MANDATORY WORKFLOW
+
+**Diagnóstico dirigido por métricas, no aplicar las 64 reglas a ciegas** (este es el enfoque `vercel-optimize`: medir primero, optimizar solo lo que las métricas señalan).
+
+### Step 0: Medir / localizar
+
+1. **¿Hay métricas?** Lighthouse, Web Vitals (LCP/INP/CLS), bundle analyzer, traces de Vercel.
+2. **¿Cuál es el síntoma dominante?** TTFB alto → waterfalls/server. Bundle grande / TBT → bundle size. Jank en interacción → re-render. Layout shift → rendering.
+3. Identificar las rutas/componentes concretos que las métricas apuntan. Optimizar **esos**, no todo.
+
+### Step 1: Priorizar por impacto
+
+| Prioridad | Categoría | Impacto | Reference |
+|-----------|-----------|---------|-----------|
+| 1 | Eliminating Waterfalls | CRITICAL | `references/waterfalls.md` |
+| 2 | Bundle Size Optimization | CRITICAL | `references/bundle-size.md` |
+| 3 | Server-Side Performance | HIGH | `references/server.md` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `references/client-fetching.md` |
+| 5 | Re-render Optimization | MEDIUM | `references/rerender.md` |
+| 6 | Rendering Performance | MEDIUM | `references/rendering.md` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `references/javascript.md` |
+| 8 | Advanced Patterns | LOW | `references/advanced.md` |
+
+### Step 2: Aplicar + medir de nuevo
+
+Aplicar la regla, re-medir. Si la métrica no mejoró, revertir y subir de categoría — no acumular micro-optimizaciones sin impacto medible.
+
+### Step 3: Checklist de cierre
+
+- [ ] Fetches independientes en paralelo (`Promise.all`), no en cascada
+- [ ] Server Components por defecto; `'use client'` empujado abajo en el árbol
+- [ ] Sin barrel imports en el critical path; componentes pesados con `next/dynamic`
+- [ ] Server Actions autenticadas individualmente
+- [ ] Sin componentes definidos dentro de componentes
+- [ ] `next/image` + `generateMetadata` + resource hints donde corresponde
+- [ ] Re-medir Web Vitals post-cambios
+
+Si todo el checklist pasa → optimización **COMPLETE**. Antes de escribir cambios significativos, confirmar el approach con el usuario (Question → Decision → Approval).
+
+## Tabla síntoma → categoría
+
+| Métrica mala | Categoría |
+|--------------|-----------|
+| TTFB / tiempo de respuesta del server | Waterfalls, Server |
+| First Load JS / TBT alto | Bundle Size |
+| INP / jank en interacción | Re-render, JS |
+| LCP | Rendering, Bundle, Server |
+| CLS / flicker en hydration | Rendering |
+
+---
+
+_Adaptado de [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) (react-best-practices, MIT, © Vercel). 64 reglas priorizadas por impacto, reorganizadas al formato skill+references de Arcane._

package/skills/nextjs-best-practices/references/advanced.md

@@ -0,0 +1,21 @@
+# 8. Advanced Patterns (LOW)
+
+Patrones de borde con `useEffectEvent` y setup de app. Impacto bajo pero evitan bugs sutiles.
+
+## 8.4 useEffectEvent for Stable Callback Refs — LOW
+Referencias de callback estables para componentes memoizados sin re-disparar effects.
+```tsx
+const onTick = useEffectEvent(() => doSomething(latestProp));
+useEffect(() => { const id = setInterval(onTick, 1000); return () => clearInterval(id); }, []);
+```
+
+## 8.1 Do Not Put Effect Events in Dependency Arrays — LOW
+Los Effect Events no van en el array de dependencias; se llaman desde el effect, no lo re-disparan.
+
+## 8.2 Initialize App Once, Not Per Mount — LOW
+Setup de app a nivel module-load, no en effects/mounts de componente.
+
+## 8.3 Store Event Handlers in Refs — LOW
+Handlers que cambian seguido en refs → no causan re-render.
+
+_Ref: https://react.dev/reference/react/experimental_useEffectEvent_

package/skills/nextjs-best-practices/references/bundle-size.md

@@ -0,0 +1,32 @@
+# 2. Bundle Size Optimization (CRITICAL)
+
+## 2.1 Avoid Barrel File Imports — CRITICAL
+Los barrels (`index.ts` que re-exportan todo) arrastran miles de módulos sin usar.
+```ts
+// ✗ import { debounce } from 'lodash';   (todo lodash)
+// ✓ import debounce from 'lodash/debounce';
+```
+Configurar `optimizePackageImports` en `next.config.js` para libs grandes.
+
+## 2.4 Dynamic Imports for Heavy Components — CRITICAL
+```tsx
+const Chart = dynamic(() => import('./Chart'), { ssr: false, loading: () => <Skeleton/> });
+```
+Para charts, editores de texto rico, modales, mapas — todo lo no necesario en el primer render.
+
+## 2.5 Prefer Statically Analyzable Paths — HIGH
+Imports con paths literales/mapas explícitos, no construidos en runtime → permite tree-shaking.
+
+## 2.2 Conditional Module Loading — HIGH
+Cargar data/módulos grandes solo cuando la feature se activa.
+
+## 2.6 Preload Based on User Intent — MEDIUM
+Precargar el bundle pesado en hover/focus, antes de que se necesite.
+```tsx
+<button onMouseEnter={() => import('./HeavyModal')}>Abrir</button>
+```
+
+## 2.3 Defer Non-Critical Third-Party Libraries — MEDIUM
+Analytics, logging, error tracking → cargar después de hydration, no bloquear el bundle inicial (`next/script` con `strategy="afterInteractive"` o `lazyOnload`).
+
+_Ref: https://nextjs.org/docs/app/api-reference/components/script · https://nextjs.org/docs/app/api-reference/config/next-config-js/optimizePackageImports_

package/skills/nextjs-best-practices/references/client-fetching.md

@@ -0,0 +1,20 @@
+# 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+## 4.3 Use SWR for Automatic Deduplication — MEDIUM-HIGH
+Dedup de requests, caching y revalidación entre instancias de componente.
+```ts
+const { data } = useSWR(`/api/user/${id}`, fetcher); // mismo key = 1 request
+```
+
+## 4.2 Use Passive Event Listeners for Scrolling — MEDIUM
+```ts
+el.addEventListener('touchstart', handler, { passive: true }); // scroll inmediato
+```
+
+## 4.4 Version and Minimize localStorage Data — MEDIUM
+Prefijo de versión en las keys (`app:v2:prefs`) y guardar solo campos necesarios → evita conflictos y reduce tamaño.
+
+## 4.1 Deduplicate Global Event Listeners — LOW
+Compartir listeners globales entre instancias con un `Map` + `useSWRSubscription()` en vez de uno por componente.
+
+_Ref: https://swr.vercel.app_

package/skills/nextjs-best-practices/references/javascript.md

@@ -0,0 +1,47 @@
+# 7. JavaScript Performance (LOW-MEDIUM)
+
+Micro-optimizaciones. Aplicar solo en hot paths comprobados por profiling — no preventivamente.
+
+## 7.8 Early Length Check for Array Comparisons — MEDIUM-HIGH
+Comparar `length` antes de operaciones caras (sort/deep-compare).
+
+## 7.1 Avoid Layout Thrashing — MEDIUM
+Agrupar escrituras de estilo, luego leer layout una vez → evita reflows síncronos forzados.
+
+## 7.4 Cache Repeated Function Calls — MEDIUM
+`Map` para memoizar resultados de llamadas repetidas con mismos inputs.
+
+## 7.7 Defer Non-Critical Work with requestIdleCallback — MEDIUM
+Analytics, logging, prefetch en periodos idle del browser.
+
+## 7.2 Build Index Maps for Repeated Lookups — LOW-MEDIUM
+`Map` para O(1) en vez de múltiples `.find()`.
+
+## 7.3 Cache Property Access in Loops — LOW-MEDIUM
+Cachear `obj.prop` antes del loop.
+
+## 7.5 Cache Storage API Calls — LOW-MEDIUM
+Cachear lecturas de `localStorage`/`sessionStorage` en memoria.
+
+## 7.6 Combine Multiple Array Iterations — LOW-MEDIUM
+Fusionar `.filter()`/`.map()` múltiples en un solo loop.
+
+## 7.9 Early Return from Functions — LOW-MEDIUM
+Retornar apenas el resultado está determinado.
+
+## 7.10 Hoist RegExp Creation — LOW-MEDIUM
+`RegExp` a nivel módulo, no recrear en cada llamada/render.
+
+## 7.11 Use flatMap to Map and Filter in One Pass — LOW-MEDIUM
+`.flatMap(x => cond ? [f(x)] : [])` en vez de `.map().filter(Boolean)`.
+
+## 7.13 Use Set/Map for O(1) Lookups — LOW
+`Set.has()` en vez de `.includes()`/`.indexOf()` repetidos.
+
+## 7.12 Use Loop for Min/Max Instead of Sort — LOW
+Loop O(n) para min/max en vez de sort O(n log n).
+
+## 7.14 Use toSorted() Instead of sort() — LOW
+`.toSorted()` para inmutabilidad (no muta el original).
+
+_Ref: https://developer.mozilla.org/docs/Web/API/Window/requestIdleCallback_

package/skills/nextjs-best-practices/references/rendering.md

@@ -0,0 +1,46 @@
+# 6. Rendering Performance (MEDIUM)
+
+## 6.2 CSS content-visibility for Long Lists — HIGH
+```css
+.row { content-visibility: auto; contain-intrinsic-size: 0 80px; }
+```
+Difiere render y paint de lo off-screen.
+
+## 6.8 Use defer or async on Script Tags — HIGH
+`defer`/`async` para no bloquear el render durante el parsing.
+
+## 6.10 Use React DOM Resource Hints — HIGH
+```ts
+import { preload, preconnect } from 'react-dom';
+preconnect('https://cdn.example.com');
+preload('/hero.jpg', { as: 'image' });
+```
+
+## 6.5 Prevent Hydration Mismatch Without Flickering — MEDIUM
+Script inline síncrono que actualiza el DOM antes de hidratar (ej: theme).
+
+## 6.7 Use Activity Component for Show/Hide — MEDIUM
+`<Activity>` preserva estado y DOM para componentes que togglean visibilidad seguido.
+
+## 6.6 Suppress Expected Hydration Mismatches — LOW-MEDIUM
+`suppressHydrationWarning` solo para diferencias server/client intencionales (fechas, IDs).
+
+## 6.1 Animate SVG Wrapper Instead of SVG Element — LOW
+Envolver el SVG en un div y animar el wrapper → aceleración por hardware.
+
+## 6.3 Hoist Static JSX Elements — LOW
+JSX estático fuera del componente → no se recrea en cada render.
+
+## 6.4 Optimize SVG Precision — LOW
+Reducir precisión de coordenadas SVG → menor tamaño, sin impacto visual.
+
+## 6.9 Use Explicit Conditional Rendering — LOW
+Ternario en vez de `&&` → evita renderizar `0` u otros falsy.
+```tsx
+{count > 0 ? <Badge n={count}/> : null}  // no {count && ...}
+```
+
+## 6.11 Use useTransition Over Manual Loading States — LOW
+`useTransition` da pending state automático en vez de `useState` manual.
+
+_Ref: https://developer.mozilla.org/docs/Web/CSS/content-visibility · https://react.dev/reference/react-dom/preload_

package/skills/nextjs-best-practices/references/rerender.md

@@ -0,0 +1,55 @@
+# 5. Re-render Optimization (MEDIUM)
+
+## 5.4 Don't Define Components Inside Components — HIGH
+Definirlos inline los remonta en cada render (pierde estado y DOM). Definir a nivel módulo o extraer.
+```tsx
+// ✗ function Parent(){ function Row(){...}; return <Row/> }
+// ✓ Row a nivel módulo, fuera de Parent
+```
+
+## 5.1 Calculate Derived State During Rendering — MEDIUM
+Computar de props/state durante el render, no guardarlo en `useState` (se desincroniza).
+```tsx
+const fullName = `${first} ${last}`; // ✓  no useState + useEffect
+```
+
+## 5.11 Use Functional setState Updates — MEDIUM
+`setCount(c => c + 1)` — opera sobre el último valor, callbacks estables.
+
+## 5.12 Use Lazy State Initialization — MEDIUM
+`useState(() => expensiveInit())` — no recomputa en cada render.
+
+## 5.13 Use Transitions for Non-Urgent Updates — MEDIUM
+`startTransition(() => setFilter(x))` — mantiene la UI responsiva.
+
+## 5.14 useDeferredValue for Expensive Derived Renders — MEDIUM
+Mantiene el input responsivo difiriendo el resultado pesado.
+
+## 5.15 Use useRef for Transient Values — MEDIUM
+Valores que cambian seguido y no son UI → `useRef`, no re-render.
+
+## 5.2 Defer State Reads to Usage Point — MEDIUM
+Leer state dinámico dentro del callback, no suscribirse en render time.
+
+## 5.5 Extract Default Non-primitive Values — MEDIUM
+Defaults objeto/función a constantes a nivel módulo → preserva memoización.
+
+## 5.6 Extract to Memoized Components — MEDIUM
+Aislar trabajo caro en componentes memoizados con early returns.
+
+## 5.8 Put Interaction Logic in Event Handlers — MEDIUM
+Side effects de interacción van en handlers, no en `useEffect`.
+
+## 5.9 Split Combined Hook Computations — MEDIUM
+Separar hooks con dependencias distintas → no recomputar lo independiente.
+
+## 5.10 Subscribe to Derived State — MEDIUM
+Suscribirse a un booleano derivado, no al valor continuo → menos renders.
+
+## 5.3 Don't Wrap Simple Expressions in useMemo — LOW-MEDIUM
+El overhead del hook supera el cómputo de un primitivo.
+
+## 5.7 Narrow Effect Dependencies — LOW
+Dependencias primitivas, no objetos enteros.
+
+_Ref: https://react.dev/reference/react/useTransition · https://react.dev/learn/you-might-not-need-an-effect_

package/skills/nextjs-best-practices/references/server.md

@@ -0,0 +1,47 @@
+# 3. Server-Side Performance (HIGH)
+
+## 3.1 Authenticate Server Actions Like API Routes — CRITICAL
+Cada Server Action verifica auth/authz adentro, no solo confía en middleware.
+```ts
+'use server';
+export async function deletePost(id: string) {
+  const session = await auth();
+  if (!session?.user) throw new Error('Unauthorized');
+  if (!canDelete(session.user, id)) throw new Error('Forbidden');
+  // ...
+}
+```
+
+## 3.7 Parallel Data Fetching with Component Composition — CRITICAL
+Componer para que fetches independientes corran a la vez (cada uno en su `<Suspense>`).
+
+## 3.8 Parallel Nested Data Fetching — CRITICAL
+Encadenar fetches dependientes dentro de la promesa de cada item → un item lento no bloquea a los demás.
+
+## 3.3 Avoid Shared Module State for Request Data — HIGH
+Variables mutables a nivel módulo se comparten entre requests → data leaks. Mantener datos de request locales al árbol de render.
+
+## 3.5 Hoist Static I/O to Module Level — HIGH
+Lecturas estáticas (config, archivos) a nivel módulo, no en cada request.
+
+## 3.6 Minimize Serialization at RSC Boundaries — HIGH
+Pasar solo los campos que el cliente usa, no el objeto entero.
+
+## 3.4 Cross-Request LRU Caching — HIGH
+LRU cache para datos compartidos entre requests dentro de una ventana de tiempo.
+
+## 3.9 Per-Request Deduplication with React.cache() — MEDIUM
+```ts
+export const getUser = cache(async (id) => db.user.find(id)); // dedup mismo arg en el request
+```
+
+## 3.10 Use after() for Non-Blocking Operations — MEDIUM
+```ts
+import { after } from 'next/server';
+after(() => logAnalytics(event)); // corre tras enviar la respuesta
+```
+
+## 3.2 Avoid Duplicate Serialization in RSC Props — LOW
+Transformar en el cliente cuando evita duplicar referencias serializadas.
+
+_Ref: https://nextjs.org/docs/app/building-your-application/data-fetching · https://react.dev/reference/react/cache_

package/skills/nextjs-best-practices/references/waterfalls.md

@@ -0,0 +1,41 @@
+# 1. Eliminating Waterfalls (CRITICAL)
+
+El factor #1 de TTFB lento. Operaciones que esperan en serie cuando podrían correr en paralelo.
+
+## 1.5 Promise.all() for Independent Operations — CRITICAL
+```ts
+// ✗ secuencial: 300ms + 300ms
+const user = await getUser(id);
+const posts = await getPosts(id);
+// ✓ paralelo: 300ms
+const [user, posts] = await Promise.all([getUser(id), getPosts(id)]);
+```
+
+## 1.4 Prevent Waterfall Chains in API Routes — CRITICAL
+Iniciar operaciones independientes inmediatamente, await recién al usarlas.
+```ts
+const userP = getUser(id);          // arranca ya
+const settingsP = getSettings(id);  // arranca ya
+return { user: await userP, settings: await settingsP };
+```
+
+## 1.3 Dependency-Based Parallelization — CRITICAL
+Cuando hay dependencias parciales, arrancar cada tarea en el momento más temprano posible (libs como `better-all` lo automatizan). No serializar todo por una sola dependencia.
+
+## 1.7/3.7 Parallel Data Fetching with Component Composition — CRITICAL
+Reestructurar componentes para que fetches independientes corran simultáneamente en vez de anidados.
+
+## 1.6 Strategic Suspense Boundaries — HIGH
+```tsx
+<Suspense fallback={<Skeleton/>}>
+  <SlowData />   {/* streamea; el shell se muestra ya */}
+</Suspense>
+```
+
+## 1.1 Check Cheap Conditions Before Async Flags — HIGH
+Evaluar guards síncronos antes de operaciones async para saltar trabajo en cold paths.
+
+## 1.2 Defer Await Until Needed — HIGH
+Mover el `await` a la rama donde realmente se usa, no bloquear ramas que no lo necesitan.
+
+_Ref: https://react.dev/reference/react/Suspense_

package/skills/nextjs-scaffold/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: nextjs-scaffold
+description: "Scaffold de app Next.js 15+ App Router con TypeScript estricto, shadcn/ui, Tailwind, RSC y estructura production-ready. Usar para iniciar un proyecto Next nuevo o agregar la base de UI."
+category: "frontend"
+argument-hint: "[project-name]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# nextjs-scaffold — Next.js + shadcn/ui Scaffolder
+
+## MANDATORY WORKFLOW
+
+**Antes de generar código, completar en orden.**
+
+### Step 0: Gather Requirements
+Clarificar (o inferir del contexto):
+1. **Nombre del proyecto** (kebab-case)
+2. **Router:** App Router (default) / Pages (legacy)
+3. **Styling:** Tailwind + shadcn/ui (default) / CSS Modules
+4. **Data layer:** Server Actions + RSC (default) / API routes / tRPC
+5. **Auth:** Auth.js (NextAuth) / Clerk / ninguna
+6. **DB:** Postgres + Prisma / Drizzle / ninguna
+7. **Deploy:** Vercel (default) / Docker / self-host
+
+Si ya está especificado, saltar al Step 1.
+
+### Step 1: Crear base
+```bash
+npx create-next-app@latest <name> --ts --app --tailwind --eslint --src-dir --import-alias "@/*"
+cd <name>
+npx shadcn@latest init   # style: default, base color: slate
+```
+
+### Step 2: Estructura
+```
+src/
+  app/                 # App Router: layouts, pages, route handlers
+    (marketing)/       # route groups
+    api/               # route handlers solo si hace falta
+  components/
+    ui/                # shadcn primitives
+  lib/                 # utils, db client, auth
+  server/              # server actions, data access (RSC-only)
+```
+
+### Step 3: Defaults no negociables
+- `tsconfig`: `"strict": true`, `noUncheckedIndexedAccess`
+- **Server Components por defecto**; `'use client'` solo en hojas interactivas
+- `next/image` + `generateMetadata` en cada page
+- Env vars validadas con Zod (`src/lib/env.ts`)
+- ESLint flat config + `@typescript-eslint/no-floating-promises`
+
+### Step 4: Agregar piezas (invocar skills relacionadas)
+- SEO → skill `seo-nextjs`
+- Búsqueda semántica → skill `pgvector-search`
+- Features de IA → skill `ai-sdk-setup`
+- Performance → skill `nextjs-best-practices`
+
+### Step 5: Verificar
+`npm run build` limpio + `npx next lint`. Revisar contra las rules `nextjs-code` y `react-perf`. Build limpio + lint sin errores → scaffold **READY**.
+
+## Stack Defaults
+
+| Componente | Default |
+|------------|---------|
+| Next.js | 15+ App Router |
+| Lenguaje | TypeScript estricto |
+| UI | shadcn/ui + Tailwind |
+| Data | Server Actions + RSC |
+| Validación | Zod |
+| ORM | Prisma |
+| Deploy | Vercel |
+
+---
+
+_Inspirado en `nextjs-shadcn` de [laguagu/claude-code-nextjs-skills](https://github.com/laguagu/claude-code-nextjs-skills). Adaptado al formato Arcane._

package/skills/pgvector-search/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: pgvector-search
+description: "Búsqueda semántica con Postgres + pgvector: embeddings, schema con columna vector, índices HNSW/IVFFlat, queries de similitud y RAG. Usar para implementar semantic search o retrieval sobre Postgres."
+category: "backend"
+argument-hint: "[setup|index|query|rag]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# pgvector-search — Búsqueda semántica con Postgres
+
+## MANDATORY WORKFLOW
+
+**Antes de generar o modificar código/schema, completar estos pasos en orden.**
+
+### Step 0: Gather Requirements
+1. **Modelo de embeddings** y dimensión (ej: OpenAI `text-embedding-3-small` = 1536; Cohere = 1024)
+2. **Volumen** de vectores (define el índice: HNSW para alta recall, IVFFlat para datasets grandes/escritura frecuente)
+3. **Métrica de distancia:** cosine (`<=>`, default para texto) / L2 (`<->`) / inner product (`<#>`)
+4. ¿Es para RAG (retrieval + LLM) o solo ranking de similitud?
+
+### Step 1: Habilitar extensión + schema
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+CREATE TABLE documents (
+  id bigserial PRIMARY KEY,
+  content text NOT NULL,
+  embedding vector(1536) NOT NULL,
+  metadata jsonb
+);
+```
+
+### Step 2: Índice
+```sql
+-- HNSW: mejor recall/latencia, recomendado por defecto
+CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);
+-- IVFFlat (alternativa para datasets muy grandes): definir lists ≈ rows/1000
+```
+
+### Step 3: Insertar embeddings
+Generar el embedding del `content` con el modelo y guardarlo. (Si usás Next + AI SDK, ver skill `ai-sdk-setup`.)
+```ts
+const { embedding } = await embed({ model, value: content });
+await sql`INSERT INTO documents (content, embedding) VALUES (${content}, ${JSON.stringify(embedding)})`;
+```
+
+### Step 4: Query de similitud
+```sql
+SELECT content, 1 - (embedding <=> $1) AS similarity
+FROM documents
+ORDER BY embedding <=> $1   -- usa el índice
+LIMIT 5;
+```
+
+### Step 5: Buenas prácticas
+- **Chunking** del contenido antes de embeddear (no documentos enteros)
+- Filtrar por `metadata` (jsonb) + similitud para hybrid search
+- `SET hnsw.ef_search` para tunear recall vs latencia
+- Re-embeddear si cambia el modelo (la dimensión debe matchear)
+- No mezclar embeddings de modelos distintos en la misma columna
+
+## Cierre
+
+Verificar que el índice se usa (`EXPLAIN ANALYZE` debe mostrar Index Scan, no Seq Scan) y medir recall/latencia con queries reales. Schema + índice + query validados → setup **READY**. Confirmar cambios de schema con el usuario antes de aplicarlos. Siguiente paso: skill `ai-sdk-setup` para generar embeddings, o `database-indexing` para tuning.
+
+---
+
+_Inspirado en `postgres-semantic-search` de [laguagu/claude-code-nextjs-skills](https://github.com/laguagu/claude-code-nextjs-skills). Adaptado al formato Arcane. Relacionado: skill `database-indexing`._

package/skills/seo-nextjs/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: seo-nextjs
+description: "SEO técnico para Next.js App Router: Metadata API, generateMetadata dinámico, sitemap.ts, robots.ts, JSON-LD structured data, Open Graph y canonical. Usar al agregar o auditar SEO en una app Next."
+category: "frontend"
+argument-hint: "[metadata|sitemap|jsonld|audit]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# seo-nextjs — SEO técnico para Next.js
+
+## MANDATORY WORKFLOW
+
+**Antes de generar o modificar código, completar estos pasos en orden.**
+
+### Step 0: Determinar scope
+1. ¿App nueva o auditoría de SEO existente?
+2. ¿Contenido estático, dinámico (DB/CMS) o mixto?
+3. ¿Necesita structured data (JSON-LD) para rich results? (artículos, productos, FAQ, breadcrumbs)
+
+### Step 1: Metadata base (`app/layout.tsx`)
+```ts
+export const metadata: Metadata = {
+  metadataBase: new URL('https://example.com'),
+  title: { default: 'Site', template: '%s · Site' },
+  description: '...',
+  openGraph: { type: 'website', siteName: 'Site', images: ['/og.png'] },
+  twitter: { card: 'summary_large_image' },
+  alternates: { canonical: '/' },
+};
+```
+
+### Step 2: Metadata dinámica (`generateMetadata`)
+```ts
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const post = await getPost(params.slug);
+  return {
+    title: post.title,
+    description: post.excerpt,
+    alternates: { canonical: `/blog/${post.slug}` },
+    openGraph: { images: [post.cover] },
+  };
+}
+```
+Nunca tags `<meta>` manuales en el body — siempre la Metadata API.
+
+### Step 3: sitemap.ts y robots.ts
+```ts
+// app/sitemap.ts
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const posts = await getAllPosts();
+  return [{ url: 'https://example.com', changeFrequency: 'daily' },
+    ...posts.map(p => ({ url: `https://example.com/blog/${p.slug}`, lastModified: p.updatedAt }))];
+}
+// app/robots.ts → reglas + link al sitemap
+```
+
+### Step 4: JSON-LD structured data
+```tsx
+<script type="application/ld+json"
+  dangerouslySetInnerHTML={{ __html: JSON.stringify({
+    '@context': 'https://schema.org', '@type': 'Article',
+    headline: post.title, datePublished: post.date, author: {...} }) }} />
+```
+Validar con Rich Results Test de Google.
+
+### Step 5: Checklist
+- [ ] `metadataBase` seteado (evita URLs OG rotas)
+- [ ] Canonical en cada page indexable
+- [ ] OG image 1200×630 por page importante
+- [ ] sitemap.ts + robots.ts presentes
+- [ ] JSON-LD donde aplique rich result
+- [ ] Sin `noindex` accidental en prod
+- [ ] LCP/CLS sanos (ver skill `nextjs-best-practices`)
+
+## Cierre
+
+Validar el structured data con el Rich Results Test de Google y los meta tags con el inspector del navegador. Si el checklist pasa → SEO **READY**. Confirmar cambios con el usuario antes de escribir. Siguiente paso: skill `nextjs-best-practices` para Web Vitals, o `ai-seo` para estrategia de contenido.
+
+---
+
+_Inspirado en las skills de SEO de [laguagu/claude-code-nextjs-skills](https://github.com/laguagu/claude-code-nextjs-skills). Adaptado al formato Arcane. Relacionado: skill `ai-seo`._