Agent skill

Image Optimization

by kostja94 in kostja94/marketing-skills

When the user wants to optimize images for search engines and performance.

MITAuto-check passedFrontend & Design

Install Image Optimization

skills CLI
$ npx skills add kostja94/marketing-skills --skill image-optimization -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install kostja94/marketing-skills image-optimization --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/kostja94/marketing-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/seo/on-page/image-optimization .claude/skills/image-optimization && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
image-optimization
GitHub stars
1k
Token cost
~2.7k tokens
SKILL.md length
1,053 words
Files
1
Skills in repo
102
Repo updated
First seen
Licence
MIT

At a glance

When the user wants to optimize images for search engines and performance.

  • Works in 9 steps: Discovery & Indexing → Format & Performance → Alt Text → …
  • Wants to optimize images for search engines and performance
  • SKILL.md covers Scope, Initial Assessment, 1. Discovery & Indexing and 2. Format & Performance, plus 9 more sections
  • Reaches sitemaps.org and google.com

What it does

Image Optimization is an agent skill from kostja94/marketing-skills. When the user wants to optimize images for search engines and performance. Also use when the user mentions "image SEO," "alt text," "image captions," "figcaption," "image optimization," "WebP," "lazy loading," "LCP," "image sitemap," "responsive images," "srcset," "image format," or "hero image optimization." For CWV, use core-web-vitals.

Its SKILL.md is about 2.7k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Frontend & Design, covering Web performance. The repository describes itself as: Agent Skills for Marketing — SEO, Social, Influencer & More. 160+ open-source skills for SEO, content, 40+ page types, paid ads, channels, and strategies. Add project context… The licence is MIT.

When your agent uses it

  • Wants to optimize images for search engines and performance
  • The user mentions image SEO
  • Image optimization
  • Responsive images

Example prompts

  • “image SEO,”
  • “alt text,”
  • “image captions,”
  • “/image-optimization”

Workflow steps

9 steps, taken from the step headings in SKILL.md.

  1. Discovery & Indexing
  2. Format & Performance
  3. Alt Text
  4. File Names
  5. Preferred Image (SERP Thumbnail & Discover)
  6. Page Context
  7. Structured Data
  8. Specs by Context
  9. Opt-Out & SafeSearch

What it can do on your machine

Read from SKILL.md and the folder at commit 8dd89c5. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are html, xml and json).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • sitemaps.org
    • google.com
    • schema.org

    Also links to:

    • developers.google.com
    • semrush.com
    • web.dev
    • searchengineland.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Image Optimization loads about 2.7k tokens when it runs. Until then it costs about 90 tokens; SKILL.md has 1,053 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~90
When it runs · the whole SKILL.md, loaded when a task matches
~2.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from kostja94/marketing-skills at commit 8dd89c5, republished under its MIT licence (© kostja94). 1,053 words, ~2,688 tokens.

