Resources API: Publish, Browse, and Download Skills

The Resources API is the core of the Skillset catalog. It covers everything from browsing the public list of Skills to publishing a new version and downloading the Artifact zip. Catalog reads (list, fetch, file access, artifact download) require no authentication; writes and deletes are role-gated.

Endpoints at a glance

Method	Path	Auth	Description
GET	`/api/resources`	None	List and search the catalog
GET	`/api/resources/stats`	None	Catalog hero counts
GET	`/api/resources/:kind/by-name/:name`	None	Fetch a Resource by Kind and name
GET	`/api/resources/:id`	None	Fetch a Resource by id
GET	`/api/resources/:id/installs/trend`	None	Daily install trend
PUT	`/api/resources/:kind/:name`	Writer+	Publish a Resource
PUT	`/api/resources/:id/tags`	Writer+	Replace a Resource’s Tags
DELETE	`/api/resources/:id`	Admin+	Delete a Resource
GET	`/api/resources/:id/files`	None	List Artifact files
GET	`/api/resources/:id/files/:path`	None	Read one Artifact file
GET	`/api/resources/:id/artifact`	None	Download the Artifact zip

List the catalog

GET /api/resources

Returns a paginated, optionally filtered and sorted directory of all Resources. No authentication required — any anonymous client can browse the catalog.

Query parameters

kind

string

Filter by Resource Kind. Accepted value: skill.

string

Full-text search term. Matches against name and description. Falls back to trigram matching when no full-text matches exist, so a mistyped query still finds the right Skill.

tag_id

string

Filter to Resources carrying the Tag with this id. Obtain Tag ids from GET /api/tags.

page

integer

default:"1"

Page number (1-based).

page_size

integer

default:"10"

Records per page. Clamped to the range 1–100; values outside that range are clamped rather than rejected.

sort_by

string

default:"updated_at"

Sort order. One of installs, updated_at, or relevance. When q is set the default becomes relevance; requesting relevance with no q falls back to updated_at.

Response fields

items

array

Array of Resource directory entries. Each entry contains:

Show child attributes

string

UUID of the Resource.

kind

string

Resource Kind (skill).

namespace

string

Publishing identity — owner/repo for Imports, Registry domain for direct publishes.

name

string

Resource name.

description

string

Short description.

published_by_name

string

Snapshot of the publisher’s name at publish time.

updated_at

string

ISO 8601 timestamp of the last publish.

allowed_tools

string | null

Tools the Skill claims access to, or null if unset.

source

string

Repository URL for Imports; reverse-DNS Registry domain for direct publishes.

installs

integer

Total recorded installs (periodically refreshed).

Catalog stats

GET /api/resources/stats

Returns unfiltered, registry-wide counts. These are the numbers shown in the catalog hero banner and are independent of any search or filter.

Response fields

skills

integer

Total number of Skills in the Registry.

publishers

integer

Number of distinct publishers who have published at least one Skill.

installs

integer

Total install count across all Skills (periodically refreshed).

curl https://registry.example.com/api/resources/stats

Fetch by Kind and name

GET /api/resources/:kind/by-name/:name

Returns the full Resource record (including body) for the given Kind and name.

Path parameters

kind

string

required

Resource Kind. Currently skill.

name

string

required

Resource name.

Query parameters

namespace

string

Namespace to resolve the name within. Omit to use this Registry’s own namespace. Required when the same name exists in multiple namespaces — the server returns 409 ambiguous_name if it cannot resolve unambiguously.

Error codes

Code	Status	When
`not_found`	404	No Resource with that Kind and name.
`ambiguous_name`	409	The name exists in multiple Namespaces and none is this Registry’s own.

curl "https://registry.example.com/api/resources/skill/by-name/build-react-app?namespace=acme/skills"

Fetch by id

GET /api/resources/:id

Returns the full Resource record, including the Skill body, by UUID.

Path parameters

string

required

UUID of the Resource.

curl https://registry.example.com/api/resources/018f1234-abcd-7000-8000-000000000001

Install trend

GET /api/resources/:id/installs/trend

Returns a daily install timeseries for the Resource over a trailing window (oldest first).

Path parameters

string

required

UUID of the Resource.

Response fields

points

array

Ordered array of daily counts. Each point has:

Show child attributes

date

string

YYYY-MM-DD (UTC).

count

integer

Installs recorded on that day.

Publish a Resource

PUT /api/resources/:kind/:name

Creates or replaces a Resource. This is a full replace — every field is overwritten on republish. Requires Writer role or higher. Publishing a Skill with an Artifact is a two-step process:

Send the publish request

Send PUT /api/resources/skill/:name with the metadata body. The files field declares the Artifact manifest — the paths and byte sizes of every file you intend to upload.

Upload Artifact files

For each entry in upload.files, PUT the file bytes directly to the presigned url using the supplied method and headers. Files are uploaded straight to object storage — they never pass through the API.

Path parameters

kind

string

required

Resource Kind. Currently skill.

name

string

required

Resource name. Must match the name field in the Skill’s SKILL.md frontmatter.

Request body

description

string

required

Short description of the Skill (max length enforced by the shared rules).

body

string

required

Full SKILL.md Markdown content (the body of the Skill document, excluding frontmatter).

files

array

required

Artifact manifest: one entry per file to upload. Each entry has:

path (string) — path relative to the Skill root
size (integer) — byte size of the file

license

string

SPDX license identifier or custom license text.

compatibility

string

Agents or environments this Skill is compatible with.

metadata

object

Free-form string-to-string key/value pairs.

allowed_tools

