| name | seo-images |
| description | Image SEO — resolve in-article image placeholders into real images with keyword-rich alt text, descriptive filenames, WebP compression, and lazy loading. Handles featured images and image sitemaps. Powers the media stage of the seo-writing pipeline (Stage 4). |
| allowed-tools | Read, Write, Glob, Grep, Bash |
SEO Images — Alt Text, Compression, Placement
Images are ranking assets and accessibility requirements, not decoration. Every in-body image needs keyword-aware alt text and a descriptive filename; every image needs compression. This skill turns the writer's [[IMAGE_REQUEST:slug]] tags into real, optimized media.
When this skill activates
Implicit: "add images to this article", "write alt text", "optimize these images for SEO", "resolve image placeholders".
Explicit: "Use the seo-images skill to [task]."
Routed from: [[seo-writing]] Stage 4, /mk:seo image actions.
Scope
Covers:
- Resolving
[[IMAGE_REQUEST:slug]] placeholder tags → real images.
- Alt text (keyword-aware, specific, describes the image).
- Descriptive filenames from slugs.
- Compression (→ WebP), lazy loading, featured-image selection.
- Image sitemap entries.
Does NOT cover:
- Writing the article body → [[seo-content]].
- Actually AI-generating an image (use-case → aspect ratio/resolution/domain-mode mapping, prompt construction, model routing) → [[seo-image-gen]], which in turn sits on [[ai-artist]]'s general prompting technique.
Placeholder resolution (the Stage-4 job)
The writer (Stage 3) appends one [[IMAGE_REQUEST:keyword-slug]] per section. Resolve each:
- Extract every tag: regex
\[\[IMAGE_REQUEST:([a-z0-9-]+)\]\].
- Source the image (preference ladder):
| Option | When | Tool |
|---|
| AI-generate | original imagery | [[seo-image-gen]], prompt = keyword + slug |
| Stock/API | fast, generic | image API MCP (source pipeline uses a generate-image/serp webhook) |
| Skip | no infra | delete the tag |
- Write alt text — describe the image AND include the section keyword naturally. Never empty alt.
- Replace the tag with
.
- Cleanup sweep — delete any unresolved tag so a raw
[[IMAGE_REQUEST:...]] never ships.
Alt text rules
| Rule | Example |
|---|
| Describe what's shown | "Activated-carbon filter cross-section" not "image1" |
| Include the keyword naturally | "…activated carbon water filter…" when relevant |
| Specific, not generic | "barista tamping espresso at 30lb pressure" not "coffee" |
| Never empty, never keyword-stuffed | one natural mention, describing the actual image |
Optimization checklist
- Filename — descriptive, from the slug:
activated-carbon-filter.webp, not IMG_2931.jpg.
- Format — WebP (or AVIF) for photos; compress before upload.
- Dimensions — right-sized to display; no 4000px hero for a 800px column.
- Lazy load —
loading="lazy" on below-fold images.
- Featured image — one hero per article, set as the post's featured image (WordPress) + used for social/OG.
Key concepts
- Alt text is dual-purpose — accessibility (screen readers) first, SEO second. Write for a human who can't see the image; the keyword follows naturally.
- Filename is a ranking signal — descriptive filenames help image search; random camera names waste it.
- Weight is a Core Web Vitals cost — uncompressed images tank LCP. Compression isn't optional.
Output
- Optimized images with alt + filenames, embedded in the article markdown (placeholders resolved).
- Featured image set for the post.
- Image-sitemap entries where applicable.
Cross-references
- [[seo-writing]] — Stage 4 consumes this to resolve placeholders
- [[seo-content]] — writer emits the
[[IMAGE_REQUEST:slug]] tags in Stage 3
- [[seo-image-gen]] — AI-generation option for the source ladder above (SEO use-case mapping, prompt construction); returns a finished image for this skill to alt-text/filename/compress
- [[seo-technical]] — Core Web Vitals (image weight impacts LCP)
.claude/workflows/marketing-rules.md — content quality rules
Provenance
Imported from AgriciDaniel/claude-seo and adapted for KitForge. Placeholder-tag resolution matches the seo-writing pipeline's Stage 4 media flow.
