replicate/skills: The Repo That Replaces the SDK With Instructions

A tiny skill file, an MCP bridge, and live schema checks turn AI agents into self-updating Replicate users.

8 min read • View on GitHub • More from replicate

A lone agent sits at a workbench surrounded by many closed drawers labeled like model families. A slim instruction card is tied to a live API endpoint, showing that the useful knowledge lives in the skill, not in a pile of wrappers. — Replicate turns integration from static client code into a portable skill that can steer an agent at runtime.

Key Takeaways

replicate/skills treats instructions as the integration layer, so the agent learns how to use Replicate instead of relying on a fixed wrapper.
The skill pushes model discovery, schema fetching, and input validation into runtime, which keeps the caller aligned with changing APIs.
Replicate is not trying to replace SDKs everywhere. It is carving out a separate layer for reusable agent behavior.
The repo hints at a larger shift in software design. When the caller is another model, the durable artifact may be the skill, not the client library.

The repo that teaches agents to use Replicate

`replicate/skills` is a strange little repo in the best way. It does not try to become the next client library. It teaches an agent how to discover a model, inspect its live schema, and run it correctly.

That is the real shift here. The integration surface moves from code you maintain to instructions an agent can load on demand.

Why this is not a normal integration

The project is built around the Agent Skills format and an MCP bridge. `SKILL.md` carries the procedure, while `.mcp.json` points the agent at the live tools it can actually call. The repository packages know-how, then gives the agent a way to act on it.

I had image generation working in a project. Replicate API wired up, a shell script polling for completion, images landing on disk exactly where I needed them. It worked well enough that I wanted to stop reimplementing it every time I started something new.

Nigel @ Visatics.ai, Developer/Author · Reusable Claude Skill (Medium)

npx skills add replicate/skills

That install step is tiny, which is the point. The repo is not shipping a big runtime. It is shipping a repeatable way for an agent to learn Replicate fast enough to use it well.

How the skill works at runtime

The skill tells the agent to start with discovery, not guessing. It looks for a model or collection, fetches the live OpenAPI schema for that specific target, checks the inputs, and then chooses the execution path that fits the job.

The workflow is simple on the surface, but each step exists to keep the agent synced to the live API instead of a stale wrapper.

The three execution modes matter because not every model should be handled the same way. Polling works for ordinary asynchronous runs, `Prefer: wait` keeps the request synchronous when the job is short, and webhooks let the caller hand completion off to callbacks.

Polling, for standard async jobs that complete after one or more checks.
`Prefer: wait`, for synchronous completion when the model can finish inside the request window.
Webhooks, for callback-driven flows when the caller does not want to hold the connection open.

The clever trick: schema first, code second

This is the most important design choice in the repo. Instead of hardcoding a parameter list and hoping it stays current, the skill asks the agent to fetch the live schema before every run.

That solves the stale-docs problem without forcing humans to babysit the integration. The instructions stay stable, while the shape of the API can change underneath them.

A close-up of a skill page beside a live schema sheet that appears to refresh itself. The two pages are connected by a pen and a cursor, illustrating how the agent checks the current contract before it acts. — Replicate teaches the agent to trust the live schema, not a frozen parameter list.

What it replaces, and what it sits beside

So the right comparison is not winner versus loser. `replicate/skills` lives one level higher than an SDK and one level narrower than a general agent framework. It is procedural knowledge for a very specific job.

Layer	What it ships	When it updates	Best at	Trade-off
Traditional SDK	Typed methods, helper functions, and client wrappers	Only when maintainers publish a new release	Stable human-led integration	Parameters and behaviors can drift from the live API
replicate/skills	A skill file, MCP bridge, and runtime schema checks	Every time the agent loads the skill and fetches schema	Autonomous model discovery and execution	It assumes the caller can follow instructions well
LangChain Skills or Skill Creator	Reusable guidance for a broader ecosystem or for authoring new skills	Depends on the template or framework	Teaching patterns inside a larger agent stack	Less focused on a single API's live execution path

Why this matters beyond Replicate

If more APIs keep changing faster than humans want to pin client versions, the durable artifact may be the skill. The instructions teach the caller how to adapt instead of freezing the world into a wrapper.

That is why this repo matters even if you never ship against Replicate. It shows a new integration pattern that is comfortable with an autonomous caller and suspicious of stale abstraction.