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

# skill.upload

> Creates or updates a skill from a zip package uploaded with [file.upload](https://open.manus.ai/docs/v2/file.upload). `scope` and `project_id` choose whether the skill goes to the user's personal skills, the user's team, or a project; see [Target scope](https://open.manus.ai/docs/v2/skill.upload#target-scope). The package must not exceed 8 MiB and must contain a `SKILL.md` file with YAML front matter that sets `name`.

<sup>Questions or issues? Contact us at [api-support@manus.ai](mailto:api-support@manus.ai).</sup>

> [!TIP]
>
> **Auth:**
>
> * **API Key:** Full access.
> * **Standard OAuth client:** Not available. Returns `permission_denied` (HTTP 403) regardless of scopes.
> * **Trusted client:** Full access.
>
> Project uploads require the user to own the project or be a project member with edit permission.
>
> Team uploads require a Team account where the user is a Team Owner, Admin, or Super Admin. Individual users and regular team members receive `permission_denied`.

## Upload flow

1. Call [file.upload](https://open.manus.ai/docs/v2/file.upload.md) with the package's filename, then `PUT` the zip bytes to the returned `upload_url`.
2. After the `PUT` completes, call `skill.upload` with the returned `file.id`. Choose where the skill goes with `scope` and `project_id`; see [Target scope](#target-scope).
3. Use the returned `skill.id` in `message.enable_skills` or `message.force_skills` of [task.create](https://open.manus.ai/docs/v2/task.create.md) or [task.sendMessage](https://open.manus.ai/docs/v2/task.sendMessage.md).

The source file is not consumed. It still expires on the normal `file.upload` schedule, and deleting it does not affect the skill.

## Target scope

| `scope` | `project_id` | The skill is uploaded to |
| - | - | - |
| Omitted | Omitted | The user's personal skills. |
| Omitted | Set | The given project. |
| `personal` | Must be omitted | The user's personal skills. |
| `project` | Required | The given project. |
| `team` | Must be omitted | The skill library of the user's team. |

Other combinations return `400 invalid_argument`. `scope` values are lowercase and match `skill.owner_type` in the response. Requests without `scope` keep working as before.

A team upload always targets the team that the API Key's or token's user belongs to; there is no team ID parameter.

## Package requirements

| Requirement | Rule |
| - | - |
| Format | A zip archive. The file extension is not checked. |
| Package size | At most **8 MiB** (8,388,608 bytes). |
| Uncompressed size | All files together at most 32 MiB, as declared in the zip headers. |
| Contents | At least one file. Entry paths must be relative: they must not be absolute, start with a drive letter, start with `..`, or contain `/..`. |
| `SKILL.md` location | Named exactly `SKILL.md` (case-sensitive), at the archive root or one directory deep, such as `my-skill/SKILL.md`. If several files match, the first one in the archive is used. |
| `SKILL.md` front matter | The file must start with a YAML front matter block opened and closed by `---`. The first `---` after the opening line closes the block, so do not use `---` inside front matter values. |
| `name` | Required and non-empty, at most 128 characters. It identifies the skill within the target scope. |
| `description` | Optional. Longer values are truncated to 1,000 characters. Other front matter keys are ignored. |
| Skill count | A personal, team, or project scope holds up to 500 skills. Only creating a new skill counts against the limit; updating or restoring an existing skill does not. |

## Same-name uploads

The `name` in `SKILL.md` identifies the skill within the target scope: the user's personal skills, the team's skill library, or the skills of the given project.

| Existing skill with the same `name` | Result | `created` |
| - | - | - |
| None | Creates a new skill. | `true` |
| Exists, `overwrite` omitted or `false` | Returns `409 already_exists`. | — |
| Exists, `overwrite` is `true` | Uploads a new version. The skill keeps its ID. A byte-identical package changes nothing. | `false` |
| Previously deleted | Restores the skill with its original ID and the new package. | `false` |

## After upload

* A created or restored personal skill is enabled for the user. Updating an existing personal skill keeps the user's current enabled state.
* Every successful project upload adds the skill to the project's default skills, so it appears in `skill_ids` of [project.detail](https://open.manus.ai/docs/v2/project.detail.md). This also re-adds a skill that was removed from `skill_ids` with [project.update](https://open.manus.ai/docs/v2/project.update.md).
* A created or restored team skill is not added to team members' skill lists automatically, including the uploader's, and is not enabled by default. Members can add it from the team library in Manus, and team admins can change these defaults in Manus. Updating an existing team skill keeps its current team settings.
* Personal skills appear in [skill.list](https://open.manus.ai/docs/v2/skill.list.md). Pass `project_id` there to list project skills, or `scope=team` to list the team library.

## Errors

| Status | Cause |
| - | - |
| `400 invalid_argument` | `file_id` is missing, unknown, owned by another user, or not fully uploaded; `project_id` is empty; `scope` is not a supported value or does not match `project_id` (see [Target scope](#target-scope)); the file exceeds 8 MiB; or the package breaks a rule in [Package requirements](#package-requirements), except the cases under `500 internal`. The error message describes the failed check. |
| `403 permission_denied` | A standard OAuth client called the endpoint; the user can view the project but cannot edit it; or `scope` is `team` and the user is not in a team or is not a Team Owner, Admin, or Super Admin. |
| `404 not_found` | The project does not exist or the user is not a member. |
| `409 already_exists` | A skill with the same `name` exists in the target scope and `overwrite` is not `true`. |
| `429 resource_exhausted` | Creating the skill would exceed 500 skills in the target scope, or the `skill.upload` limit was exceeded; see [Rate Limits](https://open.manus.ai/docs/v2/rate-limits.md). Both cases use this code, so check `error.message`: retry with backoff only for the rate limit. |
| `500 internal` | The `name` in `SKILL.md` is longer than 128 characters, or `SKILL.md` cannot be read from the archive. These package problems currently return `500` instead of `400`; check them before uploading. |


## OpenAPI

````yaml POST /v2/skill.upload
openapi: 3.1.0
info:
  title: Manus OpenAPI v2
  description: >-
    API for integrating Manus into your workflow. All responses are wrapped with
    {"ok": true, "request_id": "...", ...} for success and {"ok": false,
    "request_id": "...", "error": {"code": "...", "message": "..."}} for errors.
  version: 2.0.0
servers:
  - url: https://api.manus.ai
security:
  - ApiKeyAuth: []
paths:
  /v2/skill.upload:
    post:
      summary: UploadSkill
      description: >-
        Creates or updates a skill from a zip package uploaded with
        [file.upload](https://open.manus.ai/docs/v2/file.upload). `scope` and
        `project_id` choose whether the skill goes to the user's personal
        skills, the user's team, or a project; see [Target
        scope](https://open.manus.ai/docs/v2/skill.upload#target-scope). The
        package must not exceed 8 MiB and must contain a `SKILL.md` file with
        YAML front matter that sets `name`.
      operationId: openapi.v2.OpenapiV2Service.UploadSkill
      parameters:
        - name: x-manus-api-key
          in: header
          required: false
          schema:
            type: string
          description: >-
            API key for direct authentication. Provide either this or
            `Authorization`, not both. See
            [Authentication](https://open.manus.ai/docs/v2/authentication).
        - name: Authorization
          in: header
          required: false
          schema:
            type: string
            example: Bearer {access_token}
          description: >-
            OAuth2 access token in `Bearer {token}` format. Only `Trusted team
            client` and `Trusted public client` apps can call this endpoint;
            standard OAuth clients receive `403 permission_denied` regardless of
            scopes. Provide either this or `x-manus-api-key`, not both. See the
            [Open App](https://open.manus.ai/docs/v2/open-app) guide.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                file_id:
                  type: string
                  minLength: 1
                  maxLength: 64
                  description: >-
                    ID of a file uploaded with
                    [file.upload](https://open.manus.ai/docs/v2/file.upload).
                    The file must belong to the user, have finished uploading,
                    and be a zip skill package of at most 8 MiB (8,388,608
                    bytes). The file is not consumed: it still expires on the
                    normal file schedule, and deleting it does not affect the
                    skill.
                scope:
                  type: string
                  enum:
                    - personal
                    - team
                    - project
                  description: >-
                    Where to upload the skill. Values match `owner_type` in the
                    response.


                    - `personal` — the user's personal skills. `project_id` must
                    be omitted.

                    - `team` — the skill library of the user's team. The user
                    must be a Team Owner, Admin, or Super Admin. `project_id`
                    must be omitted.

                    - `project` — the project given by `project_id`, which is
                    required.


                    When omitted, the skill goes to the project if `project_id`
                    is set, and to the user's personal skills otherwise.
                project_id:
                  type: string
                  minLength: 1
                  maxLength: 65
                  description: >-
                    Target project. Required when `scope` is `project`; when
                    `scope` is omitted, setting it uploads the skill to this
                    project instead of the user's personal skills. Must be
                    omitted when `scope` is `personal` or `team`. The user must
                    own the project or be a project member with edit permission.
                    Use
                    [project.list](https://open.manus.ai/docs/v2/project.list)
                    to get project IDs.
                overwrite:
                  type: boolean
                  default: false
                  description: >-
                    When a skill with the same `SKILL.md` `name` already exists
                    in the target scope, upload a new version of it instead of
                    returning `409 already_exists`. The skill keeps its ID.
                    Uploading a byte-identical package changes nothing.
              required:
                - file_id
      responses:
        '200':
          description: Skill uploaded successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                    description: Whether the request was successful.
                  request_id:
                    type: string
                    description: Unique identifier for this API request.
                  skill:
                    $ref: '#/components/schemas/Skill'
                    description: >-
                      The uploaded skill, in the same shape as
                      [skill.list](https://open.manus.ai/docs/v2/skill.list).
                      `owner_type` is `personal`, `team`, or `project`.
                  created:
                    type: boolean
                    description: >-
                      `true` only when a new skill was created. `false` when an
                      existing skill was updated, a previously deleted skill
                      with the same name was restored with its original ID, or
                      the package was identical to the current version.
        4XX:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security: []
components:
  schemas:
    Skill:
      type: object
      description: A skill that extends the agent's capabilities.
      properties:
        id:
          type: string
          description: >-
            Unique identifier for the skill. Use this in enable_skills or
            force_skills when creating tasks.
        name:
          type: string
          description: Display name of the skill.
        description:
          type: string
          description: What the skill does and when it's useful.
        owner_type:
          type: string
          enum:
            - personal
            - official
            - team
            - project
            - app
            - hub
            - device
            - unknown
          description: |-
            Who owns the skill.

            - `personal` — user-created skill.
            - `official` — built-in system skill.
            - `team` — team-shared skill.
            - `project` — project-specific skill.
            - `app` — private skill owned by an Open App.
            - `hub` — skill installed from Skill Hub.
            - `device` — skill discovered on the user's connected device.
            - `unknown` — ownership not recognized.

            Treat any unrecognized value as `unknown`; new values may be added.
        creator_info:
          type: object
          description: Information about who created the skill.
          properties:
            user_id:
              type: string
              description: User ID of the skill creator.
            name:
              type: string
              description: Display name of the skill creator.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (seconds) when the skill was created.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp (seconds) when the skill was last updated.
    ErrorResponse:
      type: object
      description: Standard error response format returned when a request fails.
      properties:
        ok:
          type: boolean
          example: false
          description: Always false for error responses.
        request_id:
          type: string
          description: >-
            Unique identifier for this API request, useful for debugging with
            support.
        error:
          type: object
          description: Error details.
          properties:
            code:
              type: string
              description: >-
                Machine-readable error code (e.g., "invalid_argument",
                "not_found", "permission_denied", "rate_limited").
            message:
              type: string
              description: Human-readable error description explaining what went wrong.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-manus-api-key

````

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