Download SKILL.mdSave it as .claude/skills/image-optimization/SKILL.md (or your agent's skills folder).
name
image-optimization
description
When the user wants to optimize images for search engines and performance. Also use when the user mentions "image SEO," "alt text," "image captions," "figcaption," "image optimization," "WebP," "lazy loading," "LCP," "image sitemap," "responsive images," "srcset," "image format," or "hero image optimization." For CWV, use core-web-vitals.
metadata.version
1.2.1

SEO On-Page: Image Optimization

Guides image optimization for Google Search (text results, Image Pack, Google Images, Discover), Core Web Vitals (LCP), and accessibility. Consolidates image-related best practices from components (hero, trust-badges) and pages (landing-page). References: Google Image SEO, Semrush Image SEO.

When invoking: On first use, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On subsequent use or when the user asks to skip, go directly to the main output.

Scope

  • Discovery & indexing: HTML img elements, image sitemap
  • Format & performance: WebP, responsive images, lazy loading, LCP; full CWV optimization in core-web-vitals
  • Metadata: Alt text, file names, captions
  • Preferred image: primaryImageOfPage, og:image; thumbnail next to title/description in search results
  • Structured data: ImageObject, image in Article/Product/etc.

Initial Assessment

Project context: Read root contextus.md when present and load only the modules relevant to this task. Without Contextus, use available project material or user-provided facts and ask for missing information; do not create a parallel context system.

Identify:

  1. Context: Hero, content page, product, trust badge, social preview
  2. Above vs below fold: LCP candidate (hero) vs lazy-loadable
  3. Image count: Single hero vs gallery, programmatic pages

1. Discovery & Indexing

Use HTML Image Elements

Google finds images in the src attribute of <img> (including inside <picture>). CSS background images are not indexed.

DoDon't
<img src="puppy.jpg" alt="Golden retriever puppy" /><div style="background-image:url(puppy.jpg)">
Image Sitemap

Submit an image sitemap to help Google discover images it might otherwise miss. Image sitemaps can include URLs from CDNs (other domains); verify CDN domain in Search Console for crawl error reporting.

Structure (from Google):

xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
  <url>
    <loc>https://example.com/page</loc>
    <image:image>
      <image:loc>https://example.com/image.jpg</image:loc>
    </image:image>
  </url>
</urlset>

See xml-sitemap for sitemap index and submission. Image sitemap is an extension; can be standalone or combined with page sitemap.


2. Format & Performance

Supported Formats

Google supports: BMP, GIF, JPEG, PNG, WebP, SVG, AVIF. Match filename extension to format.

FormatBest forNotes
WebPPhotos, graphicsSmaller files, faster load; lossy + lossless; transparency, animation
AVIFModern browsersEven smaller than WebP; check support
JPEGStandard photosFallback; widely supported
PNGTransparency, detailLarger; use when needed
SVGIcons, logosScalable; use <title> for inline SVG alt
GIFSimple animationFirst frame only for preview
Responsive Images

Use <picture> or srcset for different screen sizes. Always provide fallback src—some crawlers don't understand srcset.

html
<img
  srcset="image-320w.jpg 320w, image-480w.jpg 480w, image-800w.jpg 800w"
  sizes="(max-width: 320px) 280px, (max-width: 480px) 440px, 800px"
  src="image-800w.jpg"
  alt="Descriptive alt text">

Picture element (format fallback, e.g. WebP → PNG):

html
<picture>
  <source type="image/webp" srcset="image.webp">
  <img src="image.png" alt="Descriptive alt text">
</picture>
Data URI (Inline Images)

Base64 data URIs (data:image/...;base64,...) reduce HTTP requests but increase HTML size. Use sparingly for small icons; avoid for large images. See web.dev.

Resize & Compress
  • Max width: Generally ≤2,500px; match container max-width
  • Compression: WebP preferred; quality 75–85 for lossy; 72dpi for web
  • LCP: Hero/above-fold images are LCP candidates; optimize aggressively
Lazy Loading

Use loading="lazy" only for below-fold images. Above-fold images (hero) must load immediately—lazy loading them hurts LCP.

html
<img src="hero.jpg" alt="..." loading="eager">
<img src="below-fold.jpg" alt="..." loading="lazy">

3. Alt Text

Alt text improves accessibility (screen readers, low bandwidth) and SEO (Google uses it with computer vision to understand images). It also serves as anchor text if the image is a link.

Best Practices
DoDon't
Useful, information-rich descriptionKeyword stuffing
Context of page content"image of" or "photo of" (redundant)
Max ~125 characters (some assistive tech truncates)Empty alt on meaningful images
Descriptive for functional imagesAlt on purely decorative images (use alt="")

Examples (from Google):

  • ❌ Missing: <img src="puppy.jpg"/>
  • ❌ Stuffing: alt="puppy dog baby dog pup pups puppies..."
  • ✅ Better: alt="puppy"
  • ✅ Best: alt="Dalmatian puppy playing fetch"
Captions

Google extracts image context from captions and nearby text. Use <figcaption> or descriptive text near the image.

UsePurpose
Topic relevanceCaption describes image subject; supports indexing
Featured SnippetsImages near answers with captions can capture thumbnail slots; see featured-snippet
Image PackAlt + caption + file name help Image Pack display; see serp-features
Inline SVG

Use <title> inside SVG for accessibility:

html
<svg aria-labelledby="svgtitle1">
  <title id="svgtitle1">Descriptive text for the SVG</title>
</svg>

4. File Names

Descriptive filenames give Google light clues about subject matter.

DoDon't
apple-iphone-15-pink-side-view.jpgIMG00353.jpg
Short, hyphen-separatedGeneric: image1.jpg, pic.gif
Localize filenames for translated pagesOverly long filenames

Show full SKILL.md (410 more words)Show less

5. Preferred Image (SERP Thumbnail & Discover)

When users search for keywords, optimized images can appear as thumbnails next to the page title and description in search results—enhancing visibility and CTR. Google also uses these images for Google Discover. Search Engine Land

Google selects thumbnails automatically from multiple sources. Influence selection via:

Schema: primaryImageOfPage
json
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "url": "https://example.com/page",
  "primaryImageOfPage": "https://example.com/images/cat.png"
}

Or attach image to main entity (e.g. BlogPosting, Article) via mainEntity or mainEntityOfPage.

