---
title: "Create a new skill"
method: POST
path: "/v2/skills"
tags: ["Skills"]
---

# Create a new skill

`POST /v2/skills`

Creates a reusable skill in the workspace. Skills store instructions, metadata, and an optional project location so teams can standardize repeatable AI workflows.

## Request body

- union
  - object
    - `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 — Short human-readable summary of what the skill is for.
    - `tags` string[] — Free-form labels for organizing the skill.
    - `path` string, required — Project path where the skill should be stored.
    - `project_id` string — Project that should contain the skill.
    - `instructions` string — Instruction body for the skill. Omit to create metadata first and fill instructions later.
  - object
    - `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 — Short human-readable summary of what the skill is for.
    - `tags` string[] — Free-form labels for organizing the skill.
    - `path` string — Project path where the skill should be stored.
    - `project_id` string, required — Project that should contain the skill.
    - `instructions` string — Instruction body for the skill. Omit to create metadata first and fill instructions later.

## Response `200`

OK

- CreateSkillResponse
  - `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)