SkillAgentSearch skills...

seo-blog-images

Plan, generate, compress, verify, and wire high-CTR cover images and inline proof visuals into blog posts (MDX, Astro, Next.js, Hugo, HTML) with strict image SEO checks

Install / Use

npx skills add Illyism/seo-skills --skill seo-blog-images

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

92/100

Supported Platforms

Universal

Our assessment of seo-blog-images

seo-blog-images scores 92/100 on our quality scale, 316th of 1,148 Content & Media skills we index (top 28%).

Its SKILL.md is 12 KB long, well organised into 13 sections with 7 code examples: a thorough specification that gives an agent plenty to work with.

It has 531 GitHub stars, a meaningful sign that others use it.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
12/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 38 days ago, so seo-blog-images is actively maintained.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands.

Automated pattern scan on 2026-11-21. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

seo-blog-images compared with similar skills

All 4 of these similar skills score higher than seo-blog-images; compare them before choosing.

SkillScoreStarsUpdatedFormat
seo-blog-images (this skill)by Illyism9253138d agoSKILL.md
taste-skillby Leonxlnx100120.0ktodayCLAUDE.md
LocalAIby mudler10050.5ktodayMCP Server
siyuanby siyuan-note10047.3ktodayMCP Server
algorithmic-artby anthropics100177.9k2mo agoSKILL.md

Frequently asked questions

How do I install seo-blog-images?
Run npx skills add Illyism/seo-skills --skill seo-blog-images. The install tabs above show the steps for each supported agent.
Which AI agents does seo-blog-images work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is seo-blog-images safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is seo-blog-images still maintained?
The repository was last updated 38 days ago, so seo-blog-images is actively maintained.

name: seo-blog-images description: Plan, generate, compress, verify, and wire high-CTR cover images and inline proof visuals into blog posts (MDX, Astro, Next.js, Hugo, HTML) with strict image SEO checks. Use when adding a blog cover or OG image, generating inline visuals without dark icon-box AI slop, capturing real product screenshots or data charts, or auditing image alt text, filenames, and Core Web Vitals attributes. metadata: author: illyism source: https://il.ly/skills/seo-blog-images version: 1.0.0

Blog images and image SEO

The default AI blog visual hurts the post: a dark background with 5 glowing wireframe icons, garbled infographic labels, a 2.4 MB PNG named image-1.png, and no width/height, so the layout jumps on load. This workflow picks the right visual type per slot, produces it (real capture, deterministic chart, or a short-prompt generation), reads every letter back, and wires SEO-complete tags into the post.

Step 0: Find where images live

Which framework is the repo?
├── `next.config.*`, `astro.config.*`, `vite.config.*`, Remix -> files in `public/blog/<slug>/`, src `/blog/<slug>/<name>.webp`
├── Hugo (`hugo.toml` / `config.toml`) -> page bundle next to `index.md`, or `static/blog/<slug>/`
├── Jekyll (`_config.yml`) -> `assets/blog/<slug>/`
└── Other -> match the path pattern of an existing image in a published post

Never invent a new image directory when the repo already has one; mixed locations break the size audit and CDN caching rules.

Step 1: Pick the visual type per slot

Walk this for the cover and for each <h2> that needs a visual:

What is this slot for?
├── Software product review or UI tutorial (`### 1. ToolName`)?
│   └── Path B: real Playwright screenshot or short `<video>` loop.
│       Never ask an image model to draw a real product's UI; readers spot fake dashboards and it misrepresents the product.
├── Benchmark, dataset, or any chart with numbers?
│   └── Path C: deterministic SVG chart from the real numbers.
│       Never ask an image model for charts or tables; it invents bar heights and misspells values.
├── Cover / OpenGraph (`og:image`)?
│   └── Path A: 16:9, 12-22 word prompt, 1 focal scene + a 3-6 word headline badge.
└── Inline concept (workflow, pricing contrast, architecture)?
    ├── Does a 2-4 word contrast label make the point in half a second?
    │   └── Path A: topic-literal scene + 2-4 quoted labels (`"MANUAL CSV"` vs `"LIVE WEBHOOK"`). No invented numbers.
    └── Otherwise -> Path A: zero-text close-up, 12-20 words, tight framing.

