@su-record/vibe 2.7.11 → 2.7.13

package/skills/ui-ux-pro-max/SKILL.md

@@ -1,206 +1,206 @@
----
-name: ui-ux-pro-max
-description: "UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples."
----
-
-# UI/UX Pro Max - Design Intelligence
-
-Searchable database: 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, 25 chart types across 9 stacks.
-
-## Pre-check (K1)
-
-> Does this project need custom UI/UX design? If using a pre-built template or admin framework (e.g., Retool, Vercel templates), skip this skill.
-
-## Rule Categories by Priority
-
-| Priority | Category | Impact | Domain |
-|----------|----------|--------|--------|
-| 1 | Accessibility | CRITICAL | `ux` |
-| 2 | Touch & Interaction | CRITICAL | `ux` |
-| 3 | Performance | HIGH | `ux` |
-| 4 | Layout & Responsive | HIGH | `ux` |
-| 5 | Typography & Color | MEDIUM | `typography`, `color` |
-| 6 | Animation | MEDIUM | `ux` |
-| 7 | Style Selection | MEDIUM | `style`, `product` |
-| 8 | Charts & Data | LOW | `chart` |
-
-## Quick Reference
-
-### 1. Accessibility (CRITICAL)
-
-- `color-contrast` - Minimum 4.5:1 ratio for normal text
-- `focus-states` - Visible focus rings on interactive elements
-- `alt-text` - Descriptive alt text for meaningful images
-- `aria-labels` - aria-label for icon-only buttons
-- `keyboard-nav` - Tab order matches visual order
-- `form-labels` - Use label with for attribute
-
-### 2. Touch & Interaction (CRITICAL)
-
-- `touch-target-size` - Minimum 44x44px touch targets
-- `hover-vs-tap` - Use click/tap for primary interactions
-- `loading-buttons` - Disable button during async operations
-- `error-feedback` - Clear error messages near problem
-- `cursor-pointer` - Add cursor-pointer to clickable elements
-
-### 3. Performance (HIGH)
-
-- `image-optimization` - Use WebP, srcset, lazy loading
-- `reduced-motion` - Check prefers-reduced-motion
-- `content-jumping` - Reserve space for async content
-
-### 4. Layout & Responsive (HIGH)
-
-- `viewport-meta` - width=device-width initial-scale=1
-- `readable-font-size` - Minimum 16px body text on mobile
-- `horizontal-scroll` - Ensure content fits viewport width
-- `z-index-management` - Define z-index scale (10, 20, 30, 50)
-
-### 5. Typography & Color (MEDIUM)
-
-- `line-height` - Use 1.5-1.75 for body text
-- `line-length` - Limit to 65-75 characters per line
-- `font-pairing` - Match heading/body font personalities
-
-### 6. Animation (MEDIUM)
-
-- `duration-timing` - Use 150-300ms for micro-interactions
-- `transform-performance` - Use transform/opacity, not width/height
-- `loading-states` - Skeleton screens or spinners
-
-### 7. Style Selection (MEDIUM)
-
-- `style-match` - Match style to product type
-- `consistency` - Use same style across all pages
-- `no-emoji-icons` - Use SVG icons, not emojis
-
-### 8. Charts & Data (LOW)
-
-- `chart-type` - Match chart type to data type
-- `color-guidance` - Use accessible color palettes
-- `data-table` - Provide table alternative for accessibility
-
----
-
-## How to Use
-
-### Step 1: Analyze Requirements
-
-Extract from user request: **product type**, **style keywords**, **industry**, **stack** (default: html-tailwind).
-
-### Step 2: Generate Design System (REQUIRED)
-
-```bash
-python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
-```
-
-This searches 5 domains in parallel (product, style, color, landing, typography), applies reasoning rules, and returns complete design system.
-
-**Persist for cross-session use:**
-```bash
-python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
-```
-
-Creates `design-system/MASTER.md` (global) + optional `design-system/pages/<page>.md` (overrides).
-
-**With page-specific override:**
-```bash
-python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Name" --page "dashboard"
-```
-
-**Hierarchical retrieval**: Page file overrides Master. No page file → Master exclusively.
-
-### Step 3: Detailed Searches (as needed)
-
-```bash
-python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
-```
-
-Domains: `product`, `style`, `typography`, `color`, `landing`, `chart`, `ux`, `react`, `web`, `prompt`
-
-### Step 4: Stack Guidelines (default: html-tailwind)
-
-```bash
-python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind
-```
-
-Stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose`
-
----
-
-## Common Rules for Professional UI
-
-### Icons & Visual Elements
-
-| Rule | Do | Don't |
-|------|----|----- |
-| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis as UI icons |
-| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout |
-| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths |
-| **Consistent icon sizing** | Fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes |
-
-### Interaction & Cursor
-
-| Rule | Do | Don't |
-|------|----|----- |
-| **Cursor pointer** | `cursor-pointer` on all clickable elements | Default cursor on interactive elements |
-| **Hover feedback** | Visual feedback (color, shadow, border) | No indication element is interactive |
-| **Smooth transitions** | `transition-colors duration-200` | Instant changes or >500ms |
-
-### Light/Dark Mode Contrast
-
-| Rule | Do | Don't |
-|------|----|----- |
-| **Glass card light mode** | `bg-white/80` or higher opacity | `bg-white/10` (too transparent) |
-| **Text contrast light** | `#0F172A` (slate-900) for text | `#94A3B8` (slate-400) for body |
-| **Muted text light** | `#475569` (slate-600) minimum | gray-400 or lighter |
-| **Border visibility** | `border-gray-200` in light mode | `border-white/10` (invisible) |
-
-### Layout & Spacing
-
-| Rule | Do | Don't |
-|------|----|----- |
-| **Floating navbar** | `top-4 left-4 right-4` spacing | Stick to `top-0 left-0 right-0` |
-| **Content padding** | Account for fixed navbar height | Content hidden behind fixed elements |
-| **Consistent max-width** | Same `max-w-6xl` or `max-w-7xl` | Mix different container widths |
-
----
-
-## Pre-Delivery Checklist
-
-### Visual Quality
-- [ ] No emojis used as icons (SVG instead)
-- [ ] All icons from consistent set (Heroicons/Lucide)
-- [ ] Brand logos verified (Simple Icons)
-- [ ] Hover states don't cause layout shift
-
-### Interaction
-- [ ] All clickable elements have `cursor-pointer`
-- [ ] Hover states provide clear visual feedback
-- [ ] Transitions are smooth (150-300ms)
-- [ ] Focus states visible for keyboard navigation
-
-### Light/Dark Mode
-- [ ] Light mode text has sufficient contrast (4.5:1)
-- [ ] Glass/transparent elements visible in light mode
-- [ ] Borders visible in both modes
-- [ ] Both modes tested before delivery
-
-### Layout
-- [ ] Floating elements have proper edge spacing
-- [ ] No content hidden behind fixed navbars
-- [ ] Responsive at 375px, 768px, 1024px, 1440px
-- [ ] No horizontal scroll on mobile
-
-### Accessibility
-- [ ] All images have alt text
-- [ ] Form inputs have labels
-- [ ] Color is not the only indicator
-- [ ] `prefers-reduced-motion` respected
-
-## Done Criteria (K4)
-
-- [ ] Design system generated before implementation
-- [ ] All pre-delivery checklist items verified
-- [ ] Both light and dark modes tested
-- [ ] Responsive at all breakpoints
+---
+name: ui-ux-pro-max
+description: "UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples."
+---
+
+# UI/UX Pro Max - Design Intelligence
+
+Searchable database: 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, 25 chart types across 9 stacks.
+
+## Pre-check (K1)
+
+> Does this project need custom UI/UX design? If using a pre-built template or admin framework (e.g., Retool, Vercel templates), skip this skill.
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Domain |
+|----------|----------|--------|--------|
+| 1 | Accessibility | CRITICAL | `ux` |
+| 2 | Touch & Interaction | CRITICAL | `ux` |
+| 3 | Performance | HIGH | `ux` |
+| 4 | Layout & Responsive | HIGH | `ux` |
+| 5 | Typography & Color | MEDIUM | `typography`, `color` |
+| 6 | Animation | MEDIUM | `ux` |
+| 7 | Style Selection | MEDIUM | `style`, `product` |
+| 8 | Charts & Data | LOW | `chart` |
+
+## Quick Reference
+
+### 1. Accessibility (CRITICAL)
+
+- `color-contrast` - Minimum 4.5:1 ratio for normal text
+- `focus-states` - Visible focus rings on interactive elements
+- `alt-text` - Descriptive alt text for meaningful images
+- `aria-labels` - aria-label for icon-only buttons
+- `keyboard-nav` - Tab order matches visual order
+- `form-labels` - Use label with for attribute
+
+### 2. Touch & Interaction (CRITICAL)
+
+- `touch-target-size` - Minimum 44x44px touch targets
+- `hover-vs-tap` - Use click/tap for primary interactions
+- `loading-buttons` - Disable button during async operations
+- `error-feedback` - Clear error messages near problem
+- `cursor-pointer` - Add cursor-pointer to clickable elements
+
+### 3. Performance (HIGH)
+
+- `image-optimization` - Use WebP, srcset, lazy loading
+- `reduced-motion` - Check prefers-reduced-motion
+- `content-jumping` - Reserve space for async content
+
+### 4. Layout & Responsive (HIGH)
+
+- `viewport-meta` - width=device-width initial-scale=1
+- `readable-font-size` - Minimum 16px body text on mobile
+- `horizontal-scroll` - Ensure content fits viewport width
+- `z-index-management` - Define z-index scale (10, 20, 30, 50)
+
+### 5. Typography & Color (MEDIUM)
+
+- `line-height` - Use 1.5-1.75 for body text
+- `line-length` - Limit to 65-75 characters per line
+- `font-pairing` - Match heading/body font personalities
+
+### 6. Animation (MEDIUM)
+
+- `duration-timing` - Use 150-300ms for micro-interactions
+- `transform-performance` - Use transform/opacity, not width/height
+- `loading-states` - Skeleton screens or spinners
+
+### 7. Style Selection (MEDIUM)
+
+- `style-match` - Match style to product type
+- `consistency` - Use same style across all pages
+- `no-emoji-icons` - Use SVG icons, not emojis
+
+### 8. Charts & Data (LOW)
+
+- `chart-type` - Match chart type to data type
+- `color-guidance` - Use accessible color palettes
+- `data-table` - Provide table alternative for accessibility
+
+---
+
+## How to Use
+
+### Step 1: Analyze Requirements
+
+Extract from user request: **product type**, **style keywords**, **industry**, **stack** (default: html-tailwind).
+
+### Step 2: Generate Design System (REQUIRED)
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This searches 5 domains in parallel (product, style, color, landing, typography), applies reasoning rules, and returns complete design system.
+
+**Persist for cross-session use:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
+```
+
+Creates `design-system/MASTER.md` (global) + optional `design-system/pages/<page>.md` (overrides).
+
+**With page-specific override:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Name" --page "dashboard"
+```
+
+**Hierarchical retrieval**: Page file overrides Master. No page file → Master exclusively.
+
+### Step 3: Detailed Searches (as needed)
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
+```
+
+Domains: `product`, `style`, `typography`, `color`, `landing`, `chart`, `ux`, `react`, `web`, `prompt`
+
+### Step 4: Stack Guidelines (default: html-tailwind)
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind
+```
+
+Stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose`
+
+---
+
+## Common Rules for Professional UI
+
+### Icons & Visual Elements
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis as UI icons |
+| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout |
+| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths |
+| **Consistent icon sizing** | Fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes |
+
+### Interaction & Cursor
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Cursor pointer** | `cursor-pointer` on all clickable elements | Default cursor on interactive elements |
+| **Hover feedback** | Visual feedback (color, shadow, border) | No indication element is interactive |
+| **Smooth transitions** | `transition-colors duration-200` | Instant changes or >500ms |
+
+### Light/Dark Mode Contrast
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Glass card light mode** | `bg-white/80` or higher opacity | `bg-white/10` (too transparent) |
+| **Text contrast light** | `#0F172A` (slate-900) for text | `#94A3B8` (slate-400) for body |
+| **Muted text light** | `#475569` (slate-600) minimum | gray-400 or lighter |
+| **Border visibility** | `border-gray-200` in light mode | `border-white/10` (invisible) |
+
+### Layout & Spacing
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Floating navbar** | `top-4 left-4 right-4` spacing | Stick to `top-0 left-0 right-0` |
+| **Content padding** | Account for fixed navbar height | Content hidden behind fixed elements |
+| **Consistent max-width** | Same `max-w-6xl` or `max-w-7xl` | Mix different container widths |
+
+---
+
+## Pre-Delivery Checklist
+
+### Visual Quality
+- [ ] No emojis used as icons (SVG instead)
+- [ ] All icons from consistent set (Heroicons/Lucide)
+- [ ] Brand logos verified (Simple Icons)
+- [ ] Hover states don't cause layout shift
+
+### Interaction
+- [ ] All clickable elements have `cursor-pointer`
+- [ ] Hover states provide clear visual feedback
+- [ ] Transitions are smooth (150-300ms)
+- [ ] Focus states visible for keyboard navigation
+
+### Light/Dark Mode
+- [ ] Light mode text has sufficient contrast (4.5:1)
+- [ ] Glass/transparent elements visible in light mode
+- [ ] Borders visible in both modes
+- [ ] Both modes tested before delivery
+
+### Layout
+- [ ] Floating elements have proper edge spacing
+- [ ] No content hidden behind fixed navbars
+- [ ] Responsive at 375px, 768px, 1024px, 1440px
+- [ ] No horizontal scroll on mobile
+
+### Accessibility
+- [ ] All images have alt text
+- [ ] Form inputs have labels
+- [ ] Color is not the only indicator
+- [ ] `prefers-reduced-motion` respected
+
+## Done Criteria (K4)
+
+- [ ] Design system generated before implementation
+- [ ] All pre-delivery checklist items verified
+- [ ] Both light and dark modes tested
+- [ ] Responsive at all breakpoints

