API reference

Reference for @remote-skills/client, Python's remote_skills, the Vercel AI SDK integration, the Mastra integration, the TanStack AI integration, and the LangChain and DeepAgents integration. Method tables show awaited return values: TypeScript methods return promises, and Python async methods are awaited. For a runnable integration, see Consume skills.

Client creation

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

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

Origin settings

All fields except url are optional. Origins use HTTPS; URL credentials, query strings, and fragments are rejected. Discovery uses the host-root /.well-known/agent-skills/index.json, regardless of a path in url.

Network policy

Address checks apply to each connection and redirect. Trust and security explains the policy; Authentication and authorization covers credential handling.

Client methods

catalog

The result contains entries and failures. Each failure includes originAlias (TypeScript) or origin_alias (Python) and error. Strict-mode exceptions are CatalogAggregateError in TypeScript and AggregateCatalogError in Python, both exposing failures.

session

TypeScript configures stale fallback through OriginConfig.stale.maxAgeMs. Both default to requiring an online catalog unless an acceptable fresh cached catalog is available. See Caching and updates for fallback conditions.

refresh

Revalidates the selected origin's catalog, or all configured origins when omitted. Affects future sessions only; existing sessions and their selected skills stay unchanged.

Session methods

catalog

Returns the session's fixed catalog snapshot without loading skill instructions.

activate

Downloads and verifies the complete artifact, then pins the chosen bytes for the session. Later activation calls for the same skill return that pinned selection, even if a different range is passed. Range syntax and prerelease rules are in Versions and history.

close

Releases the session's cache pins. Further catalog, activation, and resource operations fail with session_closed. TypeScript also supports async disposal; Python's async with closes the session automatically.

Session metadata

Returned data

Catalog entries

Activated data

Resource methods

TypeScript methods return promises. Python methods are awaited. All reads use already verified local files; they do not make additional network requests or execute scripts.

Each listed resource has path, size (bytes), and media_type. Listings describe files; they do not include file contents or grant permission to use them.

Activation limits

Configured through limits in TypeScript or ActivationLimits(...) passed as Python's limits argument. Values are positive integers; byte limits are measured before text decoding.

Catalog size is controlled separately by the origin's catalog-byte limit.

Scoped catalogs

The provider authorizes catalog views and artifact downloads using the caller's identity. Authentication and authorization covers both sides of this contract.

Catalog version history

Optional wire extension for version selection; Versions and history covers authoring and publishing.

Vercel AI SDK integration

remoteSkills(options: RemoteSkillsOptions): Promise<RemoteSkillsIntegration> is exported by @remote-skills/ai-sdk. For installation and a complete agent example, see Vercel AI SDK.

Source options

Exactly one source form is accepted:

Every form also accepts:

Creation discovers metadata without activating skills. Authentication, scopes, cache, transport, timeouts, and limits come from the supplied client or session. If setup fails, sessions opened by the integration are closed; a caller-owned session stays open.

Returned integration

The package also exports the types RemoteSkillsOptions, RemoteSkillsIntegration, and RemoteSkillsTools.

Model-facing tools

Tool errors retain SDK error codes without diagnostic context. Unexpected tool failures return a fixed message; setup errors remain available to the application. Abort signals are checked around tool operations, but an already-started SDK download follows the client's timeout and session-close behavior rather than per-call cancellation.

LangChain integration

@remote-skills/langchain and Python's remote_skills_langchain connect an SDK session to native skills and filesystem middleware. For installation, model setup, and complete examples in both languages, see LangChain and DeepAgents.

LangChain source options

The TypeScript versions type is Readonly<Record<string, string>>; Python accepts Mapping[str, str]. Authentication, scopes, caching, request limits, and verification come from the supplied session's client. See origin settings. Invalid adapter options raise RemoteSkillsError with configuration_invalid in TypeScript, or ValueError in Python.

Version ranges restrict SDK activation to releases still advertised by the publisher. The first activation pins a release for the session; later adapter options cannot replace that pin. Use one version policy per session. Versions and history explains selection and retention.

