buildanything 1.8.0 → 2.0.0

package/skills/web/lighthouse-ci/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: performance
+description: Optimize web performance for faster loading and better user experience. Use when asked to "speed up my site", "optimize performance", "reduce load time", "fix slow loading", "improve page speed", or "performance audit".
+license: MIT
+metadata:
+  author: web-quality-skills
+  version: "1.0"
+---
+
+# Performance optimization
+
+Deep performance optimization based on Lighthouse performance audits. Focuses on loading speed, runtime efficiency, and resource optimization.
+
+## How it works
+
+1. Identify performance bottlenecks in code and assets
+2. Prioritize by impact on Core Web Vitals
+3. Provide specific optimizations with code examples
+4. Measure improvement with before/after metrics
+
+## Performance budget
+
+| Resource | Budget | Rationale |
+|----------|--------|-----------|
+| Total page weight | < 1.5 MB | 3G loads in ~4s |
+| JavaScript (compressed) | < 300 KB | Parsing + execution time |
+| CSS (compressed) | < 100 KB | Render blocking |
+| Images (above-fold) | < 500 KB | LCP impact |
+| Fonts | < 100 KB | FOIT/FOUT prevention |
+| Third-party | < 200 KB | Uncontrolled latency |
+
+## Critical rendering path
+
+### Server response
+* **TTFB < 800ms.** Time to First Byte should be fast. Use CDN, caching, and efficient backends.
+* **Enable compression.** Gzip or Brotli for text assets. Brotli preferred (15-20% smaller).
+* **HTTP/2 or HTTP/3.** Multiplexing reduces connection overhead.
+* **Edge caching.** Cache HTML at CDN edge when possible.
+
+### Resource loading
+
+**Preconnect to required origins:**
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://cdn.example.com" crossorigin>
+```
+
+**Preload critical resources:**
+```html
+<!-- LCP image -->
+<link rel="preload" href="/hero.webp" as="image" fetchpriority="high">
+
+<!-- Critical font -->
+<link rel="preload" href="/font.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+**Defer non-critical CSS:**
+```html
+<!-- Critical CSS inlined -->
+<style>/* Above-fold styles */</style>
+
+<!-- Non-critical CSS -->
+<link rel="preload" href="/styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
+<noscript><link rel="stylesheet" href="/styles.css"></noscript>
+```
+
+### JavaScript optimization
+
+**Defer non-essential scripts:**
+```html
+<!-- Parser-blocking (avoid) -->
+<script src="/critical.js"></script>
+
+<!-- Deferred (preferred) -->
+<script defer src="/app.js"></script>
+
+<!-- Async (for independent scripts) -->
+<script async src="/analytics.js"></script>
+
+<!-- Module (deferred by default) -->
+<script type="module" src="/app.mjs"></script>
+```
+
+**Code splitting patterns:**
+```javascript
+// Route-based splitting
+const Dashboard = lazy(() => import('./Dashboard'));
+
+// Component-based splitting
+const HeavyChart = lazy(() => import('./HeavyChart'));
+
+// Feature-based splitting
+if (user.isPremium) {
+  const PremiumFeatures = await import('./PremiumFeatures');
+}
+```
+
+**Tree shaking best practices:**
+```javascript
+// ❌ Imports entire library
+import _ from 'lodash';
+_.debounce(fn, 300);
+
+// ✅ Imports only what's needed
+import debounce from 'lodash/debounce';
+debounce(fn, 300);
+```
+
+## Image optimization
+
+### Format selection
+| Format | Use case | Browser support |
+|--------|----------|-----------------|
+| AVIF | Photos, best compression | 92%+ |
+| WebP | Photos, good fallback | 97%+ |
+| PNG | Graphics with transparency | Universal |
+| SVG | Icons, logos, illustrations | Universal |
+
+### Responsive images
+```html
+<picture>
+  <!-- AVIF for modern browsers -->
+  <source 
+    type="image/avif"
+    srcset="hero-400.avif 400w,
+            hero-800.avif 800w,
+            hero-1200.avif 1200w"
+    sizes="(max-width: 600px) 100vw, 50vw">
+  
+  <!-- WebP fallback -->
+  <source 
+    type="image/webp"
+    srcset="hero-400.webp 400w,
+            hero-800.webp 800w,
+            hero-1200.webp 1200w"
+    sizes="(max-width: 600px) 100vw, 50vw">
+  
+  <!-- JPEG fallback -->
+  <img 
+    src="hero-800.jpg"
+    srcset="hero-400.jpg 400w,
+            hero-800.jpg 800w,
+            hero-1200.jpg 1200w"
+    sizes="(max-width: 600px) 100vw, 50vw"
+    width="1200" 
+    height="600"
+    alt="Hero image"
+    loading="lazy"
+    decoding="async">
+</picture>
+```
+
+### LCP image priority
+```html
+<!-- Above-fold LCP image: eager loading, high priority -->
+<img 
+  src="hero.webp" 
+  fetchpriority="high"
+  loading="eager"
+  decoding="sync"
+  alt="Hero">
+
+<!-- Below-fold images: lazy loading -->
+<img 
+  src="product.webp" 
+  loading="lazy"
+  decoding="async"
+  alt="Product">
+```
+
+## Font optimization
+
+### Loading strategy
+```css
+/* System font stack as fallback */
+body {
+  font-family: 'Custom Font', -apple-system, BlinkMacSystemFont, 
+               'Segoe UI', Roboto, sans-serif;
+}
+
+/* Prevent invisible text */
+@font-face {
+  font-family: 'Custom Font';
+  src: url('/fonts/custom.woff2') format('woff2');
+  font-display: swap; /* or optional for non-critical */
+  font-weight: 400;
+  font-style: normal;
+  unicode-range: U+0000-00FF; /* Subset to Latin */
+}
+```
+
+### Preloading critical fonts
+```html
+<link rel="preload" href="/fonts/heading.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+### Variable fonts
+```css
+/* One file instead of multiple weights */
+@font-face {
+  font-family: 'Inter';
+  src: url('/fonts/Inter-Variable.woff2') format('woff2-variations');
+  font-weight: 100 900;
+  font-display: swap;
+}
+```
+
+## Caching strategy
+
+### Cache-Control headers
+```
+# HTML (short or no cache)
+Cache-Control: no-cache, must-revalidate
+
+# Static assets with hash (immutable)
+Cache-Control: public, max-age=31536000, immutable
+
+# Static assets without hash
+Cache-Control: public, max-age=86400, stale-while-revalidate=604800
+
+# API responses
+Cache-Control: private, max-age=0, must-revalidate
+```
+
+### Service worker caching
+```javascript
+// Cache-first for static assets
+self.addEventListener('fetch', (event) => {
+  if (event.request.destination === 'image' ||
+      event.request.destination === 'style' ||
+      event.request.destination === 'script') {
+    event.respondWith(
+      caches.match(event.request).then((cached) => {
+        return cached || fetch(event.request).then((response) => {
+          const clone = response.clone();
+          caches.open('static-v1').then((cache) => cache.put(event.request, clone));
+          return response;
+        });
+      })
+    );
+  }
+});
+```
+
+## Runtime performance
+
+### Avoid layout thrashing
+```javascript
+// ❌ Forces multiple reflows
+elements.forEach(el => {
+  const height = el.offsetHeight; // Read
+  el.style.height = height + 10 + 'px'; // Write
+});
+
+// ✅ Batch reads, then batch writes
+const heights = elements.map(el => el.offsetHeight); // All reads
+elements.forEach((el, i) => {
+  el.style.height = heights[i] + 10 + 'px'; // All writes
+});
+```
+
+### Debounce expensive operations
+```javascript
+function debounce(fn, delay) {
+  let timeout;
+  return (...args) => {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => fn(...args), delay);
+  };
+}
+
+// Debounce scroll/resize handlers
+window.addEventListener('scroll', debounce(handleScroll, 100));
+```
+
+### Use requestAnimationFrame
+```javascript
+// ❌ May cause jank
+setInterval(animate, 16);
+
+// ✅ Synced with display refresh
+function animate() {
+  // Animation logic
+  requestAnimationFrame(animate);
+}
+requestAnimationFrame(animate);
+```
+
+### Virtualize long lists
+```javascript
+// For lists > 100 items, render only visible items
+// Use libraries like react-window, vue-virtual-scroller, or native CSS:
+.virtual-list {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 50px; /* Estimated item height */
+}
+```
+
+## Third-party scripts
+
+### Load strategies
+```javascript
+// ❌ Blocks main thread
+<script src="https://analytics.example.com/script.js"></script>
+
+// ✅ Async loading
+<script async src="https://analytics.example.com/script.js"></script>
+
+// ✅ Delay until interaction
+<script>
+document.addEventListener('DOMContentLoaded', () => {
+  const observer = new IntersectionObserver((entries) => {
+    if (entries[0].isIntersecting) {
+      const script = document.createElement('script');
+      script.src = 'https://widget.example.com/embed.js';
+      document.body.appendChild(script);
+      observer.disconnect();
+    }
+  });
+  observer.observe(document.querySelector('#widget-container'));
+});
+</script>
+```
+
+### Facade pattern
+```html
+<!-- Show static placeholder until interaction -->
+<div class="youtube-facade" 
+     data-video-id="abc123" 
+     onclick="loadYouTube(this)">
+  <img src="/thumbnails/abc123.jpg" alt="Video title">
+  <button aria-label="Play video">▶</button>
+</div>
+```
+
+## Measurement
+
+### Key metrics
+| Metric | Target | Tool |
+|--------|--------|------|
+| LCP | < 2.5s | Lighthouse, CrUX |
+| FCP | < 1.8s | Lighthouse |
+| Speed Index | < 3.4s | Lighthouse |
+| TBT | < 200ms | Lighthouse |
+| TTI | < 3.8s | Lighthouse |
+
+### Testing commands
+```bash
+# Lighthouse CLI
+npx lighthouse https://example.com --output html --output-path report.html
+
+# Web Vitals library
+import {onLCP, onINP, onCLS} from 'web-vitals';
+onLCP(console.log);
+onINP(console.log);
+onCLS(console.log);
+```
+
+## References
+
+For Core Web Vitals specific optimizations, see [Core Web Vitals](../core-web-vitals/SKILL.md).

package/skills/web/mcp-server-patterns/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: mcp-server-patterns
+description: Build MCP servers with Node/TypeScript SDK — tools, resources, prompts, Zod validation, stdio vs Streamable HTTP. Use Context7 or official MCP docs for latest API.
+origin: ECC
+---
+
+# MCP Server Patterns
+
+The Model Context Protocol (MCP) lets AI assistants call tools, read resources, and use prompts from your server. Use this skill when building or maintaining MCP servers. The SDK API evolves; check Context7 (query-docs for "MCP") or the official MCP documentation for current method names and signatures.
+
+For the broader routing decision of when a capability should be a rule, a skill, MCP, or a plain CLI/API workflow, see [docs/capability-surface-selection.md](../../docs/capability-surface-selection.md).
+
+## When to Use
+
+Use when: implementing a new MCP server, adding tools or resources, choosing stdio vs HTTP, upgrading the SDK, or debugging MCP registration and transport issues.
+
+## How It Works
+
+### Core concepts
+
+- **Tools**: Actions the model can invoke (e.g. search, run a command). Register with `registerTool()` or `tool()` depending on SDK version.
+- **Resources**: Read-only data the model can fetch (e.g. file contents, API responses). Register with `registerResource()` or `resource()`. Handlers typically receive a `uri` argument.
+- **Prompts**: Reusable, parameterised prompt templates the client can surface (e.g. in Claude Desktop). Register with `registerPrompt()` or equivalent.
+- **Transport**: stdio for local clients (e.g. Claude Desktop); Streamable HTTP is preferred for remote (Cursor, cloud). Legacy HTTP/SSE is for backward compatibility.
+
+The Node/TypeScript SDK may expose `tool()` / `resource()` or `registerTool()` / `registerResource()`; the official SDK has changed over time. Always verify against the current [MCP docs](https://modelcontextprotocol.io) or Context7.
+
+### Connecting with stdio
+
+For local clients, create a stdio transport and pass it to your server’s connect method. The exact API varies by SDK version (e.g. constructor vs factory). See the official MCP documentation or query Context7 for "MCP stdio server" for the current pattern.
+
+Keep server logic (tools + resources) independent of transport so you can plug in stdio or HTTP in the entrypoint.
+
+### Remote (Streamable HTTP)
+
+For Cursor, cloud, or other remote clients, use **Streamable HTTP** (single MCP HTTP endpoint per current spec). Support legacy HTTP/SSE only when backward compatibility is required.
+
+## Examples
+
+### Install and server setup
+
+```bash
+npm install @modelcontextprotocol/sdk zod
+```
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+```
+
+Register tools and resources using the API your SDK version provides: some versions use `server.tool(name, description, schema, handler)` (positional args), others use `server.tool({ name, description, inputSchema }, handler)` or `registerTool()`. Same for resources — include a `uri` in the handler when the API provides it. Check the official MCP docs or Context7 for the current `@modelcontextprotocol/sdk` signatures to avoid copy-paste errors.
+
+Use **Zod** (or the SDK’s preferred schema format) for input validation.
+
+## Best Practices
+
+- **Schema first**: Define input schemas for every tool; document parameters and return shape.
+- **Errors**: Return structured errors or messages the model can interpret; avoid raw stack traces.
+- **Idempotency**: Prefer idempotent tools where possible so retries are safe.
+- **Rate and cost**: For tools that call external APIs, consider rate limits and cost; document in the tool description.
+- **Versioning**: Pin SDK version in package.json; check release notes when upgrading.
+
+## Official SDKs and Docs
+
+- **JavaScript/TypeScript**: `@modelcontextprotocol/sdk` (npm). Use Context7 with library name "MCP" for current registration and transport patterns.
+- **Go**: Official Go SDK on GitHub (`modelcontextprotocol/go-sdk`).
+- **C#**: Official C# SDK for .NET.