string

Comma-separated list of tools the Skill is permitted to invoke.

source

string

Repository URL this Skill was imported from. Omit to record this Registry as the source.

Response fields

skill

object

The Resource as stored — full SkillSchema shape including id, kind, name, description, body, published_by, published_at, updated_at, installs, tags, namespace, source, license, compatibility, metadata, and allowed_tools.

upload

object

Presigned upload destinations for the Artifact files.

Show child attributes

files

array

One entry per file in the same order as the manifest you sent. Each entry has path, url, method (PUT), and headers to use when uploading.

expires_in_seconds

integer

How long the presigned URLs remain valid.

curl -X PUT https://registry.example.com/api/resources/skill/build-react-app \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A Skill for scaffolding React applications with Vite.",
    "body": "# Build React App\n\nThis Skill helps you...",
    "license": "MIT",
    "files": [
      { "path": "SKILL.md", "size": 1024 },
      { "path": "references/react.md", "size": 4096 }
    ]
  }'

Set Resource Tags

PUT /api/resources/:id/tags

Fully replaces the Tags on a Resource. The body is the complete new set — omitting a Tag that was previously attached removes it. Requires Writer role or higher. Tags are referenced by name; the server resolves each name to an existing catalog Tag or creates one.

Path parameters

string

required

UUID of the Resource.

Request body

Response

Returns { "tags": [{ "id": "...", "name": "..." }, ...] } — the resolved Tags now attached to the Resource.

curl -X PUT https://registry.example.com/api/resources/018f1234-abcd-7000-8000-000000000001/tags \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["typescript", "react", "frontend"] }'

Delete a Resource

DELETE /api/resources/:id

Permanently removes the Resource and its stored Artifact. Requires Admin role.

Path parameters

string

required

UUID of the Resource to delete.

Returns 204 No Content on success.

curl -X DELETE https://registry.example.com/api/resources/018f1234-abcd-7000-8000-000000000001 \
  -H "Authorization: Bearer <token>"

List Artifact files

GET /api/resources/:id/files

Returns the manifest of every file stored in the Resource’s Artifact — paths and byte sizes, but not content. No authentication required.

Path parameters

string

required

UUID of the Resource.

Response fields

files

array

Sorted list of Artifact files. Each entry has:

Show child attributes

path

string

Path relative to the Skill root (e.g. SKILL.md, references/react.md).

size

integer

Byte size of the file.

curl https://registry.example.com/api/resources/018f1234-abcd-7000-8000-000000000001/files

Read one Artifact file

GET /api/resources/:id/files/:path

Returns the raw bytes of one file from the Resource’s Artifact. The Content-Type header is derived from the file’s extension. No authentication required.

Every file (except PDFs) is served with a strict Content-Security-Policy that disables scripts, plugins, and all external fetches. This prevents uploaded HTML, SVG, or XML files from executing against your Registry’s origin.

Path parameters

string

required

UUID of the Resource.

path

string

required

Path within the Artifact, preserving slashes (e.g. references/java.md).

curl https://registry.example.com/api/resources/018f1234-abcd-7000-8000-000000000001/files/SKILL.md

Download the Artifact zip

GET /api/resources/:id/artifact

Assembles the full Artifact on demand as a zip archive and returns it. Records one install event per unique client per day (deduplicated by IP and User-Agent hash). No authentication required.

Path parameters

string

required

UUID of the Resource.

Query parameters

source

string

default:"web"

Caller identity for install analytics. One of web, cli, or mcp. Unrecognised or absent values are treated as web so old clients continue to work.

Returns a application/zip stream with Content-Disposition: attachment; filename="<name>.zip".

# CLI install
curl -o build-react-app.zip \
  "https://registry.example.com/api/resources/018f1234-abcd-7000-8000-000000000001/artifact?source=cli"

Overview

Endpoints

Resources API: Publish, Browse, and Download Skills

Endpoints at a glance

List the catalog

Query parameters

Response fields

Catalog stats

Response fields

Fetch by Kind and name

Path parameters

Query parameters

Error codes

Fetch by id

Path parameters

Install trend

Path parameters

Response fields

Publish a Resource

Path parameters

Request body

Response fields

Set Resource Tags

Path parameters

Request body

Response

Delete a Resource

Path parameters

List Artifact files

Path parameters

Response fields

Read one Artifact file

Path parameters

Download the Artifact zip

Path parameters

Query parameters

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Endpoints at a glance

​List the catalog

​Query parameters

​Response fields

​Catalog stats

​Response fields

​Fetch by Kind and name

​Path parameters

​Query parameters

​Error codes

​Fetch by id

​Path parameters

​Install trend

​Path parameters

​Response fields

​Publish a Resource

​Path parameters

​Request body

​Response fields

​Set Resource Tags

​Path parameters

​Request body

​Response

​Delete a Resource

​Path parameters

​List Artifact files

​Path parameters

​Response fields

​Read one Artifact file

​Path parameters

​Download the Artifact zip

​Path parameters

​Query parameters

Build docs developers (and LLMs) love

Endpoints at a glance

List the catalog

Query parameters

Response fields

Catalog stats

Response fields

Fetch by Kind and name

Path parameters

Query parameters

Error codes

Fetch by id

Path parameters

Install trend

Path parameters

Response fields

Publish a Resource

Path parameters

Request body

Response fields

Set Resource Tags

Path parameters

Request body

Response

Delete a Resource

Path parameters

List Artifact files

Path parameters

Response fields

Read one Artifact file

Path parameters

Download the Artifact zip

Path parameters

Query parameters