CommunityImagegithub.com

og-images

Makes an app's launch images from its real UI: a 1200×630 link preview (Open Graph and X card) with a large readable title, the app icon and a real capture, optional per-page previews for a site's pages, a Product Hunt gallery of 4 to 6 slides at 1270×760, an X header at 1500×500 with the avatar and phone-crop zones kept clear, and the meta tags to paste. Light, calm, on the brand's own colours or a bundled wallpaper, then checked on the files (exact size, no alpha, text contrast, title size, safe zones, no font fallback). Use when asked for an og image, Open Graph image, social preview, link preview, share image, Twitter card, Product Hunt gallery or X header image.

What is og-images?

og-images is a Claude Code agent skill that makes an app's launch images from its real UI: a 1200×630 link preview (Open Graph and X card) with a large readable title, the app icon and a real capture, optional per-page previews for a site's pages, a Product Hunt gallery of 4 to 6 slides at 1270×760, an X header at 1500×500 with the avatar and phone-crop zones kept clear, and the meta tags to paste. Light, calm, on the brand's own colours or a bundled wallpaper, then checked on the files (exact size, no alpha, text contrast, title size, safe zones, no font fallback). Use when asked for an og image, Open Graph image, social preview, link preview, share image, Twitter card, Product Hunt gallery or X header image.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/abdiraimov-otabek/claude-code-og-image-skill/tree/main/skills/og-images

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Og images

Three kinds of image that all do one job: make someone stop on a link and understand the app in a glance. Each is a real capture of the app with a large title, on the brand's field or a bright wallpaper. The UI is the hero. Nothing is drawn but the frame.

Outputs, in launch-assets/og/ of the user's repo:

FileSizeWhat
og.png1200×630The link preview for the home page.
og-<id>.png1200×630Optional: one per page of a site, same design, title from that page.
ph/01-<id>.png … 061270×760Product Hunt gallery, 4 to 6 slides. Slide 1 is the hero.
x-header.png1500×500X header with the avatar and phone-crop zones clear.
meta.htmlThe <meta> tags to paste into <head>.

Sizes and safe zones, with sources and dates, are in references/sizes.md.

When to use

  • A launch needs a share image, a Product Hunt gallery or an X header.
  • The site's current og:image is a logo on a flat colour, or there is none.
  • A release changed the UI, so the previews are re-rendered from fresh captures.

Captures are Mac-style landscape windows or islands; a portrait phone screen is not supported by these cards. Not for: App Store screenshots (a different skill, with different sizes), or anything that needs UI the app does not have. This skill never draws UI.

Setup (once)

Node 20 or newer. Playwright goes into this skill's folder, not the user's repo:

npm install --prefix <skill-folder> [email protected] && npx --prefix <skill-folder> playwright install chromium

If it is missing, render.mjs prints this line and exits 2.

Step 0. Brand

Read launch-assets/brand.json in the user's repo. If it is there, use it. If it is missing, detect each field from the repo and write the file. Ask the user only for what you could not find, in one message.

