claude-code-arcane 1.0.0 → 1.1.0

package/skills/nestjs-best-practices/references/performance.md

@@ -0,0 +1,32 @@
+# 5. Performance (HIGH)
+
+## 5.3 Optimize Database Queries — HIGH
+
+Seleccionar solo columnas necesarias, índices apropiados, no over-fetch de relaciones.
+```ts
+// Prisma: select explícito en vez de traer la fila entera + relaciones
+prisma.user.findMany({ select: { id: true, email: true } });
+```
+
+## 5.4 Use Caching Strategically — HIGH
+
+Cachear operaciones caras con TTL apropiado e invalidación basada en eventos.
+```ts
+@UseInterceptors(CacheInterceptor)
+@CacheTTL(30)
+@Get('stats') getStats() { /* ... */ }
+```
+
+## 5.1 Async Lifecycle Hooks Correctly — HIGH
+
+Retornar promesas de hooks async; constructores síncronos (no bloquear el arranque).
+```ts
+async onModuleInit() { await this.warmupCache(); } // ✓
+// constructor(){ await ... }  ✗ no se puede / bloquea
+```
+
+## 5.2 Lazy Loading for Large Modules — MEDIUM
+
+Diferir inicialización de módulos poco usados con `LazyModuleLoader` → menor tiempo de arranque y memoria.
+
+_Ref: https://docs.nestjs.com/techniques/caching · https://docs.nestjs.com/fundamentals/lazy-loading-modules_

package/skills/nestjs-best-practices/references/security.md

@@ -0,0 +1,50 @@
+# 4. Security (HIGH)
+
+## 4.1 Secure JWT Authentication — CRITICAL
+
+Tokens de vida corta (15m) + refresh tokens. Secreto en env/secret manager. Nunca data sensible en el payload.
+```ts
+JwtModule.register({
+  secret: process.env.JWT_SECRET,        // nunca hardcodeado
+  signOptions: { expiresIn: '15m' },
+});
+// payload: { sub: userId, role }  ← nada de passwords, emails completos, PII
+```
+
+## 4.5 Validate All Input with DTOs and Pipes — HIGH
+
+`ValidationPipe` global + DTOs decorados. Rechazar input malformado antes de procesarlo.
+```ts
+app.useGlobalPipes(new ValidationPipe({
+  whitelist: true,            // descarta props no declaradas
+  forbidNonWhitelisted: true, // 400 si vienen props extra
+  transform: true,
+}));
+
+export class CreateUserDto {
+  @IsEmail() email: string;
+  @MinLength(8) password: string;
+}
+```
+
+## 4.4 Use Guards for AuthN/AuthZ — HIGH
+
+Guards declarativos, no checks manuales en cada handler.
+```ts
+@UseGuards(JwtAuthGuard, RolesGuard)
+@Roles('admin')
+@Get('users') findAll() { /* ... */ }
+```
+
+## 4.2 Rate Limiting — HIGH
+
+`@nestjs/throttler`, límites por endpoint (login más estricto que lecturas).
+```ts
+@Throttle({ default: { limit: 5, ttl: 60000 } }) // 5/min en /login
+```
+
+## 4.3 Sanitize Output to Prevent XSS — HIGH
+
+Sanitizar contenido generado por usuario antes de almacenar; `Content-Type` correcto en respuestas.
+
+_Ref: https://docs.nestjs.com/security/authentication · https://docs.nestjs.com/security/rate-limiting_

package/skills/nestjs-best-practices/references/testing.md

