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

# Create Custom Skill

`POST /skills`

## Request

- Base URL: `https://api.myaltimate.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.myaltimate.com/skills`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

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

[Operation history](https://skmtc.dev/myaltimate/apis/myaltimate-api/changes/skills/post.md)

---

[API](https://skmtc.dev/myaltimate/apis/myaltimate-api.md) - [All operations](https://skmtc.dev/myaltimate/apis/myaltimate-api/llms.txt) - [OpenAPI document](https://skmtc.dev/myaltimate/apis/myaltimate-api/revisions/727657ce54e9?raw)