---
title: "Publish Repository Skills"
method: POST
path: "/v1/skills/publish"
tags: ["API v1", "Skills"]
---

# Publish Repository Skills

`POST /v1/skills/publish`

## Request

- Base URL: `https://api.xpander.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xpander.ai/v1/skills/publish`
- Auth: API key in header `x-api-key`

The CI writer: mirror a repository's skills into the organization's skills registry as repo-managed skills, up to 25 per call. Each skill answers with its own outcome (created, updated, unchanged, archived or error) and a failing skill never aborts the batch. archive_missing archives repo skills that left the repo; dry_run reports without writing. A user-bound API key stamps the creator, an org key publishes on behalf of the organization.

## Request body

- SkillPublishRequest
  - `managed_by` SkillPublishManagedBy, required: The repo run that owns the published skills; stored on each row as managed_by.
    - `repo` string, required: Repository slug, e.g. 'acme/skills'.
    - `path_prefix` string: Folder inside the repo the skills live under.
    - `ref` string, nullable: Branch or tag that was published.
    - `commit` string, nullable: Commit sha that was published.
    - `run_url` string, nullable: CI run that performed the publish.
  - `archive_missing` boolean: Archive repo-managed skills of this repo that are absent from this publish.
  - `dry_run` boolean: Report the outcomes without writing anything.
  - `skills` SkillPublishItem[]
    - `name` string, required: Skill name (frontmatter name).
    - `path` string, required: Repo-relative folder of the skill.
    - `skill_md` string, required: The SKILL.md document.
    - `bundle_b64` string, required: Canonical zip bundle, base64.
    - `sha256` string, required: Content address the publisher computed for the bundle.
    - `metadata` SkillPublishItemMetadata: Audience declared next to the skill in the repo; mirrored into visibility and grants.
      - `visibility` 'org' | 'restricted' | 'agent'
      - `agents` string[]: Agent ids allowed to hold the skill.
      - `access_scope` 'organizational' | 'personal'
      - `users` string[]: Profile ids granted use.
      - `groups` string[]: Group ids granted use.
  - `as_organization` boolean: Set by the platform from the calling key (an org key names no person); any value a caller sends is replaced.

## Response `200`

Successful Response

- SkillPublishResult
  - `results` SkillPublishOutcome[]
    - `name` string, required
    - `outcome` 'created' | 'updated' | 'unchanged' | 'archived' | 'error', required
    - `skill_id` string, nullable
    - `detail` string, nullable
  - `archived` string[]: Names archived because they left the repo.
  - `warnings` string[]

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xpander/apis/xpander-ai-api-service.md) - [All operations](https://skmtc.dev/xpander/apis/xpander-ai-api-service/llms.txt) - [OpenAPI document](https://skmtc.dev/xpander/apis/xpander-ai-api-service/revisions/725c0066d5df?raw)