---
title: "Create Custom Skill"
method: POST
path: "/skills"
tags: ["SKILLS"]
---

# Create Custom Skill

`POST /skills`

Upload a skill bundle and create its metadata row.

The bundle is validated and uploaded before the row is committed, so a
committed skill never points at an empty prefix.

## Request body

- CreateCustomSkillRequest — Upload a new skill bundle.
  - `name` string, required
  - `description` string, nullable
  - `files` CustomSkillFile[], required
    - `path` string, required
    - `content` string, required
  - `privacy` 'public' | 'private'

## Response `201`

Successful Response

- CustomSkillResponse
  - `skill` CustomSkillDetail, required — A skill plus its ``SKILL.md`` body, read from S3 on the detail view. The full ``files`` inventory lives here rather than on the summary: this is the only view that renders paths and sizes.
    - `public_id` string, required
    - `name` string, required
    - `description` string, nullable
    - `privacy` 'public' | 'private'
    - `file_count` integer
    - `source_ref` SkillSourceRef — Where an imported skill was copied from. Present only on skills imported from the public catalog; ``None`` means the skill was uploaded or written by hand. Carried on the list payload so the Skills table can attribute a row to its upstream origin without a second request, and so a renamed copy can still be traced back.
      - `repo` string, required
      - `path` string, required
      - `commit_sha` string, required
      - `imported_at` string, nullable
    - `created_by` integer, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `files` CustomSkillFileMeta[]
      - `path` string, required
      - `size` integer, required
    - `content` string, required
    - `attached_datamate_ids` integer[]

## Other responses

- `400` — Invalid skill bundle
- `404` — Workspace not found
- `409` — Skill name already in use
- `422` — Validation Error

## Changes

- **2026-09-02** `fcb62c79da95` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/myaltimate/apis/fastapi/changes/skills/post.md)

---

[API](https://skmtc.dev/myaltimate/apis/fastapi.md) · [All operations](https://skmtc.dev/myaltimate/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/myaltimate/fastapi/revisions/fcb62c79da95/schema)