Step 2: Prompt rules (Path A only)

  1. Brief like a designer (1–2 plain sentences). Long prompts with motif checklists make image models crowd the frame with generic chrome or repeat the same arrows/badges on every post; short plain briefs produce calm, focused visuals.
  2. Trust over neon clickbait. Technical and SEO readers immediately distrust neon rim lighting, glowing 3D icons, rockets, robot arms, holographic brains, and YouTube-thumbnail text. Visual pop comes from quiet matte surfaces and crisp dark-vs-light contrast between real recognizable artifacts (Terminal, GitHub PRs, Search Console, browser/code diffs) — or clean daylight studio/editorial scenes.
  3. Use 2–3 full-res style references (--ref) when the repo has a brand kit. Let the reference images carry surface, typography, and restraint rather than repeating hex codes and style adjectives in every prompt. Keep clean (unannotated) references separate from annotated references so the model does not auto-stamp arrows or filler subtitle pills onto every image.
  4. Evergreen copy, zero invented or stale numbers: Never invent metrics, domains, or product claims, and avoid baking mutable SaaS prices, Top-N rankings, or em-dashes into static covers or inline concept diagrams (prices and rankings change often and force image regenerations). Only put exact numbers in images when illustrating a permanent benchmark or verified proof point.
    • querybench.dev cover: "Calm matte dark editorial cover titled 'Postgres CI Branching (2026)' showing a dark terminal running 'qb branch create' beside a crisp white GitHub PR check showing 'Branch ready · Passed'."
    • invoicekit.io inline: "Side-by-side comparison on a matte dark surface: left dark billing statement highlighting 'Percentage fee per invoice' beside a crisp white invoice card reading 'Flat monthly plan · API included'."

Step 3: Produce the file

Scaffold the image script (once per repo)

If scripts/seo-image.mjs does not exist, create it. It handles both generation (Path A) and compression of any existing PNG (Paths B and C), so every image goes through the same size pipeline.

// scripts/seo-image.mjs
// Generate: node scripts/seo-image.mjs --prompt "<12-22 words>" --out public/blog/<slug>/<keyword-name>.webp
// Compress: node scripts/seo-image.mjs --input /tmp/raw.png --out public/blog/<slug>/<keyword-name>.webp
// Options:  --quality 82 (lower it if the file is over budget), --model <openrouter-image-model>
import fs from "node:fs/promises";
import path from "node:path";
import { parseArgs } from "node:util";
import sharp from "sharp";

const { values: a } = parseArgs({
  options: {
    prompt: { type: "string" },
    input: { type: "string" },
    out: { type: "string" },
    quality: { type: "string", default: "82" },
    model: { type: "string", default: "google/gemini-2.5-flash-image" },
  },
});
if (!a.out || (!a.prompt && !a.input)) {
  console.error("Usage: --prompt <text> | --input <file>, plus --out <path.webp|.jpg>");
  process.exit(1);
}

let raw;
if (a.input) {
  raw = await fs.readFile(a.input);
} else {
  if (!process.env.OPENROUTER_API_KEY) {
    console.error("OPENROUTER_API_KEY is not set");
    process.exit(1);
  }
  const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: a.model,
      messages: [{ role: "user", content: a.prompt }],
      modalities: ["image", "text"],
      image_config: { aspect_ratio: "16:9" },
    }),
  });
  const data = await res.json();
  const url = data?.choices?.[0]?.message?.images?.[0]?.image_url?.url;
  if (!res.ok || !url) {
    console.error(`Generation failed (${res.status}): ${JSON.stringify(data).slice(0, 300)}`);
    process.exit(1);
  }
  raw = Buffer.from(url.replace(/^data:image\/\w+;base64,/, ""), "base64");
}

await fs.mkdir(path.dirname(a.out), { recursive: true });
const q = Number(a.quality);
const img = sharp(raw).resize({ width: 1536, withoutEnlargement: true });
const buf = /\.jpe?g$/i.test(a.out)
  ? await img.jpeg({ quality: q, mozjpeg: true }).toBuffer()
  : await img.webp({ quality: q }).toBuffer();
await fs.writeFile(a.out, buf);
const { width, height } = await sharp(buf).metadata();
console.log(`${a.out} ${width}x${height} ${Math.round(buf.length / 1024)} KB`);

Install sharp with the repo's package manager: pnpm add -D sharp (pnpm-lock.yaml), bun add -d sharp (bun.lock), yarn add -D sharp (yarn.lock), else npm i -D sharp. If the repo has no package.json (Hugo, Jekyll), put the script in /tmp/seo-image/, run npm init -y && npm i sharp there, and pass absolute --out paths, so the repo gains no Node tooling it does not use.

If OPENROUTER_API_KEY is missing, generate with the agent's built-in image tool, save the PNG to /tmp/, and run the script in --input mode.

