push
POST /v1/skills — create-or-version by slug. An unknown slug creates the skill; a known slug with changed content mints a new version; an identical push is a no-op (content-addressed).
string
required
The skill’s stable handle.
string
required
The markdown body.
string
One-line summary.
string
An integrity claim checked against the server’s own digest of
content — never the digest of record. A mismatch is rejected with validation_failed, param: "sha256".id and slug — which is what makes chaining into pushVersion work.
pushVersion
POST /v1/skills/{ref}/versions — the same push addressed at a skill that already exists, by id or slug. Distinct from push on purpose: an unknown ref is a 404, not a create, so a release pipeline pinned to a skill id cannot silently mint a second skill after a rename.
list
GET /v1/skills, cursor-paginated.
get
GET /v1/skills/{slug} — by slug or id. Metadata only; the body costs a getVersion call.
listVersions
GET /v1/skills/{slug}/versions. Newest first. The cursor is the version number, not an id — versions have none of their own.
getVersion
GET /v1/skills/{slug}/versions/{version}. This is the call that returns the content — progressive disclosure: the body costs this second call, never every turn.
delete
DELETE /v1/skills/{slug}. Removes the skill and its versions.
catalog.list
GET /v1/skills/catalog — the platform catalogue: the newest version of every published skill, alphabetical by slug, without content. tag narrows to one family (agency, seo, media, …) and search is free text over slug, name and description. The cursor is a slug. Any authenticated caller may read it, an organization or not.
client.skills.catalog.get(slug)
GET /v1/skills/catalog/{slug} — the newest version of one slug, without content: what a naive/<slug> reference resolves to right now, and the number to pin as naive/<slug>@N. A slug nothing published is a 404 not_found naming slug.
catalog.retrieve
GET /v1/skills/catalog/{slug}/versions/{version} — one published version with its content. version is the number from the list (or the one you want to pin as naive/<slug>@N); an unknown slug or version is a 404 not_found naming slug.