package/skills/vercel-react-best-practices/SKILL.md

@@ -1,59 +1,59 @@
----
-name: vercel-react-best-practices
-description: "React/Next.js performance gotchas from Vercel engineering. Non-intuitive pitfalls that LLMs commonly miss."
-triggers: [react, next.js, performance, optimization, vercel, component, rendering]
-priority: 60
----
-
-# Vercel React Best Practices
-
-## Pre-check (K1)
-
-> Is this a React/Next.js performance issue? Standard React patterns (useState, useEffect, components) don't need this skill. Activate only for performance optimization or code review.
-
-## CRITICAL Gotchas
-
-### Waterfall Elimination
-
-| Gotcha | Why Non-obvious |
-|--------|----------------|
-| **Sequential awaits** | `const a = await f1(); const b = await f2();` creates waterfall. Use `Promise.all([f1(), f2()])` for independent ops |
-| **Await placement** | Move `await` to the branch where value is actually used, not at declaration |
-| **Missing Suspense** | Wrap slow server components in `<Suspense>` to stream — don't block entire page |
-
-### Bundle Size
-
-| Gotcha | Why Non-obvious |
-|--------|----------------|
-| **Barrel imports** | `import { Button } from "@/components"` pulls entire barrel. Use `import { Button } from "@/components/Button"` |
-| **Third-party in initial bundle** | Load analytics/logging AFTER hydration with `next/dynamic` or lazy `useEffect` |
-| **Heavy components** | Charts, editors, maps → `next/dynamic` with `{ ssr: false }` |
-
-## HIGH Gotchas
-
-### Server-side
-
-| Gotcha | Fix |
-|--------|-----|
-| Duplicate DB calls across server components | Wrap with `React.cache()` for per-request dedup |
-| Large data serialized to client | Pick only needed fields before passing to client components |
-| Blocking post-processing (logging, analytics) | Use `after()` for non-blocking tasks |
-
-## MEDIUM Gotchas
-
-| Gotcha | Fix |
-|--------|-----|
-| Expensive computation re-runs on parent re-render | Isolate in `memo()` wrapped component |
-| Static JSX recreated every render | Hoist outside component: `const HEADER = <header>...</header>` |
-| Long lists render all items | `content-visibility: auto; contain-intrinsic-size: 0 80px;` on list items |
-| `{count && <Item />}` renders `0` | Use ternary: `{count > 0 ? <Item /> : null}` |
-| Event handler changes every render → effect re-runs | Store handlers in `useRef` for stable effects |
-| Object in useEffect deps | Use primitive values (id, not entire object) as dependencies |
-
-## Done Criteria (K4)
-
-- [ ] No sequential awaits for independent operations
-- [ ] No barrel imports for tree-shakeable modules
-- [ ] Server component data is `React.cache()`-wrapped where reused
-- [ ] Heavy third-party loaded after hydration
-- [ ] Long lists use `content-visibility: auto`
+---
+name: vercel-react-best-practices
+description: "React/Next.js performance gotchas from Vercel engineering. Non-intuitive pitfalls that LLMs commonly miss."
+triggers: [react, next.js, performance, optimization, vercel, component, rendering]
+priority: 60
+---
+
+# Vercel React Best Practices
+
+## Pre-check (K1)
+
+> Is this a React/Next.js performance issue? Standard React patterns (useState, useEffect, components) don't need this skill. Activate only for performance optimization or code review.
+
+## CRITICAL Gotchas
+
+### Waterfall Elimination
+
+| Gotcha | Why Non-obvious |
+|--------|----------------|
+| **Sequential awaits** | `const a = await f1(); const b = await f2();` creates waterfall. Use `Promise.all([f1(), f2()])` for independent ops |
+| **Await placement** | Move `await` to the branch where value is actually used, not at declaration |
+| **Missing Suspense** | Wrap slow server components in `<Suspense>` to stream — don't block entire page |
+
+### Bundle Size
+
+| Gotcha | Why Non-obvious |
+|--------|----------------|
+| **Barrel imports** | `import { Button } from "@/components"` pulls entire barrel. Use `import { Button } from "@/components/Button"` |
+| **Third-party in initial bundle** | Load analytics/logging AFTER hydration with `next/dynamic` or lazy `useEffect` |
+| **Heavy components** | Charts, editors, maps → `next/dynamic` with `{ ssr: false }` |
+
+## HIGH Gotchas
+
+### Server-side
+
+| Gotcha | Fix |
+|--------|-----|
+| Duplicate DB calls across server components | Wrap with `React.cache()` for per-request dedup |
+| Large data serialized to client | Pick only needed fields before passing to client components |
+| Blocking post-processing (logging, analytics) | Use `after()` for non-blocking tasks |
+
+## MEDIUM Gotchas
+
+| Gotcha | Fix |
+|--------|-----|
+| Expensive computation re-runs on parent re-render | Isolate in `memo()` wrapped component |
+| Static JSX recreated every render | Hoist outside component: `const HEADER = <header>...</header>` |
+| Long lists render all items | `content-visibility: auto; contain-intrinsic-size: 0 80px;` on list items |
+| `{count && <Item />}` renders `0` | Use ternary: `{count > 0 ? <Item /> : null}` |
+| Event handler changes every render → effect re-runs | Store handlers in `useRef` for stable effects |
+| Object in useEffect deps | Use primitive values (id, not entire object) as dependencies |
+
+## Done Criteria (K4)
+
+- [ ] No sequential awaits for independent operations
+- [ ] No barrel imports for tree-shakeable modules
+- [ ] Server component data is `React.cache()`-wrapped where reused
+- [ ] Heavy third-party loaded after hydration
+- [ ] Long lists use `content-visibility: auto`

