Quickstart

Create a skill

In your project, create skills/howdy/SKILL.md:

---
name: howdy
description: Greet someone with a friendly cowboy welcome.
---

When greeting someone, say "Howdy partner!" and offer to help.

The name identifies the skill. The description helps an agent decide when to use it. The Markdown body contains the instructions.

Serve it

First, install the CLI in your skill project:

npm install -D @remote-skills/cli

Then, start the development server:

npm exec -- remote-skills dev

Leave this terminal running. Your skill is now available at http://127.0.0.1:8787. Changes to the skill are rebuilt automatically.

Use it in your agent

Using Vercel AI SDK? Follow the integration guide to connect its skill loader. The example below uses a small interface you can adapt to other agents.

First, install the SDK in your agent's application:

npm install @remote-skills/client

Then, connect it to the running server. The example activates howdy and passes its instructions into your agent's model context.

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

const skills = createRemoteSkills({
  origins: {
    local: { url: "http://127.0.0.1:8787", allowLoopbackHttp: true },
  },
});

// Adapt this small interface to your agent's API.
type Agent = {
  run(options: { instructions: string; input: string }): Promise<string>;
};

export async function greet(agent: Agent): Promise<string> {
  const session = await skills.session("local");
  try {
    const skill = await session.activate("howdy");
    return await agent.run({
      instructions: skill.instructions,
      input: "Hello!",
    });
  } finally {
    await session.close();
  }
}

Call await greet(yourAgent) from your application (await greet(your_agent) in Python). agent.run represents your existing agent; it is the only integration point to adapt. Add the skill instructions alongside your agent's existing instructions, then run its usual model call. Remote Skills makes no model call itself.

To check retrieval on its own, inspect skill.instructions before the agent call. It should contain the greeting instruction you wrote above. The intended agent response begins with “Howdy partner!”; the exact response depends on your model.

activate() downloads and verifies the skill before returning it. The local HTTP option is only for development; use an HTTPS origin in production.