Skip to content
Skillist
Open app

Delivery URLs

Skillist uses a single GitHub-like namespace on the apex domain. The org is the organization slug; repo is the skill identifier (formerly called slug in older API versions).

URL map

Section titled “URL map”
PurposeURL
Registry browsehttps://skillist.io/registry
Skill pagehttps://skillist.io/{org}/{repo}
SKILL.md (latest)https://skillist.io/{org}/{repo}/SKILL.md
SKILL.md (pinned)https://skillist.io/{org}/{repo}@{version}/SKILL.md
Discovery metahttps://skillist.io/{org}/{repo}/meta
Full bundlehttps://skillist.io/{org}/{repo}/bundle
Script listhttps://skillist.io/{org}/{repo}/scripts
Run scriptPOST https://skillist.io/{org}/{repo}/run
Run historyhttps://skillist.io/{org}/{repo}/runs

Example

Section titled “Example”

For the public skill skillist/web-perf-audit:

https://skillist.io/skillist/web-perf-audit
https://skillist.io/skillist/web-perf-audit/SKILL.md
https://skillist.io/skillist/web-perf-audit/meta
https://skillist.io/skillist/web-perf-audit@1.4.2/SKILL.md

Version pinning

Section titled “Version pinning”

Append @{version} to the repo segment of any delivery URL (SKILL.md, meta, bundle) to pin an exact published version:

  • {repo} or {repo}@latest — the mutable latest URL. Fresh for 60s and always resolves to the newest published version; the X-Skillist-Version response header tells you what it resolved to.
  • {repo}@1.4.2 — an exact, previously published version. Immutable: served with Cache-Control: public, max-age=31536000, immutable, so agents and CI can cache it forever. Superseded (archived) versions stay addressable; drafts and unpublished versions 404.

Pin exact versions in lockfiles and reproducible agent configs; use the latest URL when you want a skill’s self-improvement loop delivered automatically.

Caching and integrity

Section titled “Caching and integrity”

Delivery responses are edge-cached and support conditional requests:

HeaderMeaning
ETagVersion identifier for the response. Send it back as If-None-Match to get a 304 with no body when the skill is unchanged.
Cache-ControlLatest URLs: SKILL.md and meta are fresh for 60s, bundles for 300s, with stale-while-revalidate and serve-stale-on-error. Version-pinned URLs are immutable (max-age=31536000).
X-Skillist-VersionThe published semver this response resolved to.
X-Skillist-Content-Sha256Full sha256 of SKILL.md — verify the content you fetched matches what was published. Also returned as contentSha256 in /meta.

Poll cheaply with a conditional request:

Terminal window
curl -H 'If-None-Match: "<etag>"' https://skillist.io/skillist/web-perf-audit/SKILL.md
# → 304 Not Modified (empty body) until a new version is published

For push instead of polling, use the realtime feed.

REST equivalents

Section titled “REST equivalents”

Registry metadata and mutations still use the API worker under /v1:

GET https://api.skillist.io/v1/registry
GET https://api.skillist.io/v1/registry/{org}/{repo}

Raw delivery and hosted execution are also available on api.skillist.io when called directly, but canonical public URLs use skillist.io.

CLI and agents

Section titled “CLI and agents”

The CLI defaults delivery to https://skillist.io:

Terminal window
skillist install skillist/web-perf-audit
curl https://skillist.io/skillist/web-perf-audit/SKILL.md

Override for staging or local dev:

Terminal window
export SKILLIST_DELIVERY_URL=http://localhost:5173
export SKILLIST_API_URL=http://localhost:8787

MCP install help

Section titled “MCP install help”

registry_install_help returns apex delivery URLs:

  • skillMdUrl — https://skillist.io/{org}/{repo}/SKILL.md
  • registryUrl — https://skillist.io/{org}/{repo}

See Tools reference for parameters (org and repo).

How routing works

Section titled “How routing works”

DNS zone routing cannot place wildcards mid-path (e.g. skillist.io/*/SKILL.md), so delivery is implemented in two layers:

  1. API worker — serves /{org}/{repo}/SKILL.md, /meta, /bundle, and authenticated /scripts, /run, /runs
  2. Web worker — intercepts the same paths on skillist.io and forwards them to the API worker via a service binding; also proxies /v1/* and /api/* for same-origin SPA requests

The registry browse UI and skill detail pages are served as static assets with SPA fallback.

Section titled “Related”