Path A: generate

node scripts/seo-image.mjs --prompt "<prompt from Step 2>" --out public/blog/<slug>/<keyword-name>.webp

Use .jpg for the cover when the site's OG pipeline rejects WebP; use .webp everywhere else.

Path B: real screenshot

npx playwright install chromium   # first run only
npx playwright screenshot --viewport-size "1440, 900" --wait-for-timeout 1500 \
  "https://querybench.dev" /tmp/raw-shot.png
node scripts/seo-image.mjs --input /tmp/raw-shot.png --out public/blog/postgres-tools/querybench-explain-analyze-ui.webp

Path C: deterministic chart

For numbers from the post or seo/kb/proof/benchmarks/*.md, write a self-contained 1536x864 SVG: bar lengths computed from the values (cap the longest horizontal bar at 760px so right-hand value labels never clip at the 1536px edge), every value printed as a label, font-family="system-ui, -apple-system, sans-serif", dark text on a light background. Save it as /tmp/<name>.svg, then convert with --input /tmp/<name>.svg. Every number on the chart then matches the source exactly.

Step 4: Read back every image

Open every generated file with the agent's file-viewing tool right after saving. Image models misspell ("BENCHMMARK"), duplicate letters, and clip text at the edge.

  • Check every quoted word letter by letter and confirm it sits fully inside the frame.
  • Garbled, blurry, duplicated, or clipped text, or a dark icon-box layout: delete the file and regenerate with a 12-16 word prompt. After 2 failed attempts, switch that slot to zero-text mode.

Step 5: Wire it in with full image SEO

  1. Keyword kebab-case filenames naming the subject (postgres-zfs-branch-spinup-benchmark.webp). Never image1.png, hero.webp, screenshot-2026.png, or UUIDs, because the filename is one of the few text signals image search reads.
  2. alt text of 80-160 characters stating what the image shows in the post's terms. Never start with "Image of", "Picture of", or "An infographic showing"; screen readers already announce the image.
    • Bad: "An infographic of database branching speed" (43 chars, generic).
    • Good: "Comparison of 50GB Postgres CI branch creation times showing ZFS copy-on-write cloning in 1.8 seconds versus 14 minutes for pg_restore" (134 chars).
  3. Explicit width and height equal to the intrinsic pixels the script printed, on every <img> and <Image>, so the browser reserves the space and the layout does not shift.
  4. Loading priority:
    • Cover / above-the-fold hero only: priority (Next.js) or fetchpriority="high" + loading="eager", because it is the LCP element.
    • Every image below the fold: loading="lazy" and decoding="async". Never priority on body images; it competes with the hero for bandwidth.
  5. Size budgets:
    • Cover: 1200px or wider, 350 KB or less. Also set it in frontmatter (image / cover / openGraph.images) so X, LinkedIn, Slack, and Google Discover render the large card.
    • Inline: 220 KB or less, .webp. Over budget: re-run with --quality 72, then --quality 62.
  6. Placement: put inline images after the first paragraph of their <h2> section, never between the heading and its first sentence. Featured snippet extraction and readers both expect the text answer directly under the heading.
## How much faster is ZFS copy-on-write branching than pg_restore in CI?

Cloning a 50.4 GB Postgres 16 database with `pg_restore -j 4` takes a median of 14 minutes and 22 seconds in GitHub Actions. A ZFS copy-on-write snapshot boots the same 180-million-row dataset in 1.8 seconds.

<Image
  src="/blog/postgres-ci-testing/postgres-zfs-branch-spinup-benchmark.webp"
  alt="Benchmark comparison showing QueryBench ZFS copy-on-write booting a 50GB Postgres branch in 1.8 seconds compared to 14 minutes for pg_restore"
  width={1536}
  height={864}
  loading="lazy"
  decoding="async"
/>

Step 6: Audit before finishing

dir=public/blog/<slug>; post=content/blog/<slug>.mdx
for f in "$dir"/*; do
  n=$(basename "$f"); kb=$(( $(wc -c < "$f") / 1024 ))
  echo "$kb KB  $n"
  [ "$kb" -gt 350 ] && echo "  FAIL: over 350 KB"
  [ "$kb" -gt 220 ] && echo "  CHECK: only the cover may exceed 220 KB"
  echo "$n" | grep -qiE '^(image|img|hero|screenshot|untitled)[-_.0-9]|^[0-9a-f]{8}-' && echo "  FAIL: generic fil

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars531
CategoryContent
Updated1mo ago
Forks56

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium