Consume skills

Discover and load a skill

The SDK connects to a host such as https://skills.example.com. The team key below is a local name for that connection, used when opening a session.

This example shows the SDK operations for howdy: discovery, activation, and an optional resource read. In your agent integration, the agent chooses the skill name before the call to activate().

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

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

const session = await client.session("team");
try {
  const catalog = await session.catalog();
  // Your agent can choose a skill from these names and descriptions.
  const available = catalog.map(({ name, description }) => ({ name, description }));

  const skill = await session.activate("howdy");
  const instructions = skill.instructions;

  const resources = await skill.list();
  if (resources.some(({ path }) => path === "references/welcome.md")) {
    const welcome = await skill.read("references/welcome.md");
    // Include this resource in context when the task needs it.
  }
} finally {
  await session.close();
}

catalog() returns metadata without downloading the skills. activate() downloads and verifies the selected skill, then keeps that copy fixed for the session. Its instructions are the text your integration makes available to the agent.

For the Quickstart's local server, the URL is http://127.0.0.1:8787, with allowLoopbackHttp: true in TypeScript or allow_loopback_http=True in Python.

Read resources as needed

The example checks whether the optional welcome note from Prepare a skill exists before reading it. A loaded skill exposes the same resource operations in both languages:

Activation downloads the complete artifact. These later reads use the verified local copy without another network request, so your agent can bring resources into context as the task needs them. Reading a script returns its contents; it does not execute it.

Keep the session open for the task

The session keeps the selected skills available while your agent uses them. In the example, finally or async with closes it when the work finishes, releasing its cache pins without immediately deleting the downloaded files. Your agent's model calls and resource reads belong inside that lifetime.

You now have the SDK operations for discovery, loading, and resource access. Caching and updates covers how later tasks reuse downloads and see published changes.