---
title: "Create a Skill"
method: POST
path: "/v1/context-interfaces/{interfaceId}/skills"
tags: ["Skills"]
---

# Create a Skill

`POST /v1/context-interfaces/{interfaceId}/skills`

**Pre-release Endpoint**
This endpoint is currently in beta and is subject to change.

Create a skill for the specified Context Interface. The `source` determines where the skill's content comes from.

## Request body

- CreateSkillRequest
  - `name` string, required — The machine name of the skill. Must be unique within the MCP server and must match the name declared in the frontmatter.
  - `display_name` string, required — The human-readable display name of the skill.
  - `description` string, required — A description of the skill.
  - `source` SkillSourcePayload, required
    - `type` 'raw', required — The skill content is supplied inline in the request body.
    - `config` RawSkillSourceConfigPayload, required
      - `contents` string, required — The raw SKILL.md content — a markdown document beginning with a YAML frontmatter block.
  - `labels` Labels, required — Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".

## Response `201`

A response to creating a skill.

- Skill
  - `id` string, uuid, required — The unique identifier for the skill.
  - `context_interface_id` string, uuid, required — The ID of the Context Interface this skill belongs to.
  - `name` string, required — The machine name of the skill.
  - `display_name` string, required — The human-readable display name of the skill.
  - `description` string, required — A description of the skill.
  - `frontmatter` SkillFrontmatter, required
    - `name` string, required — The machine name declared in the frontmatter.
    - `description` string, required — A description of the skill declared in the frontmatter.
    - `license` string — License name or reference to a bundled license file.
    - `compatibility` string — Compatibility information for the skill, indicating environment requirements such as intended product, system packages, and network access.
    - `metadata` object — Arbitrary key-value metadata for the skill.
    - `allowed_tools` string — Space-separated list of pre-approved tools the skill is permitted to use.
  - `labels` Labels, required — Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".
  - `source` SkillSource, required
    - `type` 'raw', required — The skill content was supplied inline when the skill was created or updated.
  - `status` 'pending' | 'valid' | 'invalid', required — The current validation status of the skill. `pending` means the content has not yet been read and validated.
  - `sync_status` SkillSyncStatus, required — The outcome of the most recent attempt to fetch the skill's content from its source.
    - `status` 'pending' | 'success' | 'failed', required — The state of the most recent synchronization attempt.
    - `timestamp` string, date-time, required — The time the synchronization reached this state.
    - `error_message` string, nullable — The reason the synchronization failed. `null` unless `status` is `failed`.
  - `validation_message` string, nullable, required — The reason the skill failed validation. `null` unless `status` is `invalid`.
  - `created_at` string, date-time, required — An ISO-8601 timestamp representation of entity creation date.
  - `updated_at` string, date-time, required — An ISO-8601 timestamp representation of entity update date.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict

## Changes

- **2026-09-30** `de79e1192f11` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/kong/apis/konnect-api-go-sdk/changes/v1/context-interfaces/:interfaceId/skills/post.md)

---

[API](https://skmtc.dev/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.dev/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc.dev/kong/apis/konnect-api-go-sdk/revisions/de79e1192f11?raw)