\n\nQuick Guide: Use the
\nreplicatenpm package to run open-source ML models on serverless GPUs. Usereplicate.run()for synchronous execution that returns output directly,replicate.stream()for SSE-based streaming, orreplicate.predictions.create()for async background jobs with webhook notifications. Models are referenced asowner/model(uses latest version) orowner/model:version(pinned). File outputs areFileOutputobjects implementingReadableStream. Cold starts are expected for infrequently-used models -- use deployments withmin_instancesto keep models warm.
<critical_requirements>
\n\n\nAll code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,
\nimport type, named constants)
(You MUST never hardcode API tokens -- always use environment variables via process.env.REPLICATE_API_TOKEN)
(You MUST handle FileOutput objects for models that return files -- do not assume outputs are plain strings or URLs)
(You MUST validate webhooks using validateWebhook() from the replicate package -- never trust unverified webhook payloads)
(You MUST account for cold starts when running infrequently-used models -- use deployments for latency-sensitive applications)
\n(You MUST specify model versions (owner/model:version) in production to ensure reproducible results -- unversioned references use the latest, which can change)
</critical_requirements>
\nAuto-detection: Replicate, replicate, replicate.run, replicate.stream, replicate.predictions, replicate.deployments, replicate.trainings, replicate.models, FileOutput, validateWebhook, REPLICATE_API_TOKEN, serverless GPU, cold start, webhook_events_filter
\nWhen to use:
\nKey patterns covered:
\nreplicate.run(), replicate.predictions.create(), replicate.wait())replicate.stream() with SSE events)owner/model vs owner/model:version)FileOutput, file uploads, Buffer inputs)When NOT to use:
\n<decision_framework>
\nIs this a user-facing LLM response?\n+-- YES -> Use replicate.stream() for real-time SSE output\n+-- NO -> Do you need the result immediately?\n +-- YES -> Use replicate.run() (blocks until complete)\n +-- NO -> Use replicate.predictions.create() + webhook\n +-- Need to poll instead? -> Use replicate.wait(prediction)\nAre you in development/prototyping?\n+-- YES -> Use owner/model (latest version, convenient)\n+-- NO -> Are you in production?\n +-- YES -> Use owner/model:version_hash (pinned, reproducible)\n +-- Does the model change frequently?\n +-- YES -> Pin version, test updates explicitly\n +-- NO -> Either format works, prefer pinned\nDo you need consistent low latency?\n+-- YES -> Create a deployment with min_instances >= 1\n+-- NO -> Do you need custom hardware (A100, H100)?\n +-- YES -> Create a deployment with specific hardware\n +-- NO -> Use replicate.run() / replicate.stream() directly\n (Replicate auto-allocates hardware)\nAre you running open-source models on serverless GPUs?\n+-- YES -> Use Replicate SDK\n+-- NO -> Are you calling proprietary APIs (OpenAI, Anthropic)?\n +-- YES -> Not this skill's scope -- use provider-specific SDKs\n +-- NO -> Do you need to switch between multiple providers?\n +-- YES -> Not this skill's scope -- use a unified provider SDK\n +-- NO -> Do you want to self-host models?\n +-- YES -> Not this skill's scope -- consider Cog or vLLM\n +-- NO -> Replicate SDK is appropriate\n</decision_framework>
\n<red_flags>
\nHigh Priority Issues:
\nREPLICATE_API_TOKEN in source code (security breach risk)FileOutput as a string (it is a ReadableStream object -- use .url() or .blob())validateWebhook() (allows forged webhook payloads)replicate.run() for long-running models in request handlers (blocks the response, can timeout)Medium Priority Issues:
\nowner/model uses latest, which can change without notice)Buffer instead of hosting them at a URL (100 MiB limit on uploads)Common Mistakes:
\nreplicate.run() (returns output directly) with replicate.predictions.create() (returns a prediction object with status/id)const output = await replicate.run(...) instead of const [output] = await replicate.run(...) (image models return arrays)replicate.stream() with models that do not support streaming (only language models with SSE support)replicate.predictions.create() accepts either a version hash or a model string (owner/model) -- use version for pinned reproducibility, model for latest-version conveniencereplicate.stream() (events are lost)Gotchas & Edge Cases:
\nreplicate.stream() returns ServerSentEvent objects with .event (\"output\", \"error\", \"done\") and .data (string) propertieswebhook_events_filter accepts [\"start\", \"output\", \"logs\", \"completed\"] -- use [\"completed\"] unless you need intermediate status updatesPrefer: wait header enables sync mode on the HTTP API (up to 60s), but replicate.run() already handles this automaticallyreplicate.wait() polls the API until the prediction completes -- use webhooks for production to avoid polling overheadFileOutput.url() returns the underlying URL, but these URLs are temporary -- download or persist the file before it expires</red_flags>
\n<critical_reminders>
\n\n\nAll code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,
\nimport type, named constants)
(You MUST never hardcode API tokens -- always use environment variables via process.env.REPLICATE_API_TOKEN)
(You MUST handle FileOutput objects for models that return files -- do not assume outputs are plain strings or URLs)
(You MUST validate webhooks using validateWebhook() from the replicate package -- never trust unverified webhook payloads)
(You MUST account for cold starts when running infrequently-used models -- use deployments for latency-sensitive applications)
\n(You MUST specify model versions (owner/model:version) in production to ensure reproducible results -- unversioned references use the latest, which can change)
Failure to follow these rules will produce insecure, unreliable, or unpredictable AI integrations.
\n</critical_reminders>
\n","files":[{"path":"examples/core.md","sizeBytes":8376,"isText":true},{"path":"examples/deployments-training.md","sizeBytes":6623,"isText":true},{"path":"examples/streaming-webhooks.md","sizeBytes":7327,"isText":true},{"path":"reference.md","sizeBytes":9298,"isText":true},{"path":"SKILL.md","sizeBytes":20105,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-29T15:27:58.616497Z","sha256":"1749A3A09C401BACF78A181EB8EC27B5B32F04E9CAFACE71745197189A5DBD4A","sizeBytes":17907},"review":null,"source":{"repositoryUrl":"https://github.com/agents-inc/skills","path":"dist/plugins/ai-infrastructure-replicate/skills/ai-infrastructure-replicate","license":"MIT","commit":"3a51ef571e996b18294bf776d53dbdad26de0617","subtreeSha":"C125F194CBCB268EA6638D474ED839C2C9E531263F737FC69C6CAE33EB57A710","lastSyncedAt":"2026-09-29T15:27:48.914434Z"},"reviewedAt":"2026-09-29T15:28:47.086282Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/ai-infrastructure-replicate/skills/ai-infrastructure-replicate"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart"},{"target":"git","command":"git clone https://github.com/agents-inc/skills.git"}]}