| name | replicate-imagery |
| description | Route AI image generation and editing requests to Replicate (FLUX, Ideogram, Recraft, SDXL, imagen) via the bundled `replicate` MCP server. Use when a document, book, or report needs an illustration, hero image, character/concept art, photorealistic scene, or style-transferred image that neither Flint (data charts), Mermaid (technical diagrams), nor svg-banner (brand banners) can produce. Composes with Replicate's upstream agent skills (prompt-images, find-models, run-models, compare-models, prompt-videos) installable via `npx skills add replicate/skills`. Requires `REPLICATE_API_TOKEN`. |
| lastReviewed | 2026-08-10T00:00:00.000Z |
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:
| Artifact | Not this skill — use instead |
|---|
| Data chart (bar, line, scatter, distribution, KPI) | flint-chart |
| Technical / architectural / flow diagram | markdown-mermaid (Alex_ACT_Steward baseline) |
| Brand banner (hero header for a doc) | svg-banner (Alex_ACT_Steward baseline) |
| Deterministic hand-authored figure (dataset-backed) | figure-generator |
| Print-quality book figure with typography grammar | print-svg-style-guide |
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
-
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')
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.
-
The replicate MCP server — run setup-illustrator-runtime 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.
-
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 .
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 with the Alex ACT constellation, weave color hex codes from the constellation's 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: use that project's own brand-palette.json (heirs override — see this plugin's README Brand palette section for the swatch and configuration key mapping).
Best model choices for brand-consistent output:
recraft-ai/recraft-v3 — strongest color-guidance adherence, vector-friendlyideogram-ai/ideogram-v3 — respects color hints, best if the image includes readable textblack-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>):
| Model | Approx. cost per image |
|---|
black-forest-labs/flux-schnell | ~$0.003 |
black-forest-labs/flux-dev | ~$0.025 |
black-forest-labs/flux-1.1-pro | ~$0.04 |
ideogram-ai/ideogram-v3 | ~$0.09 |
recraft-ai/recraft-v3 | ~$0.04 |
| Video models | ~$0.10-$5.00 per second |
Fabio's Karpathy_Loop testing (2026-07-27 user memory) spent ~$1.83 across an iteration session with multiple stock media generations. 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-illustrator-runtime 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)
