Open Graph Images Skill
A comprehensive toolset and guidance for generating, managing, and wiring OpenGraph (OG) images for web applications. This skill focuses on building high-quality, brand-consistent social preview images that are committed directly to your repository or served via framework-native dynamic routes.
🚀 Overview
This repository provides the infrastructure to:
- Detect OG targets across various web frameworks (Next.js, Astro, Remix, etc.).
- Generate static 1200x630 social images by capturing the exact browser preview used in the OG Studio.
- Implement an "OG Studio" hub for reviewing and importing images before they go live.
- Wire generated assets into the application's metadata systems (App Router, Pages Router, SEO helpers).
📂 Repository Structure
Below is a breakdown of every file in this repository and its role in the OG image generation workflow.
📄 Core Files
- SKILL.md: The primary instruction manual for the Antigravity AI assistant. It contains the logic, decision matrices, and safety checks for performing OG image tasks.
- README.md: This file! Provides a human-readable overview of the repository.
🛠️ Scripts
- scripts/detect_og_targets.py: A Python utility that scans a target repository to identify frameworks, routes, existing OG assets, and SEO wiring. It recommends the best integration strategy.
📦 Assets (Templates & Examples)
These files are stored as .example files to avoid type-checking issues in this repository. They are intended to be copied and renamed in the target project.
OG Studio Hub (Next.js App Router)
The following files comprise a local-only "Studio" where users can preview and manage OG cards:
- assets/next-app-router-og-hub/app/og-studio/page.tsx.example: The main entry point for the OG Studio UI.
- assets/next-app-router-og-hub/app/og-studio/OgStudioClientPage.tsx.example: The interactive client-side grid that previews cards and imports exact browser renders.
- assets/next-app-router-og-hub/app/og-studio/client-utils.ts.example:
html-to-imagecapture helpers that wait for fonts and nested images before export. - assets/next-app-router-og-hub/app/og-studio/[key]/page.tsx.example: Local-only full-size preview route for one target.
- assets/next-app-router-og-hub/app/og-studio/[key]/OgStudioPreviewClient.tsx.example: Full-preview client that re-imports the exact single-card browser render.
- assets/next-app-router-og-hub/app/api/og/import/route.ts.example: POST-only import endpoint that writes captured PNG buffers into the repo.
- assets/next-app-router-og-hub/lib/og/card.tsx.example: Browser-safe shared OG card renderer used by the studio.
- assets/next-app-router-og-hub/lib/og/importer.ts.example: Final file-write helper used by the POST import route.
- assets/next-app-router-og-hub/lib/og/targets.ts.example: Typed target registry plus imported-state lookup.
Dynamic Routes
- assets/next-app-router-og-hub/app/blog/[slug]/opengraph-image.tsx.example: A template for generating dynamic social images on-the-fly for content-heavy routes using
next/og.
📚 References
- references/next-app-router-og-hub.md: Detailed guidance on implementing the "Review-First" workflow in Next.js applications.
🏗️ Core Principles
- Repo-Native: Images should live in the repository (e.g.,
public/og/or route-localopengraph-image.png), not as external hosted assets. - Review-First: By default, build an OG Hub to let users approve designs and copy before they are wired into production metadata.
- Preview Parity: For static OG hubs, import the exact browser preview instead of re-rendering it through a second image engine.
- Poster Design: OG images should look like high-quality posters—large text, clear branding, and minimal clutter—not just page screenshots.
🛠️ Getting Started for Assistants
- Inventory: Run
python3 scripts/detect_og_targets.py <path_to_repo>to understand the current state. - Strategy: Consult the Recommendation Matrix in
SKILL.mdto choose between Static Imports or Dynamic Routes. - Implement: Use the templates in
assets/to build the studio and generators. - Verify: Confirm that the imported PNGs match the browser preview and that metadata points to the new assets.