---
title: "Update a skill"
method: PATCH
path: "/v2/skills/{skill_id}"
tags: ["Skills"]
---

# Update a skill

`PATCH /v2/skills/{skill_id}`

Updates mutable skill fields. Omitted optional fields keep their current values. Repeated fields such as `tags` replace the existing collection when provided.

## Path parameters

- `skill_id` string, required

## Request body

- UpdateSkillRequest
  - `display_name` string — New workspace-unique display name. Must start with a letter and may contain letters, numbers, dashes, and underscores. Dots are not allowed.
  - `description` string — New description. Omit to keep the current description.
  - `tags` string[] — Replacement tag list. Leave empty to clear tags.
  - `path` string — New project path. Omit to keep the current path.
  - `instructions` string — New instruction body. Omit to keep the current instructions.
  - `project_id` string — New containing project. Omit to keep the current project.

## Response `200`

OK

- UpdateSkillResponse
  - `skill` Skill, required
    - `skill_id` string, required — Unique skill identifier assigned by ORQ, for example `skill_01H...`. Use this value in retrieve, update, and delete requests.
    - `display_name` string, required — Workspace-unique display name. Must start with a letter and may contain letters, numbers, dashes, and underscores. Dots are not allowed.
    - `description` string, required — Short human-readable summary of what the skill is for.
    - `tags` string[], required — Free-form labels used for organization and filtering in clients.
    - `project_id` string, required — Project that owns or contains the skill.
    - `path` string, required — Project path where the skill is stored in the workspace.
    - `created_at` string, date-time, required — Time when the skill was created.
    - `updated_at` string, date-time, required — Time when the skill was last updated.
    - `created_by_id` string, required — User ID that created the skill.
    - `updated_by_id` string, required — User ID that last updated the skill.
    - `instructions` string, required — Instruction body executed or reused by clients that load this skill.
    - `version` string, required — Latest semver assigned by the activity log. Stamped on the document by CreateSkill / UpdateSkill so reads return it without joining workspaces.activities.

---

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