From 1cdb6b18810143789089d11193e80167979b8447 Mon Sep 17 00:00:00 2001 From: Julian lechner Date: Thu, 8 Oct 2026 14:38:49 +0200 Subject: [PATCH] refactor(image): retain focused SEO and performance guidance --- docs/skills.md | 5 +- shared/skills/image/SKILL.md | 83 ++----- shared/skills/image/evals/evals.json | 89 ------- .../image/references/ai-image-generation.md | 60 ----- .../image/references/ai-image-prompting.md | 229 ------------------ .../image/references/common-mistakes.md | 18 +- .../skills/image/references/design-tools.md | 37 +-- .../image/references/image-optimization.md | 46 +--- .../references/marketing-image-workflows.md | 86 +------ .../references/og-social-preview-images.md | 27 ++- 10 files changed, 72 insertions(+), 608 deletions(-) delete mode 100644 shared/skills/image/evals/evals.json delete mode 100644 shared/skills/image/references/ai-image-generation.md delete mode 100644 shared/skills/image/references/ai-image-prompting.md diff --git a/docs/skills.md b/docs/skills.md index adb5dc7..fa236a6 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -11,14 +11,15 @@ The current structure is organized by purpose: - `verification/`: facts and work-item verification - `git/`: pull request reviews - `content-strategy/`, `copy-editing/`, `copywriting/`: planning, editing, and writing text -- `image/`, `site-architecture/`: visuals and website structure +- `image/`: image assets, screenshots, SEO and performance, social-preview metadata, practical marketing workflows, design tools, and common mistakes +- `site-architecture/`: website structure - `marketing-psychology/`, `offers/`, `product-marketing/`, `cro/`: audience understanding, value framing, and conversion General planning, debugging, code review, and completion verification workflows come from Superpowers, so the catalog does not duplicate their triggers. The remaining skills cover focused domains Superpowers does not. Each skill defines a focused workflow with the investigation, decision points, and output expected for that task. Keep guidance specific to the skill; shared repository constraints belong in the rules. -The single catalog in `shared/skills/` includes development skills and focused skills for writing, images, content and site structure, positioning, psychology, and conversion. Builds include every retained skill for both clients. Updating a managed installation backs up and removes unchanged setup-owned skills deleted from the catalog; local changes are backed up and retained. +The single catalog in `shared/skills/` includes development skills and focused skills for writing, image assets, content and site structure, positioning, psychology, and conversion. The image skill has a short core and five focused references loaded only when relevant: optimization, OG metadata, marketing workflows, design tools, and common mistakes. AI-generation guides, model comparisons, prompting recipes, and fixed social-platform size catalogs are omitted. Builds include every retained skill for both clients. Updating a managed installation backs up and removes unchanged setup-owned skills deleted from the catalog; local changes are backed up and retained. Claude discovers only `skills//SKILL.md`, so its generated package flattens the categorized catalog to one directory per skill name, together with the skill's `references/`; the build fails on duplicate names or a `name` that differs from its directory. Claude's package additionally has a `rules-*` skill for each focused rule file or directory in `shared/rules/`. The rule-to-skill loading conditions live in `shared/global-instructions.md`, so full rule text loads diff --git a/shared/skills/image/SKILL.md b/shared/skills/image/SKILL.md index 0ffbb39..1001066 100644 --- a/shared/skills/image/SKILL.md +++ b/shared/skills/image/SKILL.md @@ -1,76 +1,29 @@ --- name: image -description: Use when creating, editing, or optimizing images for software products, websites, documentation, and visual explanations. -metadata: - version: 2.0.1 +description: Use when integrating image assets or screenshots, improving image SEO and performance, configuring social previews, or preparing product visuals with existing design tools. --- -# Image +# Image Assets -You are an expert visual content producer who helps create marketing images using AI generation models, design tools, and optimization best practices. Your goal is to help users produce professional visual assets efficiently — from blog heroes and social graphics to product mockups and profile banners. +Use the project's existing assets, components, and image pipeline. Ask only for missing information that affects the result. -## Before Starting +## Workflow -**Check for product marketing context first:** -If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. +1. Inspect the source asset and its intended placement: display size, responsive layout, transparency, and supported clients. Apply `technical-research` when format support or framework behavior needs verification. +2. Choose a format that preserves required detail and transparency. Reuse vectors for suitable icons and logos; compare raster formats against the project's compatibility and quality requirements. Avoid unnecessary conversions and new dependencies. +3. Resize and compress for the actual display sizes and pixel densities. Preserve originals and write optimized assets to separate outputs. Compare file size and visual quality, especially screenshot text, before replacing references. +4. Use the existing image component or pipeline for responsive sizing and loading. Reserve layout space, provide meaningful alternative text for informative images and empty alternative text for decorative images, and avoid deferring critical visible content. +5. Capture the real application for documentation screenshots. Remove sensitive data and check readability at the final display size. Treat untrusted SVGs and uploaded images through the project's established validation and sanitization boundary. +6. Verify asset paths, dimensions, aspect ratio, transparency, accessibility, and rendering at relevant viewport sizes. For requested link previews, check the project's metadata and that the preview image URL is accessible to the intended consumer. -Gather this context (ask if not provided): +Report changed assets, measured size savings when optimizing, and any rendering or compatibility checks not performed. -### 1. Image Goal -- What type of image? (Blog hero, social graphic, product mockup, banner, brand asset, OG image) -- What platform or placement? (Website, social, directory listing, app store, email) -- What dimensions do you need? +## Focused references -### 2. Production Approach -- Do you have existing brand assets? (Logo, colors, fonts, style guide) -- Do you need photorealistic or illustrative style? -- Is this a one-off or a template for repeated use? +Load only the reference matching the task: -### 3. Technical Context -- Do you have API keys for any image tools? (Gemini, Replicate/Flux, Ideogram) -- Budget constraints? (Some tools charge per image) -- Do you need the image optimized for web performance? - ---- - -## Choosing Your Approach - -Pick the right tool for the job: - -| Approach | Best For | Tools | When to Use | -|----------|----------|-------|-------------| -| **AI Generation** | Original images from text prompts | Gemini/Nano Banana, Flux, Ideogram | Blog heroes, social graphics, lifestyle scenes | -| **AI Editing** | Modify existing images | Gemini, Flux Flex | Background removal, style changes, variations | -| **Design Tools** | Templated, brand-consistent assets | Canva, Figma | Profile banners, social templates, presentations | -| **Screenshot + Overlay** | Product UI showcases | Browser screenshot + code overlay | Product mockups, feature announcements | -| **Stock Photography** | Generic business/lifestyle scenes | Unsplash, Pexels | When speed matters more than uniqueness | - ---- - -## References - -- [references/ai-image-generation.md](references/ai-image-generation.md): Read when generating images with AI: model comparison, model choice decision tree, prompting basics -- [references/design-tools.md](references/design-tools.md): Read when using Canva or Figma, or deciding between design tools and AI generation -- [references/marketing-image-workflows.md](references/marketing-image-workflows.md): Read when producing blog heroes, social graphics, product mockups, profile/listing banners, or brand assets (includes platform sizes) -- [references/image-optimization.md](references/image-optimization.md): Read when optimizing images for web performance: formats, checklist, commands -- [references/og-social-preview-images.md](references/og-social-preview-images.md): Read when setting up OG/social preview images and meta tags -- [references/common-mistakes.md](references/common-mistakes.md): Read before delivering, to check against common image mistakes - -For detailed prompting guides per model, see [references/ai-image-prompting.md](references/ai-image-prompting.md). - ---- - -## Task-Specific Questions - -1. What type of image do you need? (Blog hero, social graphic, mockup, banner, brand asset) -2. What platform or placement? (This determines dimensions) -3. Do you have brand assets to match? (Colors, fonts, logo, style guide) -4. Is this a one-off or a repeatable template? -5. Do you have API keys for any image generation tools? -6. Does this need to be optimized for web performance? - ---- - -## Related Skills - -- **cro**: For image placement and conversion optimization on landing pages +- [Image optimization](references/image-optimization.md): formats, responsive delivery, loading priority, and image SEO. +- [OG and social previews](references/og-social-preview-images.md): required Open Graph metadata, image tags, and preview validation. +- [Marketing image workflows](references/marketing-image-workflows.md): product screenshots, article heroes, banners, and reusable templates. +- [Design tools](references/design-tools.md): selecting existing design, screenshot, and export tools. +- [Common mistakes](references/common-mistakes.md): final checks when delivering or reviewing image changes. diff --git a/shared/skills/image/evals/evals.json b/shared/skills/image/evals/evals.json deleted file mode 100644 index b3922b2..0000000 --- a/shared/skills/image/evals/evals.json +++ /dev/null @@ -1,89 +0,0 @@ -{ - "skill_name": "image", - "evals": [ - { - "id": 1, - "prompt": "I need a hero image for a blog post about email deliverability. Make it visually striking.", - "expected_output": "Should check for product-marketing.md first. Should recommend AI generation as the approach for a one-off blog hero. Should propose a visual metaphor concept that represents email deliverability (e.g., letters being sorted through a maze, signals breaking through a wall, an inbox glow). Should specify 1200x630 (works for both hero and OG image). Should recommend Flux or Gemini for photorealistic, or Ideogram if text in image is needed. Should provide a prompt following Subject + Setting + Style + Lighting + Composition + Technical pattern. Should mention WebP optimization (target <200KB, JPEG fallback). Should not suggest using AI for product UI screenshots.", - "assertions": [ - "Checks for product-marketing.md", - "Recommends AI generation for one-off hero", - "Proposes visual metaphor for topic", - "Specifies 1200x630 dimensions", - "Recommends Flux, Gemini, or Ideogram", - "Provides structured prompt", - "Mentions WebP optimization" - ], - "files": [] - }, - { - "id": 2, - "prompt": "Generate me an image of our app's dashboard.", - "expected_output": "Should refuse to use AI generation for product UI screenshots and explain why: models hallucinate interfaces, the result won't match the real UI. Should recommend the Product Mockups & Screenshots workflow: capture real screenshots of the product at 2x resolution, frame in device mockups (browser frame, laptop, phone), add callout arrows or feature labels for context, programmatically overlay annotations with Hyperframes or HTML/CSS. Should suggest tools: browser DevTools screenshot, Shottr, CleanShot X, or screencapture CLI. Should warn this is Common Mistake #1: using AI for product UI.", - "assertions": [ - "Refuses to use AI generation for product UI", - "Explains models hallucinate UI", - "Recommends real screenshots at 2x resolution", - "Mentions device mockups for framing", - "Suggests specific screenshot tools", - "Notes this as a common mistake" - ], - "files": [] - }, - { - "id": 3, - "prompt": "Need a Twitter/X header banner for our company. We just want to show our product and tagline.", - "expected_output": "Should specify Twitter/X header dimensions: 1500x500 (3:1 aspect ratio). Should warn the banner is partially obscured by the avatar — center critical content and avoid important elements near the avatar overlap area. Should recommend keeping text minimal (seen at small sizes on mobile). Should suggest design tools (Canva or Figma) over AI generation since brand consistency matters. Should recommend Ideogram if heavy text rendering is needed since other AI models butcher text. Should suggest using brand colors + tagline + optional product shot. Should remind to test at actual display size by zooming out.", - "assertions": [ - "Specifies 1500x500 dimensions", - "Warns about avatar overlap area", - "Recommends minimal text", - "Suggests Canva or Figma over AI", - "Mentions Ideogram for text-heavy designs", - "Recommends testing at display size" - ], - "files": [] - }, - { - "id": 4, - "prompt": "I need 5 versions of the same hero image for Twitter, LinkedIn, Instagram feed, Instagram stories, and Facebook. What's the fastest way?", - "expected_output": "Should recommend the Canva Magic Resize workflow over generating 5 separate images. Should list dimensions: Twitter/X 1200x675 (16:9), LinkedIn 1200x627 (1.91:1), Instagram feed 1080x1080 (1:1 — note 1080x1350 / 4:5 also strong), Instagram Stories 1080x1920 (9:16), Facebook 1200x630 (1.91:1). Should explain workflow: create the hero concept at highest resolution needed, use Canva Magic Resize for variants, manually crop if needed, add text overlays programmatically if required (Ideogram or post-processing), export at each platform's specs. Should note this is what Canva Magic Resize is specifically designed for.", - "assertions": [ - "Recommends Canva Magic Resize", - "Lists dimensions for all 5 platforms", - "Notes Instagram 4:5 variant", - "Suggests programmatic text overlays for variants", - "Says start at highest resolution" - ], - "files": [] - }, - { - "id": 5, - "prompt": "What's the best image format for our website?", - "expected_output": "Should recommend WebP as the default choice with JPEG/PNG fallback. Should explain the format guide: WebP for photos and graphics (lossy + lossless, ~96% browser support), AVIF for highest compression (~94% support, newer), JPEG as universal fallback (lossy only), PNG for transparency and screenshots (lossless, universal), SVG for logos and icons (vector, scales, universal). Should reference the optimization checklist: resize to display size, compress (target quality 75-85% for photos), lazy load below-the-fold, set explicit width/height attributes (prevents CLS), use a CDN with auto-optimization (Cloudflare, Vercel, Imgix, Cloudinary), add descriptive alt text. Should provide a quick cwebp or mogrify command. Should note skipping image optimization is the #1 page speed killer.", - "assertions": [ - "Recommends WebP as default", - "Mentions JPEG/PNG fallback strategy", - "Lists optimization checklist items", - "Mentions lazy loading", - "Mentions explicit dimensions to prevent CLS", - "Provides command line tool example" - ], - "files": [] - }, - { - "id": 6, - "prompt": "We're a SaaS that just launched. Need OG images for every blog post we ship — about 2 per week. Doing it manually is killing us.", - "expected_output": "Should recommend Dynamic OG Images programmatic approach. Should explain options: Vercel OG (@vercel/og) generates images at the edge using JSX — best for programmatic SEO since you can dynamically pull post title, author, image into a template; Satori converts HTML/CSS to SVG (powers Vercel OG); Cloudinary for URL-based text overlay on template images. Should explain you build the template once with your branding then it generates unique OG images per page using post metadata. Should mention required meta tags: og:image (1200x630), og:image:width, og:image:height, twitter:card summary_large_image, twitter:image. Should note this is best for programmatic SEO.", - "assertions": [ - "Recommends programmatic OG image generation", - "Names Vercel OG, Satori, or Cloudinary", - "Mentions template + dynamic data approach", - "Lists required og:image meta tags", - "Specifies 1200x630 dimensions", - "Notes this is best for high-volume blogs" - ], - "files": [] - } - ] -} diff --git a/shared/skills/image/references/ai-image-generation.md b/shared/skills/image/references/ai-image-generation.md deleted file mode 100644 index ff35854..0000000 --- a/shared/skills/image/references/ai-image-generation.md +++ /dev/null @@ -1,60 +0,0 @@ -# AI Image Generation - -Generate original images from text prompts. The fastest way to create unique marketing visuals. - -## Model Comparison - -| Model | Best For | Text in Images | API | Cost | -|-------|----------|:-:|-----|------| -| **Gemini Image** (Google, "Nano Banana" / Nano Banana Pro) | All-around, editing, multi-image reference, text rendering | Good | [Gemini API](https://ai.google.dev/gemini-api/docs/image-generation) | Check [pricing](https://ai.google.dev/gemini-api/docs/pricing) | -| **Flux** (Black Forest Labs — Pro 1.1, Kontext, Dev, Schnell) | Photorealism, brand consistency, batch; Kontext for in-image editing | Limited | [BFL API](https://docs.bfl.ai/), Replicate, fal.ai | Check [pricing](https://docs.bfl.ai/quick_start/pricing) | -| **Ideogram 3.0** | Typography, branded graphics, accurate text rendering | Best | [Ideogram API](https://developer.ideogram.ai/) | Check [pricing](https://about.ideogram.ai/api-pricing) | -| **ChatGPT Images 2.0 / GPT Image** (OpenAI) | General purpose, ChatGPT integration, native editing | Good | [OpenAI API](https://platform.openai.com/docs/guides/image-generation) | Check [pricing](https://platform.openai.com/docs/pricing) | -| **Midjourney v7** | Artistic, high-aesthetic, art-directed visuals | Improved | No official API; Discord + Web | Subscription-based | -| **Recraft V3** | Vector + brand-consistent illustrations, design assets | Strong | [Recraft API](https://www.recraft.ai/docs) | Per-credit | -| **Stable Diffusion 3.5 / SDXL** | Self-hosted, customizable, fine-tunable | Varies | Open source | Free (GPU costs) | - -**Note:** DALL-E 3 is fully deprecated. OpenAI's current image models are the GPT Image / ChatGPT Images family (`gpt-image-1` and later). - -## When to Use Which - -``` -Need text/headlines in the image? -├── Yes → Ideogram 3.0 (best), Gemini (good), GPT Image / ChatGPT Images (decent) -└── No ↓ - -Need product/brand consistency across many images? -├── Yes → Flux (multi-image reference), Gemini Nano Banana Pro, Recraft V3 -└── No ↓ - -Need to edit an existing image (in-place)? -├── Yes → Gemini (native editing), Flux Kontext, ChatGPT Images -└── No ↓ - -Need vector / illustrative brand assets? -├── Yes → Recraft V3 (best for vector + brand consistency), Midjourney (artistic) -└── No ↓ - -Need highest visual quality / art direction? -├── Yes → Flux Pro 1.1, Midjourney v7 -└── No ↓ - -Need volume at low cost? -└── Flux Schnell, Gemini Flash, Stable Diffusion (self-hosted) -``` - -## Prompting Basics - -A strong image prompt follows: **Subject + Setting + Style + Lighting + Composition + Technical** - -``` -A laptop on a minimal white desk showing a dashboard UI, -soft directional lighting from the left, shallow depth of field, -clean commercial photography style, 16:9 aspect ratio, 4K -``` - -**Common mistakes:** -- Too vague ("a business image") — add specific details -- Forgetting aspect ratio — always specify dimensions -- Requesting complex text — use overlays instead for anything beyond short headlines -- No style direction — "photorealistic," "flat illustration," "3D render" diff --git a/shared/skills/image/references/ai-image-prompting.md b/shared/skills/image/references/ai-image-prompting.md deleted file mode 100644 index 3f6fa39..0000000 --- a/shared/skills/image/references/ai-image-prompting.md +++ /dev/null @@ -1,229 +0,0 @@ -# AI Image Prompting Guide - -How to write effective prompts for AI image generation models (Gemini/Nano Banana, Flux, Ideogram, DALL-E, Midjourney). - ---- - -## Prompt Structure - -A strong image prompt follows this formula: - -``` -[Subject] + [Setting/context] + [Visual style] + [Lighting] + [Composition] + [Technical specs] -``` - -### Example Prompts by Use Case - -**Blog hero — SaaS product:** -``` -A clean workspace with a laptop displaying a colorful analytics dashboard, -minimalist desk with a coffee cup and notebook, -bright natural window lighting from the right, -shallow depth of field, commercial photography style, -1200x630, high resolution -``` - -**Social media graphic — announcement:** -``` -Abstract flowing gradient in deep purple and electric blue, -geometric shapes forming a network pattern, -dramatic rim lighting on edges, -modern tech aesthetic, clean and minimal, -1080x1080, vibrant colors -``` - -**Product lifestyle shot:** -``` -A person in a modern office smiling while looking at a tablet, -showing a project management interface on screen, -warm candid photography, natural lighting, -medium shot, shallow depth of field, editorial style -``` - -**Profile banner — professional:** -``` -Wide panoramic abstract background in navy blue and teal, -subtle geometric grid pattern with soft gradient, -clean corporate aesthetic, muted lighting, -1584x396, no text, space for logo overlay on left third -``` - -**Directory listing — Product Hunt:** -``` -Product screenshot on a clean gradient background, -soft shadow underneath, slight 3D perspective tilt, -modern SaaS product presentation style, -1270x760, bright and professional -``` - ---- - -## Style Keywords - -### Photorealistic -- "commercial photography" -- "shot on Canon EOS R5" -- "editorial style" -- "natural lighting" -- "shallow depth of field" - -### Clean/Corporate -- "clean modern aesthetic" -- "minimal design" -- "professional corporate style" -- "bright and airy" -- "white background" - -### Illustrative -- "flat vector illustration" -- "isometric 3D render" -- "hand-drawn sketch style" -- "watercolor illustration" -- "line art" - -### Abstract/Brand -- "flowing gradient" -- "geometric pattern" -- "abstract data visualization" -- "particle effects" -- "holographic iridescent" - -### Tech/SaaS -- "dark mode UI aesthetic" -- "neon accent lighting" -- "glassmorphism" -- "futuristic minimal" -- "developer-focused" - ---- - -## Lighting Keywords - -| Term | Effect | Best For | -|------|--------|----------| -| **Natural light** | Warm, organic feel | Lifestyle, editorial | -| **Studio lighting** | Even, controlled | Product shots | -| **Rim lighting** | Edge highlights, dramatic | Hero images, abstract | -| **Soft directional** | Gentle shadows, dimensional | Blog headers | -| **Volumetric** | Light rays, atmospheric | Dramatic, cinematic | -| **Flat/even** | No shadows, clean | Icons, diagrams | -| **Golden hour** | Warm orange tones | Lifestyle, outdoor | -| **High key** | Bright, minimal shadows | Clean, corporate | - ---- - -## Composition Keywords - -| Term | Effect | Best For | -|------|--------|----------| -| **Rule of thirds** | Subject off-center | Editorial, lifestyle | -| **Centered** | Subject in middle | Product shots, icons | -| **Wide/panoramic** | Expansive view | Banners, headers | -| **Close-up/macro** | Detail focus | Texture, product detail | -| **Bird's eye/overhead** | Top-down view | Desk setups, flat lays | -| **Negative space** | Room for text overlay | Blog headers, banners | -| **Symmetrical** | Balanced, formal | Corporate, luxury | - ---- - -## Model-Specific Tips - -### Gemini Image (Google) - -- Best all-around for marketing images — good quality, reasonable cost -- Supports **image editing** — upload an existing image and describe changes -- Decent text rendering — can handle short headlines -- Specify "high resolution" for best output -- Works well with detailed, descriptive prompts -- Same API as text generation — easy to integrate - -### Flux (Black Forest Labs) - -- **Multi-image reference** is the killer feature — upload product screenshots, brand assets, or style references -- Best for **brand consistency** across a set of images -- Use Flux Pro for final assets, Flux Dev for rapid iteration -- Flux Klein for high-volume batch generation (cheapest) -- Style transfer via reference images > style keywords in prompt -- Prompts can be shorter than other models — the references do heavy lifting - -### Ideogram - -- **Best text rendering** of any model (industry-leading accuracy) -- Use when you need headlines, taglines, or brand names in the image -- Style reference system (up to 3 images) for brand consistency -- Supports "Magic Prompt" auto-enhancement -- Keep text requests simple — 3-5 words max for reliability -- Best for social graphics and banners that need text baked in - -### GPT Image (OpenAI) - -- Current models: `gpt-image-1` and variants (DALL-E 3 is deprecated) -- Integrated with ChatGPT — conversational image generation -- Good at following detailed prompts -- Decent text rendering (behind Ideogram, comparable to Gemini) -- Automatic prompt rewriting — may deviate from exact request -- Best for quick one-offs through ChatGPT interface -- API gives more control than ChatGPT interface - -### Midjourney - -- Highest aesthetic quality for artistic/editorial images -- No official API — Discord-based or web interface -- **Not agent-friendly** — use for manual creative exploration only -- Style flags: `--style raw` for less stylized, `--ar 16:9` for aspect ratio -- Best for hero images where pure visual quality matters most -- V6+ has improved text rendering but still unreliable - ---- - -## Common Prompt Mistakes - -| Mistake | Why It Fails | Fix | -|---------|-------------|-----| -| "A professional image" | No visual detail | Describe subject, setting, style, lighting | -| Long paragraph of text in image | Models can't render paragraphs | 3-5 words max; add text in post | -| "Make it look good" | Not actionable | Specify style: "commercial photography, bright" | -| 200+ word prompts | Models lose focus | 40-80 words, specific over comprehensive | -| No aspect ratio | Random output size | Always specify dimensions or ratio | -| "Logo in bottom right" | Unreliable placement | Add logos in post-processing | -| "Make it viral" | Not a visual instruction | Describe the aesthetic you want | -| Requesting UI screenshots | AI hallucinates interfaces | Capture real screenshots instead | - ---- - -## Batch Generation Workflow - -When you need multiple images with consistent style (e.g., a blog series or social campaign): - -1. **Generate 3-4 test images** with different style prompts -2. **Pick the winning style** based on brand fit -3. **Save the exact prompt** as your template -4. **Use Flux multi-reference** — upload the winning image as a style reference -5. **Batch generate** variations with the same style, different subjects -6. **Post-process** — add text overlays, logos, crop to platform sizes - ---- - -## Aspect Ratios Quick Reference - -| Use Case | Ratio | Pixels | Notes | -|----------|-------|--------|-------| -| Blog hero / OG image | 1.91:1 | 1200x630 | Universal web standard | -| Full-width hero | 16:9 | 1920x1080 | Website headers | -| Instagram Feed | 1:1 | 1080x1080 | Square | -| Instagram Feed (tall) | 4:5 | 1080x1350 | More screen real estate | -| Stories / Reels | 9:16 | 1080x1920 | Vertical full screen | -| LinkedIn cover | 4:1 | 1584x396 | Personal profile | -| Twitter/X header | 3:1 | 1500x500 | Profile banner | -| Product Hunt gallery | 5:3 | 1270x760 | Launch page | -| GitHub social preview | 2:1 | 1280x640 | Repo link card | - ---- - -## Cost Optimization - -- **Iterate at low quality first** — use Flux Dev or Gemini Flash for drafts, upgrade for finals -- **Use references over long prompts** — Flux multi-reference produces more consistent results with fewer retries -- **Batch similar requests** — generate all blog headers in one session with the same style -- **Cache and reuse** — abstract backgrounds, patterns, and textures can be reused across multiple images -- **Post-process instead of re-generate** — crop, overlay text, and adjust color in code rather than generating new images diff --git a/shared/skills/image/references/common-mistakes.md b/shared/skills/image/references/common-mistakes.md index 06efe20..51bdb2e 100644 --- a/shared/skills/image/references/common-mistakes.md +++ b/shared/skills/image/references/common-mistakes.md @@ -1,10 +1,12 @@ # Common Mistakes -1. **Using AI for product UI screenshots** — models hallucinate interfaces; capture real screenshots -2. **Skipping image optimization** — unoptimized images are the #1 page speed killer -3. **No OG image** — shared links look broken without a preview image -4. **Wrong aspect ratio** — always check platform specs before generating -5. **Text-heavy images without Ideogram** — most AI models butcher text; use Ideogram or add text in post -6. **Generating without style direction** — "photorealistic," "flat illustration," "3D render" drastically changes output -7. **Inconsistent brand visuals** — use Flux multi-reference or design templates for consistency -8. **Huge images on landing pages** — compress, resize, lazy load +Check only issues relevant to the change: + +- Oversized downloads or incorrect responsive candidates: inspect the resource actually selected at each target viewport. +- Lazy-loaded LCP image, excessive high-priority images, or late discovery: inspect the loading waterfall. +- Missing dimensions or wrong aspect ratio: check layout shifts and cropping. +- Blurry screenshot text, compression artifacts, or lost transparency: compare at final display size. +- Missing or keyword-stuffed alternative text; essential information available only inside an image: check accessibility. +- Broken, authenticated, blocked, or expired preview URLs; duplicate metadata or stale cached previews: inspect responses and the target preview. +- Sensitive data in screenshots, untrusted SVG markup, or overwritten originals: use sanitized inputs and preserve editable sources. +- Stale platform dimensions, unreadable banner text, or stretched variants: verify current requirements and inspect each export. diff --git a/shared/skills/image/references/design-tools.md b/shared/skills/image/references/design-tools.md index 3eef9b5..fd0cd69 100644 --- a/shared/skills/image/references/design-tools.md +++ b/shared/skills/image/references/design-tools.md @@ -1,32 +1,13 @@ # Design Tools -For templated, brand-consistent work where AI generation is overkill or too unpredictable. +Prefer the team's existing tools and editable assets. Choose by task rather than introducing a new subscription or integration. -## Canva +| Task | Practical route | +| --- | --- | +| Product UI or documentation screenshot | Browser screenshot tooling or the existing capture tool; show the real UI. | +| Asset tied to a design system | Existing Figma components and export workflow; use the applicable Figma skill when interacting with Figma. | +| Repeated banners or social graphics | Existing Canva or Figma template; verify current export and resize capabilities before relying on them. | +| Dynamic link-preview images | Existing framework or build-time template renderer. | +| Resize, crop, or compression | Installed image pipeline or utility; preserve source files. | -Best for non-designers who need polished output fast. - -- **Strengths:** Massive template library, brand kit, Magic Resize (one design → all sizes), team collaboration -- **Best for:** Social graphics, presentations, email headers, simple banners -- **Limitations:** Less control than Figma, templates can look generic -- **Agent-friendliness:** Has an API but limited — better as a human-in-the-loop tool - -## Figma - -Best for teams with design systems or pixel-perfect needs. - -- **Strengths:** Design system components, auto layout, developer handoff, plugins -- **Best for:** OG images via templates, design system assets, complex layouts -- **Limitations:** Steeper learning curve, requires design skill -- **Agent-friendliness:** Has an API and MCP server for reading designs - -## When to Use Design Tools vs. AI Generation - -| Scenario | Design Tool | AI Generation | -|----------|:-:|:-:| -| Exact brand guidelines must be followed | Yes | Maybe (with strong ref images) | -| Need 20 size variants of one design | Yes (Canva Magic Resize) | No | -| Unique hero image for a blog post | No | Yes | -| Recurring social media template | Yes | No | -| Product mockup with real UI | No (use screenshots) | No (hallucinated UI) | -| Abstract/creative visual | No | Yes | +Keep editable originals, export only needed variants, and inspect font rendering, transparency, cropping, and file size. Use `technical-research` before depending on a tool API or version-specific feature. diff --git a/shared/skills/image/references/image-optimization.md b/shared/skills/image/references/image-optimization.md index 2e48d5b..9d79367 100644 --- a/shared/skills/image/references/image-optimization.md +++ b/shared/skills/image/references/image-optimization.md @@ -1,39 +1,11 @@ -# Image Optimization +# Image Optimization and SEO -Every image on your site affects page speed, which affects SEO and conversions. +- Start with measured transfer size, rendered dimensions, and the page's LCP element. Keep originals; compare optimized output at its actual display size. +- Use SVG for suitable vector assets, lossless formats for sharp UI text, and compare WebP/AVIF with existing raster formats for photographs. Choose against target-client support, transparency, quality, and measured size; avoid fixed quality or byte targets for every asset. +- Match `srcset` and `sizes` to the layout, or use the framework's existing image component. Set intrinsic `width` and `height` to reserve the correct aspect ratio. +- Lazy-load offscreen images. Keep the LCP image discoverable in initial HTML and eagerly loaded; consider `fetchpriority="high"` for that image, not every image. +- Use descriptive filenames, relevant surrounding text, and useful `alt` text without keyword stuffing. Decorative images need empty alternative text. +- For images intended for search, verify crawlable image URLs and standard image markup with a usable `src`. CSS backgrounds are not a substitute for indexable content images. +- Reuse existing transformation and caching infrastructure. Measure transferred bytes, rendering quality, LCP, and layout shifts after the change; distinguish lab results from real-user data. -## Format Guide - -| Format | Best For | Compression | Browser Support | -|--------|----------|-------------|:---:| -| **WebP** | Photos, graphics — default choice | Lossy + lossless | ~96% | -| **AVIF** | Highest compression, newest | Better than WebP | ~94% | -| **JPEG** | Fallback for older browsers | Lossy only | Universal | -| **PNG** | Transparency, screenshots | Lossless | Universal | -| **SVG** | Logos, icons, illustrations | Vector (scales) | Universal | - -## Optimization Checklist - -- [ ] **Serve WebP** with JPEG/PNG fallback (`` element or CDN auto-format) -- [ ] **Resize to display size** — don't serve 4000px images in 800px containers -- [ ] **Compress** — target quality 75-85% for photos, near-lossless for screenshots -- [ ] **Lazy load** below-the-fold images (`loading="lazy"`) -- [ ] **Set explicit dimensions** — `width` and `height` attributes prevent layout shift (CLS) -- [ ] **Use a CDN** with auto-optimization (Cloudflare, Vercel, Imgix, Cloudinary) -- [ ] **Add alt text** — descriptive, keyword-relevant, not stuffed - -## Quick Optimization Commands - -```bash -# Convert to WebP (using cwebp) -cwebp -q 80 input.png -o output.webp - -# Batch convert with ImageMagick -mogrify -format webp -quality 80 *.png - -# Optimize JPEG (using jpegoptim) -jpegoptim --max=80 --strip-all *.jpg - -# Check image sizes on a page -curl -s https://yoursite.com | grep -oP 'src="[^"]+\.(jpg|png|webp)"' | head -20 -``` +References: [HTML images](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img), [LCP optimization](https://web.dev/articles/optimize-lcp), [Google image SEO](https://developers.google.com/search/docs/appearance/google-images). diff --git a/shared/skills/image/references/marketing-image-workflows.md b/shared/skills/image/references/marketing-image-workflows.md index cd96237..1faabb4 100644 --- a/shared/skills/image/references/marketing-image-workflows.md +++ b/shared/skills/image/references/marketing-image-workflows.md @@ -1,87 +1,17 @@ # Marketing Image Workflows -## Blog & Article Hero Images +## Article Heroes and Landing Pages -The image at the top of every post. Sets tone, improves shareability, required for OG/social previews. +Choose an existing, appropriately licensed visual or real product screenshot that supports the page's message. Compose around the actual layout, keep essential text in HTML, and export responsive variants. Apply [image optimization](image-optimization.md); an above-the-fold hero must not inherit blanket lazy loading. -1. **Define the concept** — what visual metaphor represents the topic? -2. **Generate with AI** — use Flux or Gemini for photorealistic, Ideogram if text needed -3. **Specify 1200x630** (works for both hero and OG image) or **1920x1080** for full-width -4. **Optimize** — compress to <200KB, serve as WebP with JPEG fallback +## Product Screenshots and Mockups -**Prompt pattern:** -``` -[Visual metaphor for topic], clean modern style, -bright natural lighting, shallow depth of field, -professional blog header aesthetic, 1200x630 -``` +Capture the real application with representative, non-sensitive data. Use sufficient resolution for the final pixel density, crop irrelevant chrome, and add only useful annotations. Device frames are optional. Check small-screen readability and preserve an unannotated original. -## Social Media Graphics +## Social Graphics, Banners, and Listings -Platform-specific images for organic posts. +Reuse brand assets and one editable template. Verify the target platform's current dimensions and crop/overlay safe areas before export. Produce only requested variants; inspect each crop rather than stretching a single image to every ratio. -| Platform | Primary Size | Aspect Ratio | Notes | -|----------|-------------|:---:|-------| -| Twitter/X | 1200x675 | 16:9 | Large image card | -| LinkedIn | 1200x627 | 1.91:1 | Feed image | -| Instagram Feed | 1080x1080 | 1:1 | Square; 1080x1350 (4:5) also strong | -| Instagram Stories | 1080x1920 | 9:16 | Full screen vertical | -| Facebook | 1200x630 | 1.91:1 | Link share image | +## Repeated Publishing -**Workflow:** -1. Create the hero concept at highest resolution needed -2. Use Canva Magic Resize or manual crop for platform variants -3. Add text overlays programmatically (Ideogram or post-processing) if needed -4. Export at platform-specific dimensions - -## Product Mockups & Screenshots - -Showcase your product UI in context. AI models hallucinate UI — don't use them for this. - -1. **Capture real screenshots** of your product at 2x resolution -2. **Frame in device mockups** — use browser frame, laptop, or phone templates -3. **Add context** — callout arrows, feature labels, before/after comparisons -4. **Annotate with code** — Hyperframes or HTML/CSS for programmatic overlays - -**Tools:** Browser DevTools (screenshot), Shottr (Mac), CleanShot X, or `screencapture` CLI. - -## Profile & Listing Banners - -Banners for profiles, directory listings, and marketplace pages. Often the first visual impression. - -| Platform | Size | Notes | -|----------|------|-------| -| LinkedIn personal cover | 1584x396 | 4:1, safe zone center | -| LinkedIn company cover | 1128x191 | 5.9:1; LinkedIn recommends up to 4200x700 | -| Twitter/X header | 1500x500 | 3:1, partially obscured by avatar | -| Product Hunt gallery | 1270x760 | 5:3, up to 6 images | -| G2 profile | 1280x720 | 16:9, product screenshots preferred | -| GitHub social preview | 1280x640 | 2:1, shows in link cards | -| App Store screenshots | Varies by device | Check current platform specifications | -| Google Play feature graphic | 1024x500 | ~2:1, required for store listing | - -**Best practices:** -- **Keep text minimal** — banners are seen at small sizes on mobile -- **Center critical content** — edges get cropped differently per device -- **Show the product** — real UI screenshots outperform abstract graphics on directory listings -- **Match your brand** — use consistent colors, fonts, logo placement -- **Update seasonally** — stale banners signal an inactive product - -**Workflow:** -1. Pick the platform(s) and note exact dimensions -2. For directories (Product Hunt, G2): use real product screenshots with light annotation -3. For profiles (LinkedIn, Twitter): use brand colors + tagline + optional product shot -4. Generate with Canva/Figma templates or Ideogram (if text-heavy) -5. Test at actual display size — zoom out to check readability - -## Brand Assets - -Logos, icons, and illustrations. AI generation has limits here. - -| Asset | AI Generation | Design Tool | Notes | -|-------|:-:|:-:|-------| -| Logo | Poor — inconsistent, not vector | Yes (Figma) | Always design or commission logos | -| App icon | Decent starting point | Yes (Figma) | Generate concepts, refine manually | -| Illustrations | Good for style exploration | Depends | AI for concepts, finalize in design tool | -| Favicons | No | Yes | Derive from logo | -| Social icons | No | Yes | Use platform-provided assets | +Keep titles, product shots, and layout separate so an existing template or build pipeline can produce variants consistently. Connect link-preview exports to [OG metadata](og-social-preview-images.md). Automate only repeated work, and validate fonts, long titles, missing images, and output caching. diff --git a/shared/skills/image/references/og-social-preview-images.md b/shared/skills/image/references/og-social-preview-images.md index d01282c..4503387 100644 --- a/shared/skills/image/references/og-social-preview-images.md +++ b/shared/skills/image/references/og-social-preview-images.md @@ -1,23 +1,26 @@ -# OG & Social Preview Images - -The image that appears when your URL is shared on social media, Slack, Discord, etc. +# OG and Social Preview Images ## Required Meta Tags +Open Graph requires `og:title`, `og:type`, `og:url`, and `og:image`. Image dimensions and alternative text supplement those fields. Set the page type appropriately and keep the canonical page URL consistent. + ```html - + + + + - - + ``` -## Dynamic OG Images +Dimensions above describe the example asset, not a universal platform requirement. Verify current format, crop, and size requirements for the intended consumer. Add platform-specific card metadata through the existing framework integration when needed; confirm its current contract with `technical-research`. -Generate OG images programmatically for pages with dynamic content (blog posts, user profiles): +## Delivery and Validation -- **Vercel OG** (`@vercel/og`) — generates images at the edge using JSX -- **Satori** — converts HTML/CSS to SVG (powers Vercel OG) -- **Cloudinary** — URL-based text overlay on template images +- Put metadata in the delivered document head using the existing metadata API; avoid duplicate or conflicting tags. +- Use stable absolute HTTPS image URLs. Public previews must load without authentication and return the correct image content type. Keep private assets private. +- For recurring pages, reuse a template populated with page metadata. Prefer existing build-time generation or cache generated outputs; avoid adding a rendering service for a few static images. +- Check the actual response, metadata, crop, text readability, and target preview tool. Allow for consumer caching when validating updates. Social-preview metadata does not itself guarantee search ranking improvements. -**Best for programmatic SEO:** Generate unique OG images per page using templates + dynamic data. +Source: [Open Graph protocol](https://ogp.me/).