youtube-embed

YouTube video facade pattern for performance. Lazy-load iframe on click, poster images, GA4 tracking, Schema.org markup.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill implements a high-performance YouTube video facade pattern designed to drastically improve page load speeds and Core Web Vitals. By replacing heavy third-party iframes with optimized local poster images and lazy-loading content only upon user interaction, it ensures a seamless user experience. It also integrates SEO-essential Schema.org VideoObject markup for rich snippets, GA4 engagement tracking, and privacy-compliant 'nocookie' embeds.

Use Cases

  • Core Web Vitals Optimization: Boost Lighthouse performance scores by deferring heavy YouTube JavaScript execution until the user explicitly clicks to play.
  • SEO & Rich Snippets: Automatically generate Schema.org VideoObject metadata to improve search engine indexing and increase the visibility of video content in search results.
  • Privacy-First Web Development: Ensure GDPR and privacy compliance by using the youtube-nocookie.com domain and preventing third-party tracking cookies from loading before user consent.
  • Engagement Analytics: Seamlessly track user interactions with built-in GA4 'video_play' event triggers to monitor content performance without manual configuration.
nameyoutube-embed
descriptionYouTube video facade pattern for performance. Lazy-load iframe on click, poster images, GA4 tracking, Schema.org markup.

YouTube Embed Skill

Purpose

Embed YouTube videos without loading YouTube scripts until user clicks. Massive performance win.

Core Rules

  1. Facade pattern — Poster + play button, no iframe until click
  2. Local posters — Download and optimize thumbnails locally
  3. Privacy-enhanced — Use youtube-nocookie.com only
  4. Track engagement — GA4 video_play event on click
  5. Schema.org — VideoObject markup for rich snippets

Flow

Click before: Poster image + Play button (no YouTube)
Click after:  Replace with iframe + GA4 event + autoplay

Poster Images

  1. Download: https://i.ytimg.com/vi/{VIDEO_ID}/maxresdefault.jpg
  2. Fallback: sddefault.jpg if maxres unavailable
  3. Convert: Use Picture skill (avif, webp, jpg)
  4. Store: src/assets/videos/{slug}.jpg

References

Forbidden

  • ❌ YouTube iframe/script before click
  • ❌ youtube.com (must use youtube-nocookie.com)
  • ❌ fetchpriority="high" on video facades
  • ❌ YouTube logo as play button (trademark)
  • ❌ Remote poster images (always local)
  • ❌ Missing poster or title

Definition of Done

  • VideoFacade component created
  • Poster images downloaded and optimized
  • Click triggers iframe swap + autoplay
  • GA4 video_play event firing
  • VideoObject schema on pages with videos
  • Keyboard accessible (Enter/Space)