@@ -0,0 +1,32 @@
+# 6. Testing (MEDIUM-HIGH)
+
+## 6.3 Use Testing Module for Unit Tests — HIGH
+
+Entorno aislado con `Test.createTestingModule` y dependencias mockeadas.
+```ts
+const moduleRef = await Test.createTestingModule({
+  providers: [
+    OrdersService,
+    { provide: UserRepository, useValue: mockUserRepo },
+  ],
+}).compile();
+const service = moduleRef.get(OrdersService);
+```
+
+## 6.2 Mock External Services in Tests — HIGH
+
+Nunca llamar APIs o DBs reales en tests. Mockear todas las dependencias externas con escenarios realistas (éxito, error, timeout).
+
+## 6.1 Use Supertest for E2E Testing — HIGH
+
+Probar el ciclo completo request/response incluyendo middleware, guards y pipes. Setup/teardown apropiados.
+```ts
+const app = moduleRef.createNestApplication();
+await app.init();
+await request(app.getHttpServer())
+  .post('/users').send({ email: 'a@b.com', password: 'secret123' })
+  .expect(201);
+await app.close();
+```
+
+_Ref: https://docs.nestjs.com/fundamentals/testing_

package/skills/nestjs-scaffold/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: nestjs-scaffold
+description: "Scaffold de API NestJS production-ready con módulos por feature, DI, ValidationPipe global, Prisma/Drizzle, guards de auth y testing. Usar para iniciar un backend NestJS nuevo."
+category: "backend"
+argument-hint: "[project-name]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# nestjs-scaffold — NestJS API Scaffolder
+
+## MANDATORY WORKFLOW
+
+**Antes de generar cualquier código, completar estos pasos en orden.**
+
+### Step 0: Gather Requirements
+1. **Nombre del servicio** (kebab-case)
+2. **Transport:** REST (default) / GraphQL / microservicio
+3. **ORM:** Prisma (default) / Drizzle / TypeORM
+4. **DB:** PostgreSQL (default) / MySQL
+5. **Auth:** JWT + refresh (default) / OAuth / ninguna
+6. **Deploy:** Docker (default) / Railway / AWS ECS
+
+### Step 1: Crear base
+```bash
+npm i -g @nestjs/cli
+nest new <name> --package-manager pnpm
+cd <name>
+nest g module users && nest g controller users && nest g service users
+```
+
+### Step 2: Estructura (feature modules — NO por capa)
+```
+src/
+  users/   { users.module.ts, users.controller.ts, users.service.ts, dto/, entities/ }
+  auth/    { auth.module.ts, jwt.strategy.ts, guards/, decorators/ }
+  common/  { filters/, interceptors/, pipes/ }
+  config/  { config.module.ts, env.validation.ts }
+  main.ts
+```
+
+### Step 3: Bootstrap no negociable (`main.ts`)
+```ts
+app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }));
+app.useGlobalFilters(new AllExceptionsFilter());
+app.enableShutdownHooks();           // graceful shutdown
+app.enableVersioning({ type: VersioningType.URI });
+```
+
+### Step 4: Defaults
+- Constructor injection siempre; cero `ModuleRef.get()` en runtime
+- DTOs decorados (`class-validator`) en todos los endpoints
+- Guards declarativos para auth/authz
+- `ConfigModule` con validación de env (Joi/Zod) al boot
+- Migraciones versionadas, `synchronize: false`
+- Health check (`@nestjs/terminus`) + structured logging (pino)
+- Tests: `Test.createTestingModule` (unit) + supertest (e2e)
+
+### Step 5: Verificar
+`npm run build` + `npm run test`. Revisar contra la rule `nestjs-code` y el skill `nestjs-best-practices`. Build + tests verdes → scaffold **READY**.
+
+## Stack Defaults
+
+| Componente | Default |
+|------------|---------|
+| Framework | NestJS 10+ |
+| ORM | Prisma |
+| DB | PostgreSQL |
+| Auth | JWT + refresh tokens |
+| Validación | class-validator + ValidationPipe |
+| Testing | Jest + supertest |
+| Deploy | Docker |
+
+---
+
+_Inspirado en las skills NestJS de [kadajett/agent-nestjs-skills](https://github.com/kadajett/agent-nestjs-skills) y [giuseppe-trisciuoglio/developer-kit](https://github.com/giuseppe-trisciuoglio/developer-kit). Adaptado al formato Arcane._

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._