Caching and updates

Once an agent has loaded a skill, later tasks can reuse the download. Caching saves that work, while sessions keep a running task on the same instructions even when the publisher releases an update.

What is cached

The SDK keeps downloaded skills on disk in the operating system's cache directory. Each copy is identified by its content digest, so identical downloads share storage. It also remembers the catalog—the list of skills available from a publisher—to decide whether a saved copy is still the one your agent needs.

Loading a skill downloads the complete artifact, including any resources, and verifies it before adding it to the cache. Later read() calls use those local files. This is context-lazy access: your agent can read a resource only when it needs it, although that resource has already been downloaded.

The cache is disposable, not a skill installation or backup. A persistent volume lets a container reuse it after a restart; without one, the SDK downloads the files again. Memory-only and custom cache backends are also available when disk storage does not fit your application.

See a publisher's update

An existing session keeps the skills it has selected. When a new session opens, the SDK uses the publisher's HTTP caching headers to decide whether to reuse its catalog or check for an update.

To ask for a fresh catalog before a new task, call refresh():

import { createRemoteSkills } from "@remote-skills/client";

const client = createRemoteSkills({
  origins: { team: { url: "https://skills.example.com" } },
});

await client.refresh("team");
const session = await client.session("team");
try {
  const skill = await session.activate("howdy");
  // Use skill.instructions for this task.
} finally {
  await session.close();
}

refresh() affects future sessions only, so a running task keeps its original instructions. The SDK does not poll for updates in the background.

If a publisher removes a release from its catalog, new online sessions can no longer select it—even if an old download is still on disk. They use the publisher's current list of releases, not a list of everything the agent has ever downloaded.

Continue offline

If the connection drops during a task, its session can keep reading skills it has already loaded. Starting another task is different: the SDK needs a usable catalog to know which skills are available. By default, the new session fails if it cannot establish that.

You can opt into a bounded fallback to a previously verified catalog. This example permits a catalog up to one hour old:

import { createRemoteSkills } from "@remote-skills/client";

const client = createRemoteSkills({
  origins: {
    team: {
      url: "https://skills.example.com",
      stale: { maxAgeMs: 60 * 60 * 1000 },
    },
  },
});

const session = await client.session("team");
try {
  console.log({ stale: session.metadata.stale });
  const skill = await session.activate("howdy");
} finally {
  await session.close();
}

For this to work without a connection, both the catalog and the selected skill must already be cached. The session reports stale: true when it falls back to an older catalog, making that choice visible to your application. Cached skill files still have to pass integrity checks; offline mode does not allow damaged content through.

The tradeoff is delayed updates: until your agent sees a fresh catalog, it may still select a release the publisher has removed. The one-hour limit above bounds how long that older catalog can be used.

Cache cleanup

The SDK keeps disk usage within its configured size and age limits by removing eligible cached files. Files in use by a live session are protected from that cleanup, so closing a session makes its files eligible for removal again; it does not delete them immediately.

TypeScript and Python share the same cache format and can reuse the same directory. Writes become available to other sessions only when complete and verified. If a write is interrupted, cleanup can reclaim its temporary files after checking that they are old enough and no longer in use.

For selecting named releases instead of the current skill, see Versions and history.