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

# Create skill

`POST /skills`

Upload a skill package and create a new skill. The package must include a `SKILL.md` with `name` and `description` frontmatter; uploads may be a single `.md` file (stored as `SKILL.md`), or a `.zip` / `.skill` archive containing `SKILL.md` at its root. The initial version is created automatically. Maximum upload size is 10 MB.

## Response `201`

Skill created.

- object
  - `skill` object
    - `id` string — Unique skill identifier.
    - `name` string
    - `description` string
    - `team_id` string — ID of the team that owns the skill.
    - `created_at` string, date-time, nullable — ISO 8601 timestamp of when the skill was created.
    - `updated_at` string, date-time, nullable — ISO 8601 timestamp of when the skill was last updated.
    - `metadata` object — User-defined metadata. May include `related_server_ids` (array of MCP server IDs the skill references).
    - `usage_count` integer, nullable
    - `view_count` integer, nullable
    - `last_used_at` string, date-time, nullable
    - `version_id` string, nullable — ID of the version exposed by this payload (the current draft, by default).
    - `major_version` integer, nullable
    - `is_deployed` boolean, nullable
    - `version_created_at` string, date-time, nullable
    - `creator` object, nullable — Creator of the skill. `null` when no creator is recorded.
      - `id` string, nullable
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `email` string, nullable
      - `profile_picture` string, nullable

## Other responses

- `400` — Bad request — missing or invalid `SKILL.md`, unsafe archive, or malformed metadata.
- `401` — Unauthorized — missing or invalid API key.
- `403` — Forbidden — the caller cannot create skills on the requested team.
- `413` — Upload too large — request body exceeded 10 MB.
- `500` — Internal server error.

---

[API](https://skmtc.dev/gumloop/apis/public-api.md) · [All operations](https://skmtc.dev/gumloop/apis/public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gumloop/public-api/revisions/115f2d6ce387/schema)