---
title: "Update System Skill"
method: PATCH
path: "/api/v1/internal/skills/{skill_id}"
tags: ["internal", "internal-skills"]
---

# Update System Skill

`PATCH /api/v1/internal/skills/{skill_id}`

Replace a curated skill's content, starter flag, and availability.

``workspace_ids`` and ``icp_category_ids`` set availability together:
clearing both makes it global, either one restricts it.

## Path parameters

- `skill_id` string, uuid, required

## Request body

- AdminSkillWriteRequest — Create or replace a MAIA-curated (``scope=system``) skill. ``workspace_ids`` and ``icp_category_ids`` together set availability on both create and update: both empty is a global skill (visible to every workspace); either one restricts it. ``is_starter`` is independent of availability. ``extra="forbid"`` rejects the retired scalar ``workspace_id`` field: a stale caller from before the multi-workspace cutover would otherwise have it silently dropped, defaulting ``workspace_ids`` to empty and publishing a workspace-scoped skill to every workspace. A 422 surfaces the stale call.
  - `name` string, required
  - `description` string, required
  - `body` string, required
  - `is_starter` boolean
  - `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.
  - `workspace_ids` string[]
  - `icp_category_ids` string[] — ICP categories this skill targets. Every workspace carrying one of these categories can see it, including workspaces assigned to the category after this write.

## Response `200`

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)