> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create workspace skill

> 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 or a workspace API key, that's its 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, and each workspace API key has its own. 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, with a workspace API key, which acts as the workspace owner, or from a signed-in session. Read-only tokens and keys are refused.</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>



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/workspace/skills
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - PersonalAccessTokenAuth: []
paths:
  /api/workspace/skills:
    post:
      summary: Create workspace skill
      description: >-
        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 or a workspace API key, that's its 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, and each
        workspace API key has its own. 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, with a workspace API key, which
        acts as the workspace owner, or from a signed-in session. Read-only
        tokens and keys are refused.</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>
      operationId: create_workspace_skill_api_workspace_skills_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSkillRequest'
        required: true
      responses:
        '200':
          description: The new skill.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceSkill'
        '400':
          description: The workspace already has 100 skills.
        '401':
          description: Missing or invalid credentials.
        '403':
          description: >-
            The workspace's plan doesn't include skills, you aren't an owner or
            admin of the workspace, or your token or key is read-only.
        '409':
          description: >-
            Another skill in the workspace already has this name, or your
            workspace requires an unlocked SSO session.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded.
        '503':
          description: >-
            Database temporarily unavailable (`database_unavailable`): the data
            cluster did not answer in time. Retry after the `Retry-After`
            seconds.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
              examples:
                database_unavailable:
                  summary: database_unavailable
                  value:
                    error:
                      code: database_unavailable
                      message: Database temporarily unavailable, please retry
                      details: {}
      security:
        - PersonalAccessTokenAuth:
            - full_access
        - WorkspaceApiKeyAuth:
            - full_access
        - WorkspaceApiKeyBearerAuth:
            - full_access
components:
  schemas:
    CreateSkillRequest:
      properties:
        name:
          type: string
          maxLength: 64
          minLength: 1
          title: Name
          description: >-
            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.
          example: brand-voice
        description:
          type: string
          maxLength: 1024
          minLength: 1
          title: Description
          description: >-
            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.
          example: Use when writing any user-facing copy for our apps.
        body:
          type: string
          maxLength: 50000
          minLength: 1
          title: Body
          description: >-
            The instructions the AI follows once it loads the skill, up to 50000
            characters.
          example: >-
            Write in a warm, plain-spoken voice. Use sentence case for headings
            and keep buttons to two words.
      type: object
      required:
        - name
        - description
        - body
      title: CreateSkillRequest
    WorkspaceSkill:
      properties:
        id:
          type: string
          title: Id
          description: ID of the skill.
          example: 68d2a1f4c9e7b3001f2a5c88
        name:
          type: string
          title: Name
          description: Name of the skill.
          example: brand-voice
        description:
          type: string
          title: Description
          description: When the skill applies.
          example: Use when writing any user-facing copy for our apps.
        body:
          type: string
          title: Body
          description: The instructions the AI follows once it loads the skill.
          example: >-
            Write in a warm, plain-spoken voice. Use sentence case for headings
            and keep buttons to two words.
        enabled:
          type: boolean
          title: Enabled
          description: Whether the AI can use the skill.
          example: true
        created_by:
          type: string
          title: Created By
          description: Email of the member who created the skill.
          example: dana@acme.com
        created_date:
          type: string
          title: Created Date
          description: Time the skill was created, in UTC, as an ISO 8601 timestamp.
          example: '2026-08-01T09:15:00.123000Z'
        updated_date:
          type: string
          title: Updated Date
          description: Time the skill last changed, in UTC, as an ISO 8601 timestamp.
          example: '2026-08-03T14:02:10.456000Z'
      type: object
      required:
        - id
        - name
        - description
        - body
        - enabled
        - created_by
        - created_date
        - updated_date
      title: WorkspaceSkill
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    StandardErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
          description: What went wrong.
      type: object
      required:
        - error
      title: StandardErrorEnvelope
      description: The error body returned in the standard envelope.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    StandardError:
      properties:
        code:
          type: string
          title: Code
          description: >-
            Stable machine-readable cause of the failure. Match on this, not on
            `message`.
          example: not_found
        message:
          type: string
          title: Message
          description: Human-readable explanation. It isn't a stable contract.
          example: App not found
        details:
          additionalProperties: true
          type: object
          title: Details
          description: >-
            Structured context for the failure, or an empty object when there's
            none.
          example: {}
      type: object
      required:
        - code
        - message
      title: StandardError
  securitySchemes:
    PersonalAccessTokenAuth:
      type: http
      scheme: bearer
      description: >-
        Personal access token, sent as `Authorization: Bearer <token>`. Each
        operation lists the permission it needs: `read_only` or `full_access`. A
        full-access token can call every operation. A read-only token can call
        only the operations that list `read_only`; anything else returns 403
        `read_only_credential_route_not_allowed`.
    WorkspaceApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: >-
        Workspace API key, sent as `api_key: <key>`. Each operation that accepts
        one lists what the key needs: a permission, `read_only` or
        `full_access`, like a personal access token, or a scope. A key without
        the scope gets 403 `workspace_api_key_scope_required`.
    WorkspaceApiKeyBearerAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace API key, sent as `Authorization: Bearer <key>`. Accepted
        wherever `api_key` is, with the same permission.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.