The Complete Production SOP: How to Deploy and Run Satori Dynamic OpenGraph Image Engine in Autonomous AI Agents
Step-by-step SOP to install and run Satori Dynamic OpenGraph Image Engine in Codex, Claude Code, and Cursor. Includes verified prompts, sandbox rules, and fixes.
Technical Overview & Architectural Context
Autonomous coding agents frequently stumble when generating dynamic OpenGraph images. Without deterministic boundaries, agents default to unsupported CSS properties (such as Grid layouts, CSS transitions, or complex pseudo-elements) that break Vercel Satori's strict Yoga-based Flexbox implementation. Additionally, models often hallucinate automated web font resolution, omitting necessary TTF/OTF font buffers or failing to handle SVG rasterization via @resvg/resvg-js correctly on edge/serverless runtimes. The Satori Dynamic OpenGraph Image Engine skill installs precise procedural constraints directly into the agent runtime. It enforces strict Flexbox modeling, mandatory local font loading, proper SVG-to-PNG binary pipelines, and standard 1200x630 pixel canvas boundaries. This eliminates runtime parsing failures and ensures reproducible, pixel-perfect social card generation across CI/CD and edge endpoints.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the skill manifest into your agent's workspace configuration directory to register triggers.
Autonomous runtimes such as Claude Code, Cursor, and Codex index local skill manifests at project initialization. By mounting the open-graph-image-satori-generator skill in your project's `.agent/skills/` or user-level config, you inform the agent's intent-routing pipeline about Satori's layout limitations, required packages, and exact execution sequence before code generation begins.
mkdir -p .agents/skills/open-graph-image-satori-generator && curl -fsSL https://askills.dev/api/skills/open-graph-image-satori-generator/raw -o .agents/skills/open-graph-image-satori-generator/SKILL.md---
name: "open-graph-image-satori-generator"
description: "Render dynamic social share and OpenGraph preview images from HTML and CSS."
metadata:
author: "Vercel"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "generate opengraph images with satori"
- "render jsx to png"
- "create dynamic twitter cards nextjs"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# Satori Dynamic OpenGraph Image Engine
Enforce strict Flexbox layout (display: 'flex'), manual font buffer loading, and @resvg/resvg-js rasterization.Mount the skill at the project root instead of globally to prevent Satori constraints from bleeding into non-OG rendering agent tasks.
Satori does not support CSS Grid or float. The skill explicitly limits layouts to Flexbox; ensure your agent does not attempt to fall back to Tailwind Grid classes.
Dependency Validation & Static Asset Staging
Install the required native SVG rasterizer and stage local TTF/WOFF font buffers.
Satori converts JSX to SVG strings, but delivering social preview cards requires raw PNG or JPEG binaries. Agents often try fetching Google Fonts via remote URLs at runtime, which triggers network errors or edge timeouts. This step ensures native binaries for @resvg/resvg-js are installed and custom font files are committed to a designated assets path.
npm install satori @resvg/resvg-js && mkdir -p public/fonts && curl -fsSL -o public/fonts/Inter-Bold.ttf "https://raw.githubusercontent.com/google/fonts/main/ofl/inter/Inter-Bold.ttf"import satori from 'satori';
import { Resvg } from '@resvg/resvg-js';
import fs from 'node:fs/promises';
import path from 'node:path';
export async function generateOgImage(title: string): Promise<Buffer> {
const fontData = await fs.readFile(path.join(process.cwd(), 'public/fonts/Inter-Bold.ttf'));
const svg = await satori(
<div
style={{
height: '100%',
width: '100%',
display: 'flex',
flexDirection: 'column',
alignItems: 'flex-start',
justifyContent: 'center',
backgroundColor: '#0f172a',
padding: '60px',
}}
>
<div style={{ color: '#38bdf8', fontSize: 32, marginBottom: 16 }}>askills.dev</div>
<div style={{ color: '#f8fafc', fontSize: 64, fontWeight: 700, lineHeight: 1.1 }}>{title}</div>
</div>,
{
width: 1200,
height: 630,
fonts: [
{
name: 'Inter',
data: fontData,
weight: 700,
style: 'normal',
},
],
}
);
const resvg = new Resvg(svg, { fitTo: { mode: 'width', value: 1200 } });
return resvg.render().asPng();
}Convert WOFF2 fonts to TTF or OTF format; Satori does not parse raw WOFF2 buffers without an external decompressor like woff2-wasm.
Running @resvg/resvg-js on minimal Alpine Linux or serverless Docker images requires glibc compatibility or installing @resvg/resvg-js-linux-x64-musl.
Intent Matching & Trigger Invocation
Invoke the agent using exact YAML trigger phrasing to activate Satori SOP guidelines.
Instruct Codex, Claude Code, or Cursor using intent phrases declared in the SKILL.md manifest. When the agent detects triggers such as 'generate opengraph images with satori' or 'render jsx to png', it loads the procedural layout engine checklist and avoids standard browser/Puppeteer heavy fallbacks.
State dimensions explicitly (1200x630) in your trigger prompt to keep the agent from defaulting to arbitrary square sizes.
Do not request inline standard HTML string templates; Satori requires React-compatible JSX elements or VNode objects.
Verification, Linting & Output Quality Gate
Run automated headless rendering checks to verify image dimensions and byte health.
The skill mandates a verification checklist: compile TypeScript, confirm font buffers resolve without missing glyphs, and test that a 1200x630 PNG buffer is successfully output with positive byte size before finalizing the PR or task commit.
node -e "import('./lib/generate-og.js').then(m => m.generateOgImage('Test Header')).then(buf => console.log('Generated PNG bytes:', buf.length))"Inspect the generated PNG buffer using an image viewer CLI like `timg` or check the byte length to ensure non-empty responses (> 10KB).
Ensure the agent does not leave large generated image binary test fixtures committed in the main repository history.
Real-World Scenario: Automated Dynamic OG Image Route for a Next.js / Edge Blog Engine
“create dynamic twitter cards nextjs and generate opengraph images with satori for blog posts, using 1200x630 dimensions, custom Inter-Bold font, and resvg for PNG output”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent attempted to use CSS Grid (`display: 'grid'`) or Tailwind CSS grid utility classes inside the Satori JSX markup. Satori uses Facebook's Yoga engine, which only implements standard Flexbox.
Replace `display: 'grid'` with `display: 'flex'` and manage columns/rows using `flexDirection: 'row'` or `flexDirection: 'column'` with flex child wrappers.Root Cause: The font path specified in `fs.readFile()` is relative to an incorrect execution root or points to an unsupported WOFF2 file format instead of TTF/OTF.
Use `path.resolve(process.cwd(), 'public/fonts/font.ttf')` and verify the font exists, or provide an explicit ArrayBuffer: `new Uint8Array(await fs.readFile(...)).buffer`.Frequently Asked Questions (Satori Dynamic OpenGraph Image Engine SOP)
Q:Can I use Satori Dynamic OpenGraph Image Engine across Codex, Claude Code, and Cursor simultaneously?
Yes. This skill adheres to the universal SKILL.md specification. Placing the skill manifest inside `.agents/skills/open-graph-image-satori-generator/` makes it discoverable by Codex Desktop, Claude Code CLI, Cursor, and Windsurf without modification.
Q:How does Satori Dynamic OpenGraph Image Engine prevent context window overflow during long agent sessions?
By encapsulating CSS Flexbox rules, font buffer configurations, and resvg pipeline logic into a concise procedural guide, the agent receives precise instructions on invocation rather than hallucinating and iterating over multiple broken Chromium/Puppeteer attempts.
Q:Does this skill require escalated root or container permissions?
No. The skill operates with a 98/100 security score. It requires only workspace-level filesystem reads/writes to scaffold scripts and local font files, requiring no elevated root privileges or external shell daemon access.
Ready to equip your autonomous agent with Satori Dynamic OpenGraph Image Engine?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.