Library

Publish a skill to the global catalog

Transitions a skill in the caller's account from private to global visibility, making it discoverable in the public catalog.

Idempotent. Calling publish on an already-global skill returns 200 with action: "unchanged" rather than a 409 — consistent with the CLI retry-loop semantics established by POST /library and DELETE /library/{owner}/{name}.

Permission gate. Admin+ members are always allowed. Members with canPublish: true on their per-membership settings (or memberCanPublish: true on the account default) are also allowed — see docs/ENTITLEMENTS.md. The same canPublish entitlement gates /unpublish symmetrically.

Publish-only preconditions (not enforced on unpublish):

  • An Author ID must be chosen — blocked while the account's handle is still the auto-generated placeholder (GitHub-derived handles count as chosen). Set an Author ID in Settings → Account Profile to unblock (code: namespace_unset).
  • On editions with safety analysis enabled, the skill must have a non-null safetyGrade (code: analysis_pending).
  • The safety grade must not be F (code: safety_grade_too_low).

Idempotency. Optional Idempotency-Key header: retries with the same key + same body return the cached response with Idempotent-Replayed: true; retries with a different body return 422 idempotency_key_reused.

Rate-limit bucket: cli-crud (60/min per key).

post/api/v1/library/{owner}/{name}/publish

Request

  • Base URL: https://skillrepo.dev
  • URL: https://skillrepo.dev/api/v1/library/{owner}/{name}/publish
  • Auth: HTTP bearer

Path parameters

ownerstring required
namestring required

Headers

Idempotency-Keystring

Client-supplied idempotency key (max 255 chars). Retries with the same key + same request body return the cached response (with Idempotent-Replayed: true) instead of re-executing the handler. Retries with the same key + a different body return 422 idempotency_key_reused. Concurrent retries while the original is in-flight return 409 idempotency_key_in_progress. Cached responses live for 24 hours.

Response

Either the skill was published (action: "published") or it was already global (action: "unchanged"). skill carries the full post-transition SyncSkill so the client can update its local cache. On Idempotency-Key replay the same body is returned with Idempotent-Replayed: true.

action'published' | 'unchanged' required

Outcome of a publish call. published = visibility transitioned from private to global. unchanged = the skill was already global; no transition happened (idempotent retry).

Example response

{
  "skill": {
    "files": [
      {
        "contentType": "text/markdown"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.