---
title: "Publish a skill to the hosted registry"
method: POST
path: "/v1/skills"
tags: ["public", "registry"]
---

# Publish a skill to the hosted registry

`POST /v1/skills`

## Request

- Base URL: `https://api.runx.ai`
- URL: `https://api.runx.ai/v1/skills`
- Auth: HTTP bearer

Publishes one governed skill markdown document under the signed-in principal's verified namespace. The caller cannot set owner or trust tier.

## Request body

- HostedSkillPublishRequest
  - `markdown` string, required: Complete SKILL.md document, including frontmatter.
  - `profile_document` string: Optional run.yaml profile document published with the skill.
  - `version` string: Optional version or content ref. If omitted, the registry derives one from content.
  - `publisher` string: The namespace to publish for, required when the principal may publish for several; it must be one it is authorized for.
  - `package_files` HostedSkillPackageFile[]: Optional UTF-8 skill package files persisted with the registry version and used by hosted publish admission to rerun the package harness. Allowed paths are root worker modules referenced by run.yaml, nested SKILL.md/run.yaml packages, references markdown, and tool manifests/minimal runtimes.
    - `path` string, required: Relative allowlisted package path. Root SKILL.md and run.yaml use their dedicated fields.
    - `content` string, required: UTF-8 file content.

## Response `200`

Published hosted skill.

- HostedSkillPublishEnvelope
  - `status` 'success', required
  - `publish` HostedSkillPublishResult, required
    - `status` 'published' | 'unchanged', required
    - `skill_id` string, required
    - `owner` string, required
    - `name` string, required
    - `version` string, required
    - `digest` string, required
    - `profile_digest` string
    - `paid_listing` RunxPaidSkillListing
      - `offers` object, required
      - `package_digest` string, required
      - `profile_digest` string, required
      - `skill_digest` string, required
      - `skill_id` string, required
      - `vendor_ref` object, required
        - `label` string
        - `locator` string
        - `observed_at` string
        - `proof_kind` 'effect_evidence' | 'effect_finality' | 'credential_resolution'
        - `provider` string
        - `type` 'principal', required
        - `uri` string, required
      - `version` string, required
    - `trust_tier` 'community', required
    - `maturity` 'alpha' | 'beta' | 'stable', required
    - `install_command` CopyableCommand, required
      - `shell` 'posix', required
      - `argv` string[], required
      - `copy_text` string, required
    - `run_command` CopyableCommand, required
      - `shell` 'posix', required
      - `argv` string[], required
      - `copy_text` string, required
    - `public_url` string, uri, required
    - `harness` HarnessPublishSummary
      - `status` 'passed' | 'failed' | 'not_declared', required
      - `case_count` integer, required
      - `assertion_error_count` integer, required
      - `assertion_errors` string[], required
      - `case_names` string[], required
      - `receipt_ids` string[], required
      - `graph_case_count` integer
      - `evidence_id` string
      - `evidence_url` string, uri

## Other responses

- `400`: Invalid skill package.
- `401`: Unauthorized.
- `403`: Missing publish scope.
- `409`: Skill version conflict.
- `503`: Hosted registry unavailable.

---

[API](https://skmtc.dev/runx/apis/runx-hosted-api.md) · [All operations](https://skmtc.dev/runx/apis/runx-hosted-api/llms.txt) · [OpenAPI document](https://skmtc.dev/runx/apis/runx-hosted-api/revisions/6c940d8edacc?raw)