Remote Skills
Build and host
Make your skills available to agents beyond your machine.
With a prepared skill and the CLI installed, publishing has three parts: building the files, serving them over HTTPS, and checking that clients can use them. A static host or application server can serve the output.
Build the files
From your skill project, run:
npm exec -- remote-skills buildbuild validates your skills first, then packages them. You do not need to run validate beforehand: that command is a check you can use while writing, without creating output. Validation errors stop the build.
A skill with only SKILL.md becomes a Markdown file; a skill with resources becomes a compressed archive. The build writes a catalog at dist/.well-known/agent-skills/index.json, with skill files in the artifacts/ directory beside it.
Upload the output
The deployment consists of the contents of dist/, served from the root of your HTTPS host. At https://skills.example.com, the catalog is available at:
https://skills.example.com/.well-known/agent-skills/index.jsonThe SDK connects to https://skills.example.com and finds this catalog automatically. Path prefixes such as https://example.com/skills are not supported as discovery locations: the catalog is always looked up at the host-root /.well-known/agent-skills/index.json.
Some deployment tools exclude dot-prefixed directories, so their upload settings need to include .well-known. The catalog uses relative artifact URLs, allowing the generated tree to move between hosts unchanged.
Archives are served exactly as built. Their digest covers the exact response bytes, so unpacking, recompressing, or adding a wrapper folder breaks verification. Keeping the generated filenames also preserves the catalog's download links. Inside each archive, SKILL.md is already at the root.
The host serves each file with its corresponding response type:
| File | Content-Type |
|---|---|
index.json | application/json |
*.md | text/markdown; charset=utf-8 |
*.zip | application/zip |
*.tar.gz | application/gzip |
Artifact filenames include their content digest, so those files can use immutable caching. The catalog changes as you publish; give it ordinary HTTP revalidation with ETag or Last-Modified, not permanent immutable caching.
Using GitHub or GitLab Pages? Git and Pages hosting explains the domain setup.
Verify the origin
After deployment, run:
npm exec -- remote-skills verify https://skills.example.comVerification fetches the catalog and every current or retained release it lists, checks their digests, and validates their structure. Running it with the same network access as your consumers helps confirm they can reach the files too.
Once verification succeeds, the published skills are ready for the SDK. Its connection URL is https://skills.example.com, without the catalog path or the local-development HTTP option.
Verify a private origin
Hosts can require authentication for their skills. The CLI can send the required headers during verification; this example supplies a bearer token through an environment variable:
SKILLS_AUTH='Bearer …' npm exec -- remote-skills verify \
https://skills.example.com \
--header-env Authorization=SKILLS_AUTH \
--scope engineeringThe optional --scope selects a catalog view offered by the host. Authentication and authorization explains how hosts provide those views and how clients request access.
When you publish again, deploy the complete output together and preserve any history you advertise. Versions and history shows how.