---
title: "Create Skill"
method: POST
path: "/v1/skills/create"
tags: ["skills"]
---

# Create Skill

`POST /v1/skills/create`

## Request

- Base URL: `https://api.vlm.run` (the document declares no server; this is the origin it was published from)
- URL: `https://api.vlm.run/v1/skills/create`
- Auth: HTTP bearer

Create a skill from a file, prompt, or chat session.

Three creation modes (provide exactly one source):
A. file_id: Use an already-uploaded skill zip (must contain SKILL.md).
B. prompt (+ optional json_schema): Auto-generate SKILL.md and schema.json, package and upload.
C. session_id: Retrieve chat history as the prompt, auto-generate SKILL.md.

All modes produce a skill zip stored in GCS and deduplicate by content hash.

## Request body

- SkillCreateRequest: Request to create a skill. Three creation modes (provide exactly one): A. file_id: Create from a pre-built skill zip uploaded via POST /v1/files. B. prompt (+ optional json_schema): Auto-generate SKILL.md and schema.json. C. session_id: Retrieve chat history and auto-generate SKILL.md from messages. For mode A (file_id), name and description are required. For modes B (prompt) and C (session_id), name and description are optional — if omitted, they are auto-generated by the LLM from the content.
  - `name` string, nullable: Name of the skill (required for file_id, auto-generated for prompt/session_id)
  - `description` string, nullable: Description of the skill (required for file_id, auto-generated for prompt/session_id)
  - `file_id` string, nullable: File ID from file upload API (the uploaded skill zip)
  - `prompt` string, nullable: Prompt text that becomes the SKILL.md body (auto-generates skill zip)
  - `json_schema` object, nullable: JSON schema that becomes schema.json in the skill zip
  - `session_id` string, nullable: Chat session ID to retrieve chat history as the prompt
  - `is_public` boolean: Whether the skill is publicly accessible

## Response `201`

Successful Response

- SkillCreateResponse: Response for skill creation.
  - `id` string, required: ID of the created skill
  - `name` string, required: Name of the skill (may differ from request if LLM-generated)
  - `description` string, required: Description of the skill (may differ from request if LLM-generated)
  - `skill_version` string, required: Auto-generated version of the skill (e.g. '20260512-abc12345')
  - `status` string: Status of the skill creation
  - `created_at` string, date-time, required: Date and time when the skill was created
  - `updated_at` string, date-time, required: Date and time when the skill was updated

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/vlm/apis/vlm-run-unified-server.md) · [All operations](https://skmtc.dev/vlm/apis/vlm-run-unified-server/llms.txt) · [OpenAPI document](https://skmtc.dev/vlm/apis/vlm-run-unified-server/revisions/4a68ab36546b?raw)