Publish Skills

Publish a batch of skills from a repository into your organization’s skill registry, with each skill’s visibility and access taken from its xpander.yaml.

POST /v1/skills/publish

Publish Skills

cURL

curl --request POST \
  --url https://api.xpander.ai/v1/skills/publish \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "managed_by": {
    "repo": "acme/agent-skills",
    "path_prefix": "skills",
    "ref": "refs/heads/main",
    "commit": "9f1c2d3e4b5a6978877665544332211009988776",
    "run_url": "https://github.com/acme/agent-skills/actions/runs/123456789"
  },
  "archive_missing": true,
  "dry_run": false,
  "skills": [
    {
      "name": "quarterly-report",
      "path": "quarterly-report",
      "skill_md": "---\nname: quarterly-report\ndescription: Build the quarterly revenue report from the finance warehouse.\n---\n\nRead the report template, query the warehouse, and hand back a PDF.\n",
      "bundle_b64": "UEsDBBQAAAAIAEWUV1326OUxfQAAALAAAAAIAAAAU0tJTEwubWRFjTsOwjAQRHufYg8Q5wApEaJG3GBxJrKFf2zWRLk9IUHQTDPvzVhrTeaEgZ6NRSFxtYJaRM2I2UmoGkoe6NRCHEk9/hwJXsgNdPA0SUk7MYXM2YEWFvjSZvTGbjfmBj4mvoIi1ciKbtuErHv1czriPJL/xJ3dg5iu50tv3lBLAwQUAAAACABFlFdd1XJaSmAAAAB5AAAADAAAAHhwYW5kZXIueWFtbEXMMQrDMAwAwF2v0Ac0NEkXf6bIsmoEQQ6WEmhf36GFcvtdFlZtt3wVnBo5TVIbcFfPKIBIyLcvqktdSFZZqW1tI73/AYtoxCNkHFpwzM5ub04bzjv0Oc7jtz3N2UXhA1BLAQIeAxQAAAAIAEWUV1326OUxfQAAALAAAAAIAAAAAAAAAAEAAACkgQAAAABTS0lMTC5tZFBLAQIeAxQAAAAIAEWUV13VclpKYAAAAHkAAAAMAAAAAAAAAAEAAACkgaMAAAB4cGFuZGVyLnlhbWxQSwUGAAAAAAIAAgBwAAAALQEAAAAA",
      "sha256": "6912a8f3e22d54978322f6a50c4a81046716b321ca93af3b4952a669d6753909",
      "metadata": {
        "visibility": "restricted",
        "agents": [
          "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5"
        ],
        "access_scope": "organizational",
        "users": [],
        "groups": [
          "finance"
        ]
      }
    }
  ]
}
'

200

{
  "results": [
    {
      "name": "quarterly-report",
      "outcome": "updated",
      "skill_id": "5b5b5b5b-6c6c-7d7d-8e8e-9f9f9f9f9f9f",
      "detail": "bundle changed; visibility org -> restricted"
    }
  ],
  "archived": [
    "legacy-invoice-check"
  ],
  "warnings": []
}

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 zips every skill folder under managed_by.path_prefix and sends up to 25 skills per call. The bundle must be a zip archive. The managed_by block names 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, and their names come back in archived. dry_run computes every outcome without writing. 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.

Show child attributes

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.

skills · PublishSkillItem · object[]

Up to 25 skills per call. Omit it, with archive_missing: true, to archive every skill this repo and prefix published.

Required array length: 1 - 25 elements

Show child attributes

Response

200

application/json

Successful Response

results · PublishSkillResult · object[] · required

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

Show child attributes

archived · string[]

Names of skills archived by archive_missing.

warnings · string[]

Non-fatal notes about the call.