---
title: "Create workspace skill"
method: POST
path: "/api/workspace/skills"
---

# Create workspace skill

`POST /api/workspace/skills`

## Request

- Base URL: `https://app.base44.com`
- URL: `https://app.base44.com/api/workspace/skills`
- Auth: HTTP bearer

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Adds a skill to a workspace. The new skill is enabled, so the AI builder can use it right away.

The AI sees the name and description of every enabled skill in the workspace, and loads a skill's instructions when its description fits the task.

Skills belong to the workspace your credential is for. With a personal access token, that's the token's workspace, and there's no parameter to choose another one.

Skill names are unique within a workspace, so retrying a create that succeeded returns a `409`. A workspace has at most 100 skills, and creating another returns a `400`.

Skills need the Builder plan or higher. Below it, this returns a `403`.

This is limited to 60 requests per minute, shared with the other endpoints that change skills. A signed-in session has its own limit, and every personal access token for the workspace shares one. Some workspaces have a different limit.

<Note>Call this as an owner or admin of the workspace, with a personal access token sent as a Bearer token, or from a signed-in session. A read-only token is refused, and workspace API keys aren't accepted.</Note>

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time.</Warning>

## Request body

- CreateSkillRequest
  - `name` string, required: Name of the skill, up to 64 characters: lowercase letters and digits in words joined by single hyphens, such as `code-review`. Unique within the workspace.
  - `description` string, required: When the skill applies, up to 1024 characters. The AI reads it to decide when to load the skill, so say what the skill is for.
  - `body` string, required: The instructions the AI follows once it loads the skill, up to 50000 characters.

## Response `200`

The new skill.

- WorkspaceSkill
  - `id` string, required: ID of the skill.
  - `name` string, required: Name of the skill.
  - `description` string, required: When the skill applies.
  - `body` string, required: The instructions the AI follows once it loads the skill.
  - `enabled` boolean, required: Whether the AI can use the skill.
  - `created_by` string, required: Email of the member who created the skill.
  - `created_date` string, required: Time the skill was created, in UTC, as an ISO 8601 timestamp.
  - `updated_date` string, required: Time the skill last changed, in UTC, as an ISO 8601 timestamp.

## Other responses

- `400`: The workspace already has 100 skills.
- `401`: Missing or invalid credentials.
- `403`: The workspace's plan doesn't include skills, you aren't an owner or admin of the workspace, your token is read-only, or your credential can't be used on this endpoint.
- `409`: Another skill in the workspace already has this name, or your workspace requires an unlocked SSO session.
- `422`: Validation Error
- `429`: Rate limit exceeded.

## Changes

- **2026-10-15** `31b59ecae1c9`: 1 info
  - the `body` request property's maxLength was increased from `15000` to `50000`
- **2026-10-11** `80287813ab84`: 1 info
  - the endpoint scheme security `PersonalAccessTokenAuth` was added to the API
- **2026-10-10** `fc604cdcc3a2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/idealspot/apis/base44-app-management-api/changes/api/workspace/skills/post.md)

---

[API](https://skmtc.dev/idealspot/apis/base44-app-management-api.md) - [All operations](https://skmtc.dev/idealspot/apis/base44-app-management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/idealspot/apis/base44-app-management-api/revisions/b5b4ebd82a1e?raw)