package/skills/web/next-best-practices/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: next-best-practices
+description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
+user-invocable: false
+---
+
+# Next.js Best Practices
+
+Apply these rules when writing or reviewing Next.js code.
+
+## File Conventions
+
+See [file-conventions.md](./file-conventions.md) for:
+- Project structure and special files
+- Route segments (dynamic, catch-all, groups)
+- Parallel and intercepting routes
+- Middleware rename in v16 (middleware → proxy)
+
+## RSC Boundaries
+
+Detect invalid React Server Component patterns.
+
+See [rsc-boundaries.md](./rsc-boundaries.md) for:
+- Async client component detection (invalid)
+- Non-serializable props detection
+- Server Action exceptions
+
+## Async Patterns
+
+Next.js 15+ async API changes.
+
+See [async-patterns.md](./async-patterns.md) for:
+- Async `params` and `searchParams`
+- Async `cookies()` and `headers()`
+- Migration codemod
+
+## Runtime Selection
+
+See [runtime-selection.md](./runtime-selection.md) for:
+- Default to Node.js runtime
+- When Edge runtime is appropriate
+
+## Directives
+
+See [directives.md](./directives.md) for:
+- `'use client'`, `'use server'` (React)
+- `'use cache'` (Next.js)
+
+## Functions
+
+See [functions.md](./functions.md) for:
+- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
+- Server functions: `cookies`, `headers`, `draftMode`, `after`
+- Generate functions: `generateStaticParams`, `generateMetadata`
+
+## Error Handling
+
+See [error-handling.md](./error-handling.md) for:
+- `error.tsx`, `global-error.tsx`, `not-found.tsx`
+- `redirect`, `permanentRedirect`, `notFound`
+- `forbidden`, `unauthorized` (auth errors)
+- `unstable_rethrow` for catch blocks
+
+## Data Patterns
+
+See [data-patterns.md](./data-patterns.md) for:
+- Server Components vs Server Actions vs Route Handlers
+- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
+- Client component data fetching
+
+## Route Handlers
+
+See [route-handlers.md](./route-handlers.md) for:
+- `route.ts` basics
+- GET handler conflicts with `page.tsx`
+- Environment behavior (no React DOM)
+- When to use vs Server Actions
+
+## Metadata & OG Images
+
+See [metadata.md](./metadata.md) for:
+- Static and dynamic metadata
+- `generateMetadata` function
+- OG image generation with `next/og`
+- File-based metadata conventions
+
+## Image Optimization
+
+See [image.md](./image.md) for:
+- Always use `next/image` over `<img>`
+- Remote images configuration
+- Responsive `sizes` attribute
+- Blur placeholders
+- Priority loading for LCP
+
+## Font Optimization
+
+See [font.md](./font.md) for:
+- `next/font` setup
+- Google Fonts, local fonts
+- Tailwind CSS integration
+- Preloading subsets
+
+## Bundling
+
+See [bundling.md](./bundling.md) for:
+- Server-incompatible packages
+- CSS imports (not link tags)
+- Polyfills (already included)
+- ESM/CommonJS issues
+- Bundle analysis
+
+## Scripts
+
+See [scripts.md](./scripts.md) for:
+- `next/script` vs native script tags
+- Inline scripts need `id`
+- Loading strategies
+- Google Analytics with `@next/third-parties`
+
+## Hydration Errors
+
+See [hydration-error.md](./hydration-error.md) for:
+- Common causes (browser APIs, dates, invalid HTML)
+- Debugging with error overlay
+- Fixes for each cause
+
+## Suspense Boundaries
+
+See [suspense-boundaries.md](./suspense-boundaries.md) for:
+- CSR bailout with `useSearchParams` and `usePathname`
+- Which hooks require Suspense boundaries
+
+## Parallel & Intercepting Routes
+
+See [parallel-routes.md](./parallel-routes.md) for:
+- Modal patterns with `@slot` and `(.)` interceptors
+- `default.tsx` for fallbacks
+- Closing modals correctly with `router.back()`
+
+## Self-Hosting
+
+See [self-hosting.md](./self-hosting.md) for:
+- `output: 'standalone'` for Docker
+- Cache handlers for multi-instance ISR
+- What works vs needs extra setup
+
+## Debug Tricks
+
+See [debug-tricks.md](./debug-tricks.md) for:
+- MCP endpoint for AI-assisted debugging
+- Rebuild specific routes with `--debug-build-paths`
+