Open Graph
html
<meta property="og:image" content="https://example.com/images/cat.png">

Preferred image rules: Relevant, representative; avoid generic (e.g. logo) or text-heavy images; avoid extreme aspect ratios; high resolution. See open-graph, twitter-cards for social specs.

Google Discover (if targeting Discover): ≥1200px wide; ≥300KB; 16:9 aspect ratio preferred; important content visible in landscape crop.


6. Page Context

  • Title & meta description: Google uses page title and meta for image result snippets. See title-tag, meta-description.
  • Placement: Put images near relevant text; page subject matter influences image indexing.
  • Same URL: Reference the same image with the same URL across pages for cache efficiency and crawl budget.

7. Structured Data

Add structured data for rich results in Google Images (badges, extra info). Image attribute is required for eligibility. See schema-markup for ImageObject, Article, Product, Recipe, etc.


8. Specs by Context

ContextPriorityNotes
HeroLCP, alt, no lazySee hero-generator; above-fold, fast load
Article / Blog hero1200–1600px wide; proportional height; 1200×630 for og:imageSame image for Schema, Open Graph, Twitter Cards; under 200 KB; WebP preferred; descriptive alt; set width/height to prevent CLS; use srcset/sizes for responsive; articles with relevant images get ~94% more views
Trust badgesAlt textSee trust-badges-generator; e.g. "Norton Secured"
Landing pageAll aboveSee landing-page-generator Pre-Delivery Checklist
OG / Twitter1200×630, 1200×675See open-graph, twitter-cards
PlatformsPer-platformX, LinkedIn, Pinterest—see platform skills

9. Opt-Out & SafeSearch

  • Inline linking opt-out: Prevent full-sized image display in Google Images via HTTP referrer check (200 or 204). See Google docs.
  • SafeSearch: Label pages for explicit content if applicable.

Output Format

  • Alt text suggestions per image
  • Captions (if applicable; snippet/Image Pack context)
  • File name recommendations
  • Format (WebP, fallback)
  • Responsive (srcset/sizes or picture)
  • Lazy loading (above-fold vs below-fold)
  • Image sitemap (if many images)
  • Preferred image (schema, og:image) for key pages
  • core-web-vitals: LCP, INP, CLS; image optimization supports LCP
  • xml-sitemap: Sitemap structure; image sitemap extension
  • open-graph, twitter-cards: og:image, twitter:image; social preview
  • schema-markup: ImageObject, Article/Product image
  • content-optimization: Multimedia in content; defers image SEO to this skill
  • featured-snippet: Images near answers + captions; snippet thumbnail
  • serp-features: Image Pack; alt, captions, file names
  • visual-content: Visual content for social, infographics; website images use this skill

© kostja94, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/seo/on-page/image-optimization of kostja94/marketing-skills.

Open the folder on GitHubat commit 8dd89c5

Compare with similar skills

Image Optimization next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Image Optimization compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Image Optimization this skillkostja94/marketing-skills1k—~2.7kAutomated safety check: PassMIT
React Doctormakeplane/plane61k12 repos~657Automated safety check: PassAGPL-3.0
Fixing Motion Performanceibelick/ui-skills9.5k5 repos~1.4kAutomated safety check: PassMIT
GSAP Performance Tuninggreensock/gsap-skills16k4 repos~1kAutomated safety check: PassMIT
React Frontend Development Guidelinesdiet103/claude-code-infrastructure-showcase10k2 repos~2.9kAutomated safety check: PassMIT
Web Quality Auditaddyosmani/web-quality-skills2.9k—~2.6kAutomated safety check: PassMIT

Similar skills

  • React Doctor

    makeplane/plane

    Scans React code for lint, accessibility, bundle size and architecture issues, reports a health score and checks that changes do not lower it.

    61k GitHub starsUsed in 12 repos~657 tokens
    Frontend & DesignAuto-check passed
  • Fixing Motion Performance

    ibelick/ui-skills

    Audits and fixes web animation performance: layout thrashing, work that belongs on the compositor, scroll-linked motion and costly blur effects.

    9.5k GitHub starsUsed in 5 repos~1.4k tokens
    Frontend & DesignAuto-check passed
  • GSAP Performance Tuning

    greensock/gsap-skills

    Guides the agent to keep GSAP animations smooth by animating transforms and opacity, batching DOM reads and writes, and avoiding layout-heavy properties.

    16k GitHub starsUsed in 4 repos~1k tokens
    Frontend & DesignAuto-check passed
  • React Frontend Development Guidelines

    diet103/claude-code-infrastructure-showcase

    Guidelines for React 18 and TypeScript apps covering Suspense data fetching, lazy loading, feature folders, MUI v7 styling, TanStack Router and performance.

    10k GitHub starsUsed in 2 repos~2.9k tokens
    Frontend & DesignAuto-check passed
  • Web Quality Audit

    addyosmani/web-quality-skills

    Run an evidence-led web quality audit covering performance, accessibility, SEO, best practices, and agentic browsing.

    2.9k GitHub stars~2.6k tokensUpdated 1 mo ago
    Frontend & DesignAuto-check passed
  • SEO Google

    AgriciDaniel/codex-seo

    Google SEO APIs: Search Console (Search Analytics, URL Inspection, Sitemaps), PageSpeed Insights v5, CrUX field data with 25-week history, Indexing API v3, and GA4 organic traffic.

    791 GitHub starsUsed in 2 repos~3.4k tokens
    Frontend & DesignAuto-check passed

