Remote Skills
How it works
What happens between discovering a skill and using it in your agent.
Remote Skills keeps the same SKILL.md, resources, and discover-then-load workflow as filesystem-based Agent Skills. What changes is delivery: instead of installing skill folders into each agent's environment, you publish them once and let agents load them remotely. There is no new skill format to learn or rewrite your skills for.
Discover, then activate
The publisher hosts a catalog: a small index of skill names, descriptions, and download information. A client reads it from the origin's standard discovery URL.
session.catalog() gets the metadata. Your application or agent chooses a skill by name. session.activate("howdy") downloads the selected skill and verifies it before returning the instructions. Remote Skills does not choose a skill or call a model for you.
One session keeps one version
A session is the lifetime of a task in your application. It uses one catalog snapshot, and each activated skill stays fixed to the exact bytes it selected. This is called pinning.
If you update howdy while an agent is using it, that agent's session stays consistent. Future sessions can see the update. client.refresh() requests fresh catalog information for future sessions; it never replaces a skill inside an existing one.
A session stays open for as long as the task needs its skills. Closing it releases the cache entries it was keeping in use; Caching and updates explains what happens next.
Download size and context size are different
A skill may contain instructions plus references, templates, or other files. Activation downloads the complete artifact and extracts archives into a local cache.
Your agent can start with skill.instructions and use read() for a resource when the task needs it. Those reads use the verified local copy and make no further network requests. This is context-lazy access: it saves context, not download bandwidth or disk space.
The publisher and the application keep control
The publisher decides what is available from its origin. Your application decides which origins to trust, which skill to use, and what the agent is allowed to do.
Verification confirms that the downloaded bytes match the catalog. It does not judge the instructions or grant permission to run scripts. Trust and security explains these boundaries in detail.