devskill 2.0.6 → 2.0.8

package/skills/napkin/assets/step5-response.svg

@@ -0,0 +1,112 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="800" height="480" viewBox="0 0 800 480">
+  <defs>
+    <linearGradient id="termBg5" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#2D2B55"/>
+      <stop offset="100%" stop-color="#1E1B3A"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Background -->
+  <rect width="800" height="480" rx="12" fill="#F8FAFB"/>
+
+  <!-- Step indicator -->
+  <circle cx="46" cy="28" r="16" fill="#0D9488"/>
+  <text x="46" y="33" text-anchor="middle" font-family="Arial, Helvetica, sans-serif" font-size="14" font-weight="bold" fill="white">5</text>
+  <text x="72" y="33" font-family="Arial, Helvetica, sans-serif" font-size="15" font-weight="bold" fill="#334155">Copilot reads your napkin and responds</text>
+
+  <!-- Terminal Window -->
+  <g transform="translate(40, 55)">
+    <!-- Terminal chrome -->
+    <rect width="550" height="370" rx="10" fill="#1E1B3A" stroke="#3D3A5C" stroke-width="1"/>
+    <!-- Title bar -->
+    <rect width="550" height="36" rx="10" fill="#2D2B55"/>
+    <rect x="0" y="26" width="550" height="10" fill="#2D2B55"/>
+    <!-- Window buttons -->
+    <circle cx="20" cy="18" r="6" fill="#FF5F57"/>
+    <circle cx="40" cy="18" r="6" fill="#FFBD2E"/>
+    <circle cx="60" cy="18" r="6" fill="#28C840"/>
+    <text x="275" y="22" text-anchor="middle" font-family="Arial, Helvetica, sans-serif" font-size="12" fill="#8B87B0">Terminal</text>
+
+    <!-- User prompt -->
+    <text x="20" y="62" font-family="monospace" font-size="13" fill="#0D9488">&#x276F;</text>
+    <text x="36" y="62" font-family="monospace" font-size="13" fill="#E0DEF4">check the napkin</text>
+
+    <!-- Loading indicator -->
+    <text x="20" y="88" font-family="monospace" font-size="13" fill="#0D9488">&#x2713;</text>
+    <text x="36" y="88" font-family="monospace" font-size="13" fill="#A5F3FC">Reading your napkin...</text>
+
+    <!-- Copilot response header -->
+    <text x="20" y="120" font-family="monospace" font-size="13" fill="#C4B5FD">Copilot</text>
+
+    <!-- Response content - warm, conversational -->
+    <text x="20" y="148" font-family="monospace" font-size="12" fill="#E0DEF4">I can see your sketch! Here's what I'm picking up:</text>
+
+    <!-- Response body -->
+    <text x="20" y="178" font-family="monospace" font-size="12" fill="#E0DEF4">You've drawn a three-stage workflow:</text>
+    <text x="20" y="200" font-family="monospace" font-size="12" fill="#A5F3FC">  Draft</text>
+    <text x="80" y="200" font-family="monospace" font-size="12" fill="#64748B">&#x2192;</text>
+    <text x="100" y="200" font-family="monospace" font-size="12" fill="#A5F3FC">Review</text>
+    <text x="165" y="200" font-family="monospace" font-size="12" fill="#64748B">&#x2192;</text>
+    <text x="185" y="200" font-family="monospace" font-size="12" fill="#A5F3FC">Ship</text>
+
+    <text x="20" y="228" font-family="monospace" font-size="12" fill="#E0DEF4">Your sticky notes highlight some key items:</text>
+
+    <!-- Sticky note references -->
+    <text x="20" y="254" font-family="monospace" font-size="12" fill="#FBBF24">&#x25A0;</text>
+    <text x="36" y="254" font-family="monospace" font-size="12" fill="#FEF3C7">"Need legal review" — before the Ship phase</text>
+    <text x="20" y="276" font-family="monospace" font-size="12" fill="#F472B6">&#x25A0;</text>
+    <text x="36" y="276" font-family="monospace" font-size="12" fill="#FCE7F3">"Q2 deadline" — June 30th</text>
+    <text x="20" y="298" font-family="monospace" font-size="12" fill="#60A5FA">&#x25A0;</text>
+    <text x="36" y="298" font-family="monospace" font-size="12" fill="#DBEAFE">"Check with Sarah" — re: compliance</text>
+
+    <text x="20" y="328" font-family="monospace" font-size="12" fill="#E0DEF4">It looks like you're planning a review workflow</text>
+    <text x="20" y="348" font-family="monospace" font-size="12" fill="#E0DEF4">with a legal gate. Would you like me to help you</text>
+    <text x="20" y="368" font-family="monospace" font-size="12" fill="#E0DEF4">turn this into a checklist or project plan?</text>
+
+    <!-- Cursor -->
+    <rect x="20" y="385" width="8" height="14" fill="#0D9488" opacity="0.8"/>
+  </g>
+
+  <!-- Annotation callout -->
+  <g transform="translate(608, 75)">
+    <rect width="170" height="84" rx="10" fill="#0D9488" opacity="0.1"/>
+    <text x="85" y="24" text-anchor="middle" font-family="Arial, Helvetica, sans-serif" font-size="11" fill="#0D9488" font-weight="bold">Copilot sees your</text>
+    <text x="85" y="42" text-anchor="middle" font-family="Arial, Helvetica, sans-serif" font-size="11" fill="#0D9488" font-weight="bold">drawings and text,</text>
+    <text x="85" y="60" text-anchor="middle" font-family="Arial, Helvetica, sans-serif" font-size="11" fill="#0D9488" font-weight="bold">then responds in</text>
+    <text x="85" y="78" text-anchor="middle" font-family="Arial, Helvetica, sans-serif" font-size="11" fill="#0D9488" font-weight="bold">plain English</text>
+  </g>
+  <!-- Arrow from annotation to terminal content -->
+  <path d="M608,130 C598,140 596,150 594,160" fill="none" stroke="#0D9488" stroke-width="1.5" stroke-dasharray="4,3"/>
+  <polygon points="590,158 594,166 598,158" fill="#0D9488"/>
+
+  <!-- What Copilot understood panel -->
+  <g transform="translate(608, 190)">
+    <rect width="170" height="230" rx="10" fill="white" stroke="#E2E8F0" stroke-width="1"/>
+    <text x="85" y="24" text-anchor="middle" font-family="Arial, Helvetica, sans-serif" font-size="11" font-weight="bold" fill="#334155">What Copilot understood:</text>
+    <line x1="15" y1="34" x2="155" y2="34" stroke="#E2E8F0" stroke-width="1"/>
+
+    <!-- Mini flowchart icon -->
+    <rect x="15" y="48" width="14" height="14" rx="2" fill="#F0FDFA" stroke="#0D9488" stroke-width="1"/>
+    <text x="35" y="59" font-family="Arial, Helvetica, sans-serif" font-size="10" fill="#475569">3-stage workflow</text>
+
+    <!-- Sticky note icon -->
+    <rect x="15" y="74" width="14" height="14" rx="1" fill="#FEF9C3" stroke="#F59E0B" stroke-width="0.8"/>
+    <text x="35" y="85" font-family="Arial, Helvetica, sans-serif" font-size="10" fill="#475569">Legal review needed</text>
+
+    <!-- Calendar icon -->
+    <rect x="15" y="100" width="14" height="14" rx="2" fill="#FCE7F3" stroke="#EC4899" stroke-width="0.8"/>
+    <text x="35" y="111" font-family="Arial, Helvetica, sans-serif" font-size="10" fill="#475569">Q2 deadline (June 30)</text>
+
+    <!-- Person icon -->
+    <rect x="15" y="126" width="14" height="14" rx="2" fill="#DBEAFE" stroke="#3B82F6" stroke-width="0.8"/>
+    <text x="35" y="137" font-family="Arial, Helvetica, sans-serif" font-size="10" fill="#475569">Follow up with Sarah</text>
+
+    <!-- Annotation icon -->
+    <rect x="15" y="152" width="14" height="14" rx="7" fill="#FEE2E2" stroke="#EF4444" stroke-width="0.8"/>
+    <text x="35" y="163" font-family="Arial, Helvetica, sans-serif" font-size="10" fill="#475569">Review step = priority</text>
+
+    <line x1="15" y1="180" x2="155" y2="180" stroke="#E2E8F0" stroke-width="1"/>
+    <text x="85" y="200" text-anchor="middle" font-family="Arial, Helvetica, sans-serif" font-size="10" fill="#0D9488" font-weight="bold">Everything from your</text>
+    <text x="85" y="216" text-anchor="middle" font-family="Arial, Helvetica, sans-serif" font-size="10" fill="#0D9488" font-weight="bold">napkin — captured!</text>
+  </g>
+</svg>