package/skills/web/next-best-practices/async-patterns.md

@@ -0,0 +1,87 @@
+# Async Patterns
+
+In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.
+
+## Async Params and SearchParams
+
+Always type them as `Promise<...>` and await them.
+
+### Pages and Layouts
+
+```tsx
+type Props = { params: Promise<{ slug: string }> }
+
+export default async function Page({ params }: Props) {
+  const { slug } = await params
+}
+```
+
+### Route Handlers
+
+```tsx
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params
+}
+```
+
+### SearchParams
+
+```tsx
+type Props = {
+  params: Promise<{ slug: string }>
+  searchParams: Promise<{ query?: string }>
+}
+
+export default async function Page({ params, searchParams }: Props) {
+  const { slug } = await params
+  const { query } = await searchParams
+}
+```
+
+### Synchronous Components
+
+Use `React.use()` for non-async components:
+
+```tsx
+import { use } from 'react'
+
+type Props = { params: Promise<{ slug: string }> }
+
+export default function Page({ params }: Props) {
+  const { slug } = use(params)
+}
+```
+
+### generateMetadata
+
+```tsx
+type Props = { params: Promise<{ slug: string }> }
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params
+  return { title: slug }
+}
+```
+
+## Async Cookies and Headers
+
+```tsx
+import { cookies, headers } from 'next/headers'
+
+export default async function Page() {
+  const cookieStore = await cookies()
+  const headersList = await headers()
+
+  const theme = cookieStore.get('theme')
+  const userAgent = headersList.get('user-agent')
+}
+```
+
+## Migration Codemod
+
+```bash
+npx @next/codemod@latest next-async-request-api .
+```