Skip to main content
POST
Publish Skills
Publish is the call a CI job makes when a skills repository merges. The repository holds one folder per skill, each with a SKILL.md (the instructions the agent reads) and an xpander.yaml (the registry contract). On merge, CI bundles every skill folder under managed_by.path_prefix and sends up to 25 skills per call, with the managed_by block naming the repo, ref, commit and run URL. The response holds one outcome per skill in results: created, updated, unchanged, archived or error, with its skill_id and a short detail. A matching sha256 returns unchanged. archive_missing archives the skills this repo and prefix published earlier that the call no longer lists (their names come back in archived), dry_run computes every outcome without writing, and non-fatal notes arrive in warnings. Publishes and archives are audited as PUBLISH_SKILL and ARCHIVE_SKILL. Authenticate with an organization API key in x-api-key. xpander.yaml carries the skill’s access, and each skill’s metadata mirrors it. visibility is org (any agent in the organization may hold the skill), restricted (only the agents listed in agents) or agent (one owner agent, the single entry in agents). access_scope is organizational for the organization’s catalog or personal for the publisher’s own. users and groups are the user and group audiences of Manage access: who sees the skill in the catalog. How the scope is enforced at runtime is on Skill visibility; how it looks to a builder is on Skills.

Authorizations

x-api-key
string
header
required

API Key for authentication

Body

application/json
managed_by
PublishManagedBy · object
required

Where the skills come from. Stored on each published skill so the registry knows which repository manages it.

skills
PublishSkillItem · object[]
required

Up to 25 skills per call.

Required array length: 1 - 25 elements
archive_missing
boolean
default:false

Archive skills that this repo and prefix published earlier and that are absent from skills. Their names are returned in archived.

dry_run
boolean
default:false

Compute every outcome without writing to the registry.

Response

Successful Response

results
PublishSkillResult · object[]
required

One entry per skill in the request, in request order.

archived
string[]

Names of skills archived by archive_missing.

warnings
string[]

Non-fatal notes about the call.