---
title: "Promote Skill"
method: POST
path: "/api/v1/internal/skills/{skill_id}/promote"
tags: ["internal", "internal-skills"]
---

# Promote Skill

`POST /api/v1/internal/skills/{skill_id}/promote`

Promote an internal-authored user/workspace skill into the system catalog.

Copies the source (which stays intact) into a new owner-less system skill
with the given curation controls. Sources outside internal workspaces /
internal authors are rejected (403); a name collision is a 409 the caller
resolves by re-submitting with a ``name`` override.

## Path parameters

- `skill_id` string, uuid, required

## Request body

- AdminSkillPromoteRequest — Promote an internal-authored user/workspace skill into the system catalog. The source skill's description, body, and type are copied as-is; ``name`` overrides the source's name (rename on collision), else the source name is kept. ``is_starter``, ``workspace_ids``, and ``icp_category_ids`` are the same curation controls as ``AdminSkillWriteRequest`` — promotion never inherits them from the source, since they only mean something at system scope.
  - `name` string, nullable
  - `is_starter` boolean
  - `workspace_ids` string[]
  - `icp_category_ids` string[]

## Response `201`

Successful Response

- AdminSkillResponse — A curated skill as returned to the internal admin catalog. Adds the ``workspace_ids`` availability set, which the public ``SkillResponse`` deliberately omits: for a skill restricted to a set of workspaces, that set contains *other* tenants' workspace ids, so exposing it on the public read paths (picker / gallery) would leak cross-tenant data to any workspace the skill is visible in. Only the internal admin surface (``require_internal``) sees the availability set.
  - `id` string, uuid, required
  - `scope` 'user' | 'workspace' | 'system', required — Tier a skill applies to. Unlike knowledge entries, skills add a ``system`` scope: globally-available skills that are read-only through the public service/API and writable only via the internal admin override, plus the in-code create-skill playbook registry. ``user`` skills are owned by a single user, ``workspace`` skills by a workspace, ``system`` skills by neither.
  - `user_id` string, uuid, nullable
  - `workspace_id` string, uuid, nullable
  - `name` string, required
  - `description` string, required
  - `body` string, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `is_starter` boolean — Whether this skill surfaces as a first-run starter in the new-project gallery. System (Ready-made by MAIA) and workspace-scoped skills may be starters; user-scoped skills are never starters.
  - `skill_type` 'workflow' | 'enrichment' | 'agent_column' — What kind of work a skill encodes (MAIA-2976). ``workflow`` skills run end-to-end from a blank project (the IOS skill) and are the only kind that defaults into the new-project starter gallery; ``enrichment`` skills produce a derived configuration/value (usable IOS acreage) and ``agent_column`` skills build a single agent-derived column (owner assemblages) against an existing project's data.
  - `supersedes_skill_id` string, uuid, nullable — If set, the MAIA/workspace starter this skill was customized from; that original is hidden from this caller's starter gallery and the agent's routing catalog in favor of this skill.
  - `workspace_ids` string[] — The workspaces this curated (system) skill is explicitly available in. Global means this AND icp_category_ids are both empty.
  - `icp_category_ids` string[] — The ICP categories this curated (system) skill targets. Any workspace carrying one of them can see it.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.net/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/maia-analytics/maia-api/versions/ba2b8d962161/schema)