package/skills/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/next-best-practices/SYNC.md

@@ -0,0 +1,5 @@
+# Sync Info
+
+- **Source:** `vendor/next-skills/skills/next-best-practices`
+- **Git SHA:** `038954e07bfc313e97fa5f6ff7caf87226e4a782`
+- **Synced:** 2026-03-24

package/skills/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 .
+```

package/skills/next-best-practices/bundling.md

@@ -0,0 +1,180 @@
+# Bundling
+
+Fix common bundling issues with third-party packages.
+
+## Server-Incompatible Packages
+
+Some packages use browser APIs (`window`, `document`, `localStorage`) and fail in Server Components.
+
+### Error Signs
+
+```
+ReferenceError: window is not defined
+ReferenceError: document is not defined
+ReferenceError: localStorage is not defined
+Module not found: Can't resolve 'fs'
+```
+
+### Solution 1: Mark as Client-Only
+
+If the package is only needed on client:
+
+```tsx
+// Bad: Fails - package uses window
+import SomeChart from 'some-chart-library'
+
+export default function Page() {
+  return <SomeChart />
+}
+
+// Good: Use dynamic import with ssr: false
+import dynamic from 'next/dynamic'
+
+const SomeChart = dynamic(() => import('some-chart-library'), {
+  ssr: false,
+})
+
+export default function Page() {
+  return <SomeChart />
+}
+```
+
+### Solution 2: Externalize from Server Bundle
+
+For packages that should run on server but have bundling issues:
+
+```js
+// next.config.js
+module.exports = {
+  serverExternalPackages: ['problematic-package'],
+}
+```
+
+Use this for:
+- Packages with native bindings (sharp, bcrypt)
+- Packages that don't bundle well (some ORMs)
+- Packages with circular dependencies
+
+### Solution 3: Client Component Wrapper
+
+Wrap the entire usage in a client component:
+
+```tsx
+// components/ChartWrapper.tsx
+'use client'
+
+import { Chart } from 'chart-library'
+
+export function ChartWrapper(props) {
+  return <Chart {...props} />
+}
+
+// app/page.tsx (server component)
+import { ChartWrapper } from '@/components/ChartWrapper'
+
+export default function Page() {
+  return <ChartWrapper data={data} />
+}
+```
+
+## CSS Imports
+
+Import CSS files instead of using `<link>` tags. Next.js handles bundling and optimization.
+
+```tsx
+// Bad: Manual link tag
+<link rel="stylesheet" href="/styles.css" />
+
+// Good: Import CSS
+import './styles.css'
+
+// Good: CSS Modules
+import styles from './Button.module.css'
+```
+
+## Polyfills
+
+Next.js includes common polyfills automatically. Don't load redundant ones from polyfill.io or similar CDNs.
+
+Already included: `Array.from`, `Object.assign`, `Promise`, `fetch`, `Map`, `Set`, `Symbol`, `URLSearchParams`, and 50+ others.
+
+```tsx
+// Bad: Redundant polyfills
+<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch,Promise,Array.from" />
+
+// Good: Next.js includes these automatically
+```
+
+## ESM/CommonJS Issues
+
+### Error Signs
+
+```
+SyntaxError: Cannot use import statement outside a module
+Error: require() of ES Module
+Module not found: ESM packages need to be imported
+```
+
+### Solution: Transpile Package
+
+```js
+// next.config.js
+module.exports = {
+  transpilePackages: ['some-esm-package', 'another-package'],
+}
+```
+
+## Common Problematic Packages
+
+| Package | Issue | Solution |
+|---------|-------|----------|
+| `sharp` | Native bindings | `serverExternalPackages: ['sharp']` |
+| `bcrypt` | Native bindings | `serverExternalPackages: ['bcrypt']` or use `bcryptjs` |
+| `canvas` | Native bindings | `serverExternalPackages: ['canvas']` |
+| `recharts` | Uses window | `dynamic(() => import('recharts'), { ssr: false })` |
+| `react-quill` | Uses document | `dynamic(() => import('react-quill'), { ssr: false })` |
+| `mapbox-gl` | Uses window | `dynamic(() => import('mapbox-gl'), { ssr: false })` |
+| `monaco-editor` | Uses window | `dynamic(() => import('@monaco-editor/react'), { ssr: false })` |
+| `lottie-web` | Uses document | `dynamic(() => import('lottie-react'), { ssr: false })` |
+
+## Bundle Analysis
+
+Analyze bundle size with the built-in analyzer (Next.js 16.1+):
+
+```bash
+next experimental-analyze
+```
+
+This opens an interactive UI to:
+- Filter by route, environment (client/server), and type
+- Inspect module sizes and import chains
+- View treemap visualization
+
+Save output for comparison:
+
+```bash
+next experimental-analyze --output
+# Output saved to .next/diagnostics/analyze
+```
+
+Reference: https://nextjs.org/docs/app/guides/package-bundling
+
+## Migrating from Webpack to Turbopack
+
+Turbopack is the default bundler in Next.js 15+. If you have custom webpack config, migrate to Turbopack-compatible alternatives:
+
+```js
+// next.config.js
+module.exports = {
+  // Good: Works with Turbopack
+  serverExternalPackages: ['package'],
+  transpilePackages: ['package'],
+
+  // Bad: Webpack-only - migrate away from this
+  webpack: (config) => {
+    // custom webpack config
+  },
+}
+```
+
+Reference: https://nextjs.org/docs/app/building-your-application/upgrading/from-webpack-to-turbopack