package/skills/video-production/SKILL.md

@@ -1,51 +1,51 @@
----
-name: video-production
-description: "Video processing gotchas — FFmpeg, transcoding, streaming, subtitles."
-triggers: [video, ffmpeg, transcode, encode, stream, media, subtitle, thumbnail, hls, dash]
-priority: 60
----
-
-# Video Production
-
-## Pre-check (K1)
-
-> Are you processing video files programmatically? If just embedding a YouTube/Vimeo player, this skill is not needed.
-
-## Gotchas
-
-| Gotcha | Consequence | Prevention |
-|--------|-------------|------------|
-| Direct CLI string concatenation | Command injection risk | Always use wrapper library (fluent-ffmpeg for TS, ffmpeg-python for Python) |
-| No input validation | Crash on corrupted files | Always `ffprobe` input before processing — check codec, resolution, duration |
-| No temp file cleanup | Disk fills up silently | `try/finally` or cleanup handler — never leave partial outputs |
-| No progress callback | Long encoding appears frozen | Implement progress events for any operation >10s |
-| Memory loading large files | OOM on 4K+ video | Use streaming I/O, never read entire file into memory |
-| Assuming codec availability | Fails on different FFmpeg builds | Check `ffmpeg -codecs` at runtime before encoding |
-| Fixed bitrate encoding | Inconsistent quality | Use CRF-based quality (18-28 for H.264) instead |
-| No timeout | Encoding hangs forever | Set timeout + kill process on expiry |
-
-## Codec Quick Reference
-
-| Use Case | Codec | Note |
-|----------|-------|------|
-| Maximum compatibility | H.264 (libx264) | CRF 23 default |
-| Smaller files | H.265 (libx265) | 50% smaller, slower, licensing issues |
-| Open source | VP9 (libvpx-vp9) | Good for WebM |
-| Best compression | AV1 (libaom-av1) | Very slow encoding |
-
-## Resolution Presets
-
-| Preset | Resolution | Bitrate (H.264) |
-|--------|-----------|-----------------|
-| 360p | 640x360 | 800 kbps |
-| 720p | 1280x720 | 3 Mbps |
-| 1080p | 1920x1080 | 6 Mbps |
-| 4K | 3840x2160 | 15 Mbps |
-
-## Done Criteria (K4)
-
-- [ ] All FFmpeg calls go through wrapper library (no raw CLI strings)
-- [ ] Input files validated with ffprobe before processing
-- [ ] Temp files cleaned up in all paths (success + error)
-- [ ] Progress reporting for long operations
-- [ ] Codec availability checked at runtime
+---
+name: video-production
+description: "Video processing gotchas — FFmpeg, transcoding, streaming, subtitles."
+triggers: [video, ffmpeg, transcode, encode, stream, media, subtitle, thumbnail, hls, dash]
+priority: 60
+---
+
+# Video Production
+
+## Pre-check (K1)
+
+> Are you processing video files programmatically? If just embedding a YouTube/Vimeo player, this skill is not needed.
+
+## Gotchas
+
+| Gotcha | Consequence | Prevention |
+|--------|-------------|------------|
+| Direct CLI string concatenation | Command injection risk | Always use wrapper library (fluent-ffmpeg for TS, ffmpeg-python for Python) |
+| No input validation | Crash on corrupted files | Always `ffprobe` input before processing — check codec, resolution, duration |
+| No temp file cleanup | Disk fills up silently | `try/finally` or cleanup handler — never leave partial outputs |
+| No progress callback | Long encoding appears frozen | Implement progress events for any operation >10s |
+| Memory loading large files | OOM on 4K+ video | Use streaming I/O, never read entire file into memory |
+| Assuming codec availability | Fails on different FFmpeg builds | Check `ffmpeg -codecs` at runtime before encoding |
+| Fixed bitrate encoding | Inconsistent quality | Use CRF-based quality (18-28 for H.264) instead |
+| No timeout | Encoding hangs forever | Set timeout + kill process on expiry |
+
+## Codec Quick Reference
+
+| Use Case | Codec | Note |
+|----------|-------|------|
+| Maximum compatibility | H.264 (libx264) | CRF 23 default |
+| Smaller files | H.265 (libx265) | 50% smaller, slower, licensing issues |
+| Open source | VP9 (libvpx-vp9) | Good for WebM |
+| Best compression | AV1 (libaom-av1) | Very slow encoding |
+
+## Resolution Presets
+
+| Preset | Resolution | Bitrate (H.264) |
+|--------|-----------|-----------------|
+| 360p | 640x360 | 800 kbps |
+| 720p | 1280x720 | 3 Mbps |
+| 1080p | 1920x1080 | 6 Mbps |
+| 4K | 3840x2160 | 15 Mbps |
+
+## Done Criteria (K4)
+
+- [ ] All FFmpeg calls go through wrapper library (no raw CLI strings)
+- [ ] Input files validated with ffprobe before processing
+- [ ] Temp files cleaned up in all paths (success + error)
+- [ ] Progress reporting for long operations
+- [ ] Codec availability checked at runtime