agentleFS
ZmokiZmoki/zmoki-astro-starter/.claude/skills/og-images/SKILL.md

og-images

Skill4 starsChanged 21 days agoMITView on GitHub

Customize the Open Graph / social-share image cards — layout, colors, fonts, text, dimensions, add a template variant, or change which pages get a card. Use when the user wants to change how link previews / social cards / OG images look.

5 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions5 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 5

    1. Anglesite/anglesite-skills★ 15same name
    2. karero/croftweaver★ 10same name
    3. karero/website-builder★ 10same name
    4. phucbm/skills★ 2same name
    5. gwendall/skills★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository9 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the PNG to check it. Always finish with a build.

    line 29
  2. Very specific:

    Add the name to the OgTemplate union in src/og/types.ts.

    line 51
  3. Very specific:

    Write a fooCard(entry) builder in src/og/card.ts and route to it in renderCard.

    line 52

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

OG images

Social-share cards are rendered at build time: Satori (nodes → SVG), then resvg (SVG → PNG). Every card comes in two frames: 1200×630 at /og/<key>.png and 1200×1200 at /og/square/<key>.png. astro build writes them to dist/og/; astro dev renders the same routes on request. Nothing is committed except the card fonts.

Files

FileOwns
src/og/manifest.tsWhich pages get a card, and each card's text (title, description, eyebrow, alt)
src/og/card.tsHow cards look: the article and site layouts
src/og/theme.tsCard colors (from design tokens) and OG_FRAMES (each frame's size, folder and scale)
src/og/fonts.ts + fonts/*.woffThe card font (Noto Sans Latin subset)
src/og/types.tsThe OgEntry shape and the OgTemplate union
src/pages/og/[...path].png.tsThe endpoint: getStaticPaths from the manifest → render → PNG

The manifest feeds both the endpoint and BaseLayout.astro, which lists one og:image group per frame, landscape first (consumers take the first they support), via getOgImage(pathname). twitter:image is the landscape card. A page with no entry gets the default card.

Preview

npm run dev     # then open /og/index.png, /og/square/index.png, /og/blog/<id>.png, /og/default.png
npm run build   # then open dist/og/**/*.png

Read the PNG to check it. Always finish with a build.

Common edits

Colors

Cards read the design tokens, so a re-skin via /brand recolors them. To tune only the cards, edit the token picks in src/og/theme.ts (bg, ink, muted, accent, …).

Every text/background pair must meet WCAG AA: 4.5:1 for normal text, 3:1 for large text (the title/name). Check against the card background, cream-100, not white. The tight pair is muted text (stone-500) on cream-100, at about 4.5:1: lightening bg or muted drops the eyebrow, description and domain below AA first. If a pair fails, darken the token or enlarge/bold the text.

Font

Put the new .woff/.ttf in src/og/fonts/ (Satori needs the file, not a CSS @font-face), load it in src/og/fonts.ts, and use its name in card.ts. The bundled font is a Latin subset; other scripts need a fuller file. This font is separate from the site's self-hosted fonts: a brand typeface swap (/brand) must update it too.

Layout or copy

Layout: edit articleCard / siteCard in src/og/card.ts, built with the small el(type, style, children) helper (no JSX). Write sizes as px(frame, n), in landscape pixels: the square frame scales them up (scale in OG_FRAMES). Check both frames. The brand mark comes from public/brand-mark.svg, and the site name and domain from src/site.config.ts.

Text (eyebrow format, site-card tagline, truncation): edit src/og/manifest.ts.

New template variant

  1. Add the name to the OgTemplate union in src/og/types.ts.
  2. Write a fooCard(entry) builder in src/og/card.ts and route to it in renderCard.
  3. Build entries with template: "foo" in src/og/manifest.ts.

Which pages get a card

computeEntries() in src/og/manifest.ts builds the list from three sources:

  • Collection pages (posts, resources, legal) come from getPageRecords() in src/lib/page-collections.ts, the same registry as the sitemap. A new page section registered there gets cards automatically.
  • Standalone pages (home, blog index) come from the meta each page exports. A page without title + description falls back to default.
  • default is listed explicitly.

An entry's key is its filename stem under /og/ ("blog/<id>" → /og/blog/<id>.png).

Dimensions and frames

Each frame in OG_FRAMES (src/og/theme.ts) is rendered for every card: width, height, dir (its folder under /og/) and scale (type size against landscape). The meta tags and the endpoint read the list, so adding or resizing a frame is one edit. The landscape frame (keep it 1.91:1) is always listed first, by name. Each frame renders every card again, so it adds build time and files; on a very large site, drop the square frame. The build fails if a frame's dir clashes with a card key.

Satori gotchas

  • Colors must be hex/rgb, not oklch. Tailwind v4 palettes are oklch(), which resvg renders near-black. theme.ts wraps every token in culori's formatHex; keep that on new tokens.
  • Every multi-child container needs display: "flex" and an explicit flexDirection. There's no block layout.
  • No line-clamp. Long text overflows, so the manifest truncates with TITLE_MAX / DESC_MAX. Adjust those caps.

Verify

npm run build   # then open a few dist/og/**.png: colors, font and text
npm run check
npm run lint
npm run format

A broken font or color pipeline still builds but yields blank or black cards, so look at the PNGs. If you changed a card color or font size, recheck the AA pairs above.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.