Imported from fabioc-aloha/Alex_ACT_ONE (skills/replicate-imagery/SKILL.md). Install upstream with npx skills add fabioc-aloha/Alex_ACT_ONE --skill replicate-imagery. Copyright stays with the author.

Replicate Imagery

Thin routing + brand-alignment skill for AI image generation and editing on Replicate. Delegates substantive prompting guidance to Replicate's upstream prompt-images skill and model discovery to the replicate MCP server. This skill is the plugin's entry point that says WHEN to reach for Replicate and HOW it composes with the plugin's other visual capabilities.

When to use this skill

You want to add a visual artifact to a doc / book / report and none of these fit:

Fires when the goal is one of:

• Illustrations — decorative or narrative images for chapters, sections, blog posts
• Hero images — top-of-page visuals for docs shared externally
• Character / concept art — figures for creative writing, book covers, brand mascots
• Photorealistic scenes — mockups, product-in-context imagery, scene composition
• Style-transferred images — restyling existing images to match a brand aesthetic
• Image editing — inpaint, background removal, upscaling, prompt-driven edits

Prerequisites

1. REPLICATE_API_TOKEN environment variable — get one at replicate.com/account/api-tokens. Set in your shell env so the MCP server picks it up:

   # PowerShell (per-session)
   $env:REPLICATE_API_TOKEN = 'r8_...'
   
   # PowerShell (persistent, user scope)
   [System.Environment]::SetEnvironmentVariable('REPLICATE_API_TOKEN', 'r8_...', 'User')

   # bash / zsh
   export REPLICATE_API_TOKEN=r8_...

   Do NOT commit the token to any config file. The plugin's shipped .vscode/mcp.json references it via ${env:REPLICATE_API_TOKEN} so it stays out of source control.

2. The replicate MCP server — run setup-dependencies once after installing or updating the plugin. It installs the reviewed replicate-mcp@0.9.0 pin through npm's configured registry; the bundled Node launcher starts it on the first Replicate tool invocation. Use setup's --check-updates mode to compare the pin with the stable dist-tag before a release.

3. Upstream Replicate skills (recommended, one-shot) — install once per project:

   npx skills add replicate/skills

   Pulls in five agent skills authored by Replicate covering the substantive prompting knowledge this thin skill delegates to:

   Upstream skill	What it covers
   find-models	Searching models, browsing collections, reading schemas, picking the right model
   compare-models	Evaluating by cost, speed, quality, capabilities
   run-models	Creating predictions, polling, webhooks, streaming, file handling, multi-model workflows
   prompt-images	Prompting techniques: photographic language, text rendering, style transfer, character consistency, inpainting
   prompt-videos	Prompting techniques for video: scene, camera motion, audio/dialogue, time-coded multi-shot, style control

   Update with npx skills update. Remove with npx skills remove replicate.

Model selection

Replicate hosts thousands of models. Working set for illustration as of 2026-07:

Discover current models via the MCP tool: ask the agent "search Replicate for <capability> models" — the replicate MCP calls models.search under the hood and returns current results with cost, hardware, and capability metadata. Per-model page at replicate.com/<owner>/<model> shows pricing and interactive playground.

Model list evolves fast. If a recommendation here is stale, the upstream find-models skill has current model-discovery guidance and the MCP does live discovery.

Brand alignment

For illustrations that should feel on-brand, weave color hex codes from your project's .github/config/brand-palette.json into the prompt. Example:

"A minimalist illustration of a person coding at a desk, dominant color emerald #10b981 with deep slate #0f172a accents, cyan #06b6d4 highlight on the monitor, clean vector style, no text."

Per-project brands: each project overrides the palette in its own .github/config/brand-palette.json.

Best model choices for brand-consistent output:

• recraft-ai/recraft-v3 — strongest color-guidance adherence, vector-friendly
• ideogram-ai/ideogram-v3 — respects color hints, best if the image includes readable text
• black-forest-labs/flux-* — interprets colors well but with less strict adherence

Output handling

• Default output location: assets/generated/<slug>-<timestamp>.png
• Consider adding assets/generated/ to .gitignore — ML-generated images are large and often iterative
• Keep curated finals in assets/ (not assets/generated/)
• For book / report embedding, downscale to target print DPI before committing to keep the git tree light

Cost awareness

Replicate charges per prediction. Approximate costs for image generation as of 2026-07 (verify current at replicate.com/<model>):

A measured iteration session with multiple stock media generations cost roughly $1.83. Individual illustrations are cheap; volume adds up.

Set a spending cap at replicate.com/account/billing if runaway costs are a concern.

Composition with plugin skills

• Big Idea gate first: run chart-big-idea Step 0.5 (earn-a-figure gate) before generating. Skips wasted API calls for figures that shouldn't exist.
• Verify after: run render-verify to check the generated image actually communicates what you asked for. AI-generated images fail Prose-coupling surprisingly often (prose says X, image shows Y).
• Iterate cheap, publish expensive: FLUX-schnell for iteration, FLUX-1.1-pro or Ideogram for the final.
• Style-lock for a series: for a book or multi-chapter report, lock model + seed + palette hints across figures so the visual family reads as one voice. Ideogram and Recraft handle this best.

Boundaries

• Does not itself run predictions — dispatches to the replicate MCP server which invokes the Replicate HTTP API. Requires setup-dependencies to have installed the reviewed runtime; verify with the plugin install verifier.
• Does not manage the API token — user brings their own via REPLICATE_API_TOKEN env var. If the var is unset, the MCP server fails on first invocation, not at config load.
• Does not cache or dedupe predictions — same prompt run twice = two paid predictions. Save outputs you want to keep.
• Does not select the model automatically — the agent chooses based on the prompt + this skill's recommendations. Model choice matters for both cost and quality.
• Does not do TTS, music, code generation, or LLM inference on Replicate — those are separate categories the plugin does not currently route to.

Falsifiability

Revisit by 2026-10-30 (90 days) or sooner if:

• The recommended model list is stale (≥3 models retired or superseded by newer versions)
• The upstream replicate/skills bundle changes structure such that the composition callouts here point at moved content
• Heirs consistently reach for this skill for artifact types the routing table above says NOT to use (indicates the boundary is unclear)
• Cost estimates in the table are off by >2x versus real Replicate pricing at 2026-10 recheck
• The replicate-mcp npm package moves, renames, or changes invocation shape
• Zero heir uses the skill in the observation window (parking-lot candidate — the plugin scope was wrong to activate)