More from kostja94/marketing-skills

All 102 skills in this repo
  • Grokipedia Recommendations

    kostja94/marketing-skills

    When the user wants to add recommendations, links, or content to Grokipedia.

    1k GitHub starsUsed in 1 repo~4.2k tokens
    Auto-check passed
  • AI Traffic Tracking

    kostja94/marketing-skills

    When the user wants to track AI search traffic in GA4 or GSC.

    1k GitHub stars~959 tokensUpdated 2 days ago
    Auto-check passed
  • Analytics Tracking

    kostja94/marketing-skills

    When the user wants to set up, audit, or optimize analytics tracking (GA4, events, conversions).

    1k GitHub stars~1.5k tokensUpdated 2 days ago
    Auto-check passed
  • Brand Visual Generator

    kostja94/marketing-skills

    When the user wants to define, audit, or apply visual identity (typography, colors, spacing, design tokens, frontend aesthetics).

    1k GitHub stars~3k tokensUpdated 2 days ago
    Auto-check passed
  • Canonical Tag

    kostja94/marketing-skills

    When the user wants to configure canonical URLs, fix duplicate content, or consolidate URL signals.

    1k GitHub stars~1.2k tokensUpdated 2 days ago
    Auto-check passed
  • Content Strategy

    kostja94/marketing-skills

    When the user wants to plan content for SEO, create content calendar, or build topic clusters.

    1k GitHub stars~1.8k tokensUpdated 2 days ago
    Auto-check passed

Questions about Image Optimization

What does Image Optimization do?

When the user wants to optimize images for search engines and performance. Image Optimization is an agent skill from kostja94/marketing-skills. When the user wants to optimize images for search engines and performance.

When should I use Image Optimization?

Image Optimization fits situations like: wants to optimize images for search engines and performance; the user mentions image SEO; image optimization; responsive images.

How do I install Image Optimization in Claude Code?

Run `npx skills add kostja94/marketing-skills --skill image-optimization -a claude-code`. Or copy the skill folder (skills/seo/on-page/image-optimization in kostja94/marketing-skills) into .claude/skills/image-optimization in your project. Claude Code loads it when a task matches its description.

How do I install Image Optimization in Codex?

Run `npx skills add kostja94/marketing-skills --skill image-optimization -a codex`. Or copy the skill folder (skills/seo/on-page/image-optimization in kostja94/marketing-skills) into .agents/skills/image-optimization in your project. Codex loads it when a task matches its description.

Can I use Image Optimization in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add kostja94/marketing-skills --skill image-optimization -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/image-optimization, .gemini/skills/image-optimization, .github/skills/image-optimization and .opencode/skills/image-optimization in your project.

What does Image Optimization need to run?

SKILL.md names no scripts, command-line tools or credentials: Image Optimization is instructions for the agent only.

Does Image Optimization access the network?

SKILL.md names 7 domains. In commands or code: sitemaps.org, google.com and schema.org; the agent is likely to contact these when it follows the instructions. As links in the text: developers.google.com, semrush.com, web.dev and searchengineland.com. This is read from the text; nothing was executed.

Is Image Optimization safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Image Optimization use?

Image Optimization is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Image Optimization use?

About 2.7k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Image Optimization?

Skills that share tags, products or a category with Image Optimization: React Doctor (makeplane/plane, 61k stars), Fixing Motion Performance (ibelick/ui-skills, 9.5k stars), GSAP Performance Tuning (greensock/gsap-skills, 16k stars) and React Frontend Development Guidelines (diet103/claude-code-infrastructure-showcase, 10k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Image Optimization?

kostja94 (a GitHub user) maintains it in kostja94/marketing-skills, which has 1,019 GitHub stars. The repository holds 102 skills in this directory. The repository was last updated on October 6, 2026.

Source: kostja94/marketing-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.