image-workflows

name

image-workflows

description

Create and execute image workflows using floimg. Use when the user needs to generate AI images, transform existing images (resize, caption, filters), or create multi-step pipelines. Also handles charts, diagrams, QR codes, and screenshots. Trigger words: image, picture, photo, illustration, hero, thumbnail, resize, transform, caption, watermark, generate, AI, DALL-E, chart, diagram, QR, screenshot.

Image Workflows Skill

This skill enables you to create and execute image workflows using floimg—the composable workflow engine with two core differentiators:

1. Deterministic Transforms: AI image modification is probabilistic—DALL-E generates new images, inpainting runs diffusion. FloImg applies deterministic transforms: adjust hue mathematically, resize to exact dimensions. The image stays intact except for exactly what you requested.

2. A Unified API: FloImg models image manipulation as a series of composable steps. This functional approach consolidates the patchwork of tools and SDKs into one abstraction layer—portable across SDK, CLI, visual builder, and MCP.

Architecture: CLI Simple, MCP Complex

floimg uses a hybrid approach:

Task Type	Method	Works Immediately?
Complex (AI images, multi-step, iteration)	MCP	After restart
Simple (QR, chart, diagram, screenshot)	CLI via npx	Yes

When to Use This Skill

Activate this skill when the user:

• Wants to generate AI images (DALL-E, etc.) with professional finishing
• Needs to transform images (resize, add caption, adjust colors, apply filters)
• Wants iterative refinement ("make it more vibrant", "add a caption")
• Wants to save images to cloud storage (S3, R2, Tigris)
• Describes a multi-step image workflow (generate → transform → save)
• Also: charts, diagrams, QR codes, screenshots

Simple Tasks (Use CLI)

For one-shot operations, use the floimg CLI:

# Resize an image
npx -y @teamflojo/floimg resize hero.png 1200x630 -o ./og-image.png

# Convert format
npx -y @teamflojo/floimg convert image.png -o image.webp

# Add caption
npx -y @teamflojo/floimg caption image.png "© 2025 Acme" -o ./watermarked.png

# AI image (requires OPENAI_API_KEY)
npx -y @teamflojo/floimg generate --generator openai --prompt "..." -o ./image.png

# Also: charts, diagrams, QR, screenshots
npx -y @teamflojo/floimg qr "https://example.com" -o ./qr.png
npx -y @teamflojo/floimg chart bar --labels "Q1,Q2,Q3" --values "10,20,30" -o ./chart.png

These work immediately with no configuration.

Complex Tasks (Use MCP)

For multi-step workflows, iteration, and transforms, use MCP tools:

Available MCP Tools

• generate_image - Generate with intent-based routing
• transform_image - Apply transforms to existing images
• save_image - Save to filesystem or cloud
• run_pipeline - Execute multi-step workflows
• analyze_image - AI vision analysis

If MCP is not available

For complex workflows, inform the user: "Multi-step image workflows work best with MCP. Restart Claude Code once to enable the floimg MCP server for session state and iteration."

Why Session State Matters

This is FloImg's core advantage over raw LLM + DALL-E:

Task	Without FloImg	With FloImg MCP
"Create a hero image"	Generates image	Generates + stores as img_001
"Make it 1200x630"	Re-generates entirely (different image!)	Resizes exact pixels
"Make it bluer"	Start over	Adjusts hue on existing image

The key insight: When you say "make it more vibrant," FloImg adjusts the existing image—it doesn't re-generate a new one. AI handles creation. FloImg handles precision.

Generator Selection Guide

User Intent	Generator	Method
Photo/illustration/hero/scene	openai	MCP generate_image or CLI
Product mockup, creative	openai	MCP for iteration
Bar/line/pie chart	quickchart	CLI chart TYPE
Flowchart/sequence/diagram	mermaid	CLI diagram "CODE"
QR code/barcode	qr	CLI qr "TEXT"
Webpage screenshot	screenshot	CLI screenshot "URL"

Workflow Patterns

Pattern 1: AI Image with Transforms (MCP preferred)

User: "Create a hero image for my blog, resize to 1200x630, add my tagline"

1. generate_image({ intent: "hero image for tech blog about AI" }) → imageId
2. transform_image({ imageId, operation: "resize", params: { width: 1200, height: 630 } })
3. transform_image({ imageId, operation: "addCaption", params: { text: "AI for Everyone" } })
4. save_image({ imageId, destination: "./hero.png" })

Pattern 2: Iterative Refinement (MCP required)

User: "Create a hero image for my blog"
→ generate_image(...) → imageId: "img_001"

User: "Make it more vibrant"
→ transform_image({ imageId: "img_001", operation: "modulate", params: { saturation: 1.3 } })

User: "Add a caption"
→ transform_image({ imageId: "img_002", operation: "addCaption", params: { text: "..." } })

Session state is crucial here: Each transform references the previous result by imageId. No file uploads, no re-generation—just precise refinements.

Pattern 3: Full Pipeline (MCP)

User: "Create a hero image, resize for social, add caption, upload to S3"

run_pipeline({
  steps: [
    { generate: { intent: "hero image..." } },
    { transform: { operation: "resize", params: { width: 1200, height: 630 } } },
    { transform: { operation: "addCaption", params: { text: "...", position: "bottom" } } },
    { save: { destination: "s3://bucket/hero.png" } }
  ]
})

Best Practices

1. AI workflows → MCP: Generate + transform + iterate benefits from session state
2. Simple generators → CLI: /floimg:qr, /floimg:chart for one-shot output
3. Use imageId for chaining: Reference previous images without file juggling
4. Resize last: Apply quality-degrading transforms before final resize
5. Choose right format: PNG for photos, WebP for web, SVG for diagrams

For detailed API reference, see reference.md. For common workflow examples, see examples.md.