Skills

Operations of the Skill Registry API. Paths are relative to your deployment's API host.

GET /api/skill-registry-api/skills

List skills visible to the caller.

Returns every active system skill plus the caller org/project/user skills. Optional filters (scope, kind, biomeId, parentSlug, topLevelOnly) are AND-combined. skillMarkdown is omitted from list rows.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/skill-registry-api/skills

Author a new skill.

Creates a skill + its first server-numbered draft revision. Scope must be org, project, or user. A (scope, slug) collision returns 409.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json CreateSkillDto

GET /api/skill-registry-api/skills/bundle

The full mountable bundle for a skill.

SKILL.md plus every bundled resource (reference docs, scripts, assets, templates) for the highest-precedence visible skill at slug. This is what the workspace composer mounts into /workspace/.opencode/skills/.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/skill-registry-api/skills/bundle

Author a skill as a full multi-file bundle.

Creates or replaces a skill from a complete bundle — SKILL.md plus reference docs, scripts, assets, templates, and nested sub-skills (a resource whose relPath is a nested SKILL.md). The server allocates revisions; identical retries reuse the current draft. Scope must be org, project, or user. A slug owned by a biome/git source returns 409.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json CreateSkillBundleDto

GET /api/skill-registry-api/skills/bundle/by-ref

The full mountable bundle for a skill at an EXACT scope.

Deterministic variant of GET /skills/bundle keyed by canonical XemaObject ref (<scope>/skill/<slug>) — returns SKILL.md + every resource + checksum for the skill at the EXACT scope tier encoded in the ref, WITHOUT scope-precedence resolution. Use it when the caller already knows which scope tier it wants; GET /skills/bundle is the one that resolves precedence at a slug. Its original caller was the workspace-orchestrator content mirror, which no longer exists — no first-party service calls this route today.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/skill-registry-api/skills/lookup

Resolve a skill by its hierarchical slug.

Slugs contain /, so they are passed as a query param rather than a path segment. When the slug exists at multiple scopes the most specific visible one wins: user > project > org > system.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/skill-registry-api/skills/mount-baseline

Every skill slug this caller's agents mount with no configuration.

The System baseline (mandatory core plus what this org enabled) UNION the injectionMode: always skills published at org, project or user space, collapsed by the User > Project > Org ladder. This is what a launch forwards to the composer as its mount set. GET /skills/system-baseline answers only the System half and is the settings surface; an org-scoped always-on skill reaches no worker through it. Pass surface so a skill declaring surfaces: is filtered against the requesting surface, and X-Project-Id so the project tier is visible at all.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/skill-registry-api/skills/registry.json

OpenCode-compatible skill catalog.

A flat catalog (slug, name, description, kind, category, tags) of every visible skill — the progressive-disclosure discovery surface.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/skill-registry-api/skills/search

Search skills by keyword.

Keyword search over skill name and description, scoped to the caller's visible skills. Name matches rank above description-only matches.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json SearchSkillsQueryDto

GET /api/skill-registry-api/skills/system-baseline

Which System skills this org mounts into every agent.

Every System skill that exists, each marked mandatory (mounted regardless) and enabled (mounted for this org). Before the baseline split, every System skill was injected into every agent — including the Studio-authoring skills only an agent building other agents needs.

Authentication: bearer token (Authorization: Bearer <token>)

PATCH /api/skill-registry-api/skills/system-baseline

Enable or disable one optional System skill for this org.

Idempotent. A mandatory skill cannot be disabled (404) — every agent needs it, so the change would not take effect.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json SetSystemSkillEnabledDto

GET /api/skill-registry-api/skills/tree

The visible skill hierarchy as a nested tree.

Top-level skills with their nested sub-skills. A skill whose parent is not visible to the caller is surfaced as a root.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/skill-registry-api/skills/{id}

Get a skill by id.

Returns the skill including its working-draft SKILL.md body when present, otherwise its live revision body.

Authentication: bearer token (Authorization: Bearer <token>)

PATCH /api/skill-registry-api/skills/{id}

Update a skill.

Updates metadata in place. Changed skillMarkdown creates a new immutable, server-numbered draft revision; identical content is idempotent. The live revision is unchanged until approval. System/biome skills are read-only.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json UpdateSkillDto

DELETE /api/skill-registry-api/skills/{id}

Delete a skill.

Removes the skill and its entire bundle subtree — every version, resource, eval suite, governance event, and nested sub-skill cascade-delete with it. System/biome skills are read-only — 409 with a fork-first hint.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/skill-registry-api/skills/{id}/rescope

Re-scope a skill — publish it to a project or to the organisation.

PROMOTES the skill's owner up the tier ladder so it becomes visible to a broader audience. This is how "publish to my org" is expressed: there are no junction tables here, availability is implicit-by-scope, so moving the OWNER is the operation. Legal promotions come from the kernel — user → project|org, project → org. Demotion, same-tier, and moves into or out of biome/system are refused with 422; a tier this registry does not own (app, session) with 400. Promoting to org requires the org admin role — it changes what every member of the organisation resolves — while project and user targets are ordinary member authoring authority. A slug already taken at the target space is a 409, never a silent overwrite. A deliverable skill is refused: its bundle is generated by a projection path that owns the space it sits in.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json RescopeSkillDto

GET /api/skill-registry-api/skills/{resourceId}/revisions/{revisionId}/authority

Resolve one exact immutable published Skill revision.

Reads the existing AuthoredResource identity/revision tuple directly and never follows the mutable current-version pointer. Returns the canonical owner, canonical stored revision content for strict local hash verification, and the complete resolved mount bundle.

Authentication: bearer token (Authorization: Bearer <token>)