LangChain returned adapter

Discovery and root listings download no artifacts. Content reads activate and verify the complete artifact once; subsequent reads reuse those bytes. Native read_file retains text pagination and line numbering. Binary resources remain available through the content backend and SDK resource methods.

LangChain composition

Keep DeepAgents' returned backend, skills, and middleware together. They connect discovery to metadata and file reads to verified content, including in the default general-purpose subagent. Using only the content backend with automatic skills loading downloads artifacts during discovery; using only middleware leaves the default subagent without its catalog. For custom named subagents, pass the same native middleware through their middleware option so they share the SDK session and its pins.

LangGraph support requires a native agent subgraph. Arbitrary raw model or tool nodes do not run LangChain middleware; there is no standalone middleware runtime supplied by this integration. The guide's LangGraph example shows the complete node composition.

LangChain lifetime and runtime

The native filesystem middleware exposes only ls and read_file. The adapter supplies no write, search, or command-execution tool and disables filesystem offloading because its content is read-only. It does not install files into an agent workspace. Digest verification establishes byte integrity; your application still controls content trust and tool authorization, including any tools a skill requests through allowed-tools.

Mastra integration

remoteSkills(options: RemoteSkillsOptions): Promise<RemoteSkillsIntegration> is exported by @remote-skills/mastra. For installation and a complete agent example, see the Mastra guide.

Mastra source options

Exactly one source form is accepted:

Both forms also accept:

Creation discovers catalog metadata without downloading skill contents. Authentication, scopes, cache policy, transport, timeouts, and limits come from the supplied client or session. One integration binds one origin and one credential context. If setup fails, a session opened by the integration is closed; a caller-owned session stays open.

Mastra integration members

The package also exports the types RemoteSkillsOptions and RemoteSkillsIntegration. Consume response streams before closing the integration. When reusing a caller-owned session, close the integration first, then close the session when your application has finished using it.

Mastra native tools

These are Mastra's existing Workspace tools, with native schemas and result formatting. The integration loads and verifies selected content before the native tool runs.

Mastra composition

Pass your hooks through the hooks option. Your before hook runs before activation and can deny a call with { proceed: false }. Your after hook runs after the native tool; Mastra does not invoke it when a before hook fails or denies the call.

Retain the supplied Workspace, hooks, and instructions on the agent. Replacing hooks at construction or execution, renaming native skill tools, or calling the raw Workspace loader bypasses the required loading path. Reserve skill, skill_read, and skill_search for the native tools and avoid same-named skills from other sources.

The integration creates its own skills-only Workspace; it does not merge an existing Workspace, add filesystem or sandbox tools, or index the whole remote catalog. It runs in Node.js on the server. For skill selection and reading within an application, use the Agent tool path shown in the guide.

TanStack AI integration

remoteSkills(options: RemoteSkillsOptions): Promise<RemoteSkillSource> from @remote-skills/tanstack-ai returns a native TanStack SkillSource. Pass it to withSkills(skillSource) for catalog discovery and the automatically registered load_skill tool. Optionally add createResourceTool(skillSource) to read supporting files with read_skill_resource; omit that tool for skills that need only their SKILL.md instructions. Both loaders return content through ordinary tool calls and results. See the TanStack guide for setup.

Keep one source per conversation and keep it open until the response completes. Pins survive client.refresh(); later sessions can select newer artifacts. TanStack tracks loaded skills per chat() call. The source does not implement revision keys or script methods, execute content, or add host instructions. SDK error codes are preserved with diagnostic context removed. The exact supported TanStack version is declared in the package peer dependencies; the lockfile pins tested development versions.

Request failures

Stable error codes

SDK errors expose code, retryable, and sanitized context. Catalog and request errors use RemoteSkillsError in TypeScript and CatalogError in Python; cache operations can also raise CacheConfigurationError or CacheCorruptError. Diagnostics exclude credentials, response bodies, instructions, and resource contents; URL context is sanitized.