{
  "appName": "Halo", "oneLiner": "The Dynamic Island for Mac", "platform": "macos",
  "colors": { "bg": "#f5f5f7", "ink": "#1d1d1f", "accent": "#0071e3" },
  "fonts": { "family": "-apple-system, 'SF Pro Display', sans-serif", "file": null, "google": null },
  "iconPath": "site/assets/icon.png",
  "screenshotDirs": ["launch-assets/captures"],
  "siteUrl": "https://example.com"
}
  • appName, oneLiner: README title and first line, the site's <title> and <h1>, Info.plist.
  • colors: the site's CSS variables, the asset catalog's AccentColor, Swift Color definitions. Take the light values. Write hex (#0d7f76); convert rgb(), oklch() and hsl() first. Anything the renderer cannot read counts as grey.
  • fonts.family (a CSS stack), fonts.file (a font file the repo ships, a path relative to the repo root, the folder above launch-assets, or null), fonts.google (such as Geist:wght@400;600, or null). Use the brand's font only if the repo ships the file; otherwise the system stack or Google Fonts. Never copy a proprietary font into the user's repo.
  • iconPath: the app icon, a square PNG (1024 px is best), relative to the repo root. Look in the site's assets, the asset catalog's AppIcon, the favicon folder. Required: the icon and name are on every image.
  • siteUrl: where meta.html points the image URLs. Optional; without it the tags carry a placeholder.

Steps

  1. Captures. Reuse what exists: launch-assets/captures/, screenshotDirs, or an earlier launch-assets/store-screenshots/shots.json. Take new ones only when none pass the rules below. First look for the app's own way to capture itself: a snapshot, demo or sample-data flag (rg -i "demo|snapshot|screenshot|marketing" in the source, the README and Package.swift; for example MyApp --snapshot <dir> or MYAPP_DEMO=1). Read what a flag does before running it. Never run anything that scans, cleans or writes real user data, and never launch a second copy of an app that keeps live state. If a flag could do either, stop and ask. Otherwise, on a Mac, bring the app to the front in the state to show and run swift <skill-folder>/scripts/capture-window.swift "MyApp" capture.png (the app's largest on-screen window, no shadow, Retina pixels; it skips a notch or menu bar app's panel, which sits on a higher window layer, and says so). iOS: xcrun simctl status_bar booted override --time 9:41 --batteryState charged --batteryLevel 100, then xcrun simctl io booted screenshot capture.png, then xcrun simctl status_bar booted clear.

    Rules for every capture:

    • Real UI, focused. The active window: coloured traffic lights, a lit sidebar. A grey, dimmed window is a fail.
    • Settled. No counter mid-roll, no spinner, nothing half-drawn.
    • Neutral demo data. No personal names, real file, project or account names, no other company's product names (unless the app's own site names that integration). Use the demo mode, never a screenshot of the real thing.
    • Light mode if the app has one. Dark captures are for dark-only apps.
    • 2x pixels. A card shows a capture at most 1.15x its own pixels (the render fails above that), so a window needs about 1400 px across for a link preview and 2000 px for a gallery slide.
    • Real content. No empty wells, no lorem, no truncated text in the part the title talks about.
    • One that reads small. The link preview shows the capture at about 600 px wide. Pick the capture whose main point is visible at that size (a big number, a clear list), not a dense settings pane. Crop to the part that matters.
    • A SwiftUI ImageRenderer capture (a notch app's island) comes with opaque yellow placeholders in its corner flares: set "clean": true. For an island floating on the card, add "square": true, which squares the corner flares off to the body's edges. Crop away any empty notch row with crop.

    Done when each capture passes the list. Read every file's size (sips -g pixelWidth -g pixelHeight) and look at it.

  2. Write the words.

    • Link title: the app's one-liner or the page's own title, in the site's words: 9 words or fewer, sentence case, no full stop, no dash, no !. It is the only large text on the card, so shorter is bigger.
    • Pages: if the repo has a site with several pages, run node <skill-folder>/scripts/pages.mjs <site-folder>. It prints each page's <title> and <h1>. Pick the pages worth a preview of their own (the guides, the pricing page, the biggest features); skip pages that name another company's product. Take the <h1> or the shorter of the two, drop the site-name suffix and "(2026)" style tags, keep it to 9 words. Never paraphrase.
    • Slides: if launch-assets/store-screenshots/shots.json exists, "ph": { "fromShots": "../store-screenshots/shots.json" } reuses its headlines, sublines, captures and crops (first 6 shots, "limit" changes that). Otherwise write 4 to 6 slides: slide 1 says what the app is, each later one has one benefit and makes sense alone. Headline 6 words or fewer, an optional subline of one short sentence.
    • X header title: the one-liner. 6 words or fewer.
    • Alt text: one sentence that says what the image shows. It defaults to <app>: <title>. <subline>; write alt on the link when the capture adds something worth saying.

    Copy uses the site's own words. Every line is taken from the site or README and shortened; every number, name and claim is on the site. Check each line with rg against the site copy before you keep it.

  3. Write launch-assets/og/og.json.

    {
      "brand": "../brand.json",
      "out": ".",
      "wallpaper": "auto",
      "link": {
        "title": "A Mac cleaner for developers",
        "capture": "../captures/overview.png",
        "alt": "Shedi, a Mac cleaner for developers: 43.84 GB found, sorted into safe to clean and check first"
      },
      "pages": [
        { "id": "xcode-deriveddata", "title": "Clear Xcode DerivedData", "capture": "../captures/xcode.png" }
      ],
      "ph": { "fromShots": "../store-screenshots/shots.json" },
      "x": { "title": "A Mac cleaner for developers", "capture": "../captures/overview.png" }
    }
    

    Leave out pages, ph or x to skip that kind. Paths are relative to og.json. A page inherits everything from link (capture, crop, layout) and overrides what it names. Options on link, a page, a slide or x:

    • capture (or captures, up to 3, stacked), crop ({ x, y, w, h }, 0 to 1 of the capture after transparent margins are trimmed; crops for several captures), clean, square, radius, width (capture width as a share of the card), shadow: false, minCoverage.
    • layout: link cards are side (title left, a window rising from the bottom right) or below (title centred, a wide capture under it). The default picks below for a capture wider than 2:1, side otherwise. Slides are fit (the whole capture, nothing cut), bleed (cut by the bottom edge, for a window) or pair (2 or 3 captures stacked). A slide with no layout and one plain window capture (no clean) is bleed; anything else is fit.
    • minCoverage: the floor for UI coverage (link 0.3, slide 0.4, header 0.12). A capture that spans 80% of the card width passes without it (a thin island or bar cannot get taller). Do not lower the floor to hide a small capture: show it larger, crop it or pick another.
    • On a slide in fromShots, add "slides": [{ "id": "<shot id>", ... }] to override one slide's options.

    Background, once for all images: "wallpaper": "auto" picks the bundled picture whose hue is nearest the brand accent (blue and teal, green, warm, pink) and prints the pick and why. Tell the user the pick and why, and that they can change it ("wallpaper": "snow", or a path to their own bright, calm picture, at least 2400 px wide). A grey accent, or one more than 50 degrees from every picture, gets the brand field instead (the brand's background washed with a little of its accent). Leave the key out for the field. This skill bundles five pictures.

  4. Render.

    node <skill-folder>/scripts/render.mjs launch-assets/og/og.json
    

    One output line per PNG: ok or FAIL, size, file weight, the font that actually drew the title, the contrast of the words against the pixels really behind them, the title's size and cap height, the UI coverage and how far the capture and the wallpaper were enlarged. --only link|pages|ph|x renders one kind (anything else fails). It also writes meta.html.

    The guard fails: a size that is not exact, an alpha channel, a file over 5 MB, text contrast under 4.5:1 (there is no scrim; pick a paler wallpaper or darker ink), a title whose cap height is under the minimum (link 40 px, slide 38 px, header 36 px, so it still reads in a 600 px wide preview) or that needs more lines than fit, over-long or dashed (a dash, " - " or "--") or ! copy, a capture enlarged over 1.15x or a wallpaper over 1.2x, UI coverage under the floor unless the capture spans 80% of the card width (measured on the capture's content pixels, not its box, so blank black or white areas do not count), anything outside the X safe area or inside the avatar zone, and a font fallback: the first named family of fonts.family must be the font that drew the title ("Inter, sans-serif" with no file would draw SF Pro: FAIL). A stack that starts with -apple-system or system-ui means the system font and only fails on a fallback such as Helvetica or Arial. Fix every FAIL in og.json and render again.

  5. QA pass. Required, and done on the files, not on the config.

    1. Size and alpha: sips -g pixelWidth -g pixelHeight -g hasAlpha <each file>. Exact sizes from sizes.md, hasAlpha: no.
    2. Look: open every PNG with the Read tool at full size. Then node <skill-folder>/scripts/preview.mjs launch-assets/og and open _preview-600.png and _preview-300.png (every image at 600 and 300 px wide, as a feed shows it), then delete the two files. For each image check:
      • The title is readable at 300 px and nothing is clipped or alone on a second line.
      • The font in the output line is the one you asked for.
      • The capture is sharp, shows the point of the title, has no truncated text and no personal data.
      • Names: no competitor or other company's name or logo unless the site names that integration; no personal names.
      • Words: every line is the site's own wording, shortened; every number is on the site.
      • X header: the lower left (x under 420, y over 300) is clear for the profile photo; the content sits in the middle band, away from the top and bottom 70 px. Check it against sizes.md and, if you can, on the real profile.
      • Set: the slides read as one family; no two make the same point.
    3. Fix and render again, then look at that file again.
    4. Only then report: the file list, the sips output, and anything you could not verify. Tell the user to copy the PNGs to the site, paste meta.html into <head>, and refresh the cached preview in each platform's debugger.

Look rules

  • Light first. A bright wallpaper or the brand field, ink dark on it. No dark background with neon.
  • No glow, no halo. Depth is a 1 px edge and neutral black shadows at low opacity.
  • One job per image. One title, one capture (or one pair), at most one subline.
  • Large type. The title is what survives a thumbnail. Short copy is what lets it be large.
  • Real captures only. The UI is never drawn, redrawn or generated.

Related Skills