CreateSkill

Updated at:
Copy as MD

Creates a skill.

Operation description

  • Creation rules:
    • Name must be unique within the current tenant and cannot be the same as an official skill.

    • Description and Metadata are required. Metadata must contain one and only one valid content source. Different sources cannot be mixed.

    • After the skill is created, you can modify it by calling UpdateSkill.

  • Content sources:
    • skillMd: Directly enter the Markdown body. No YAML front matter is required. Use Name and Description for the name and description.

    • transitId: Upload and confirm a ZIP file through Transit. The call sequence is as follows:
      1. Call CreateTransitUploadPolicy and pass in FileShowName to obtain TransitId, FilePath, and PolicyInfo.

      2. Use PolicyInfo and FilePath to upload the ZIP file to Object Storage Service (OSS).

      3. Call ConfirmTransitUpload and pass in TransitId. Proceed with creation only if Confirmed=true is returned.

      4. Call CreateSkill and pass the confirmed TransitId in Metadata.transitId.

    • bundleUrl: Pass in a public HTTPS ZIP direct link. The platform downloads the file and saves it as an artifact. The original URL is not saved or echoed.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ada:CreateSkill

create

*All Resource

*

None None

Request parameters

Parameter

Type

Required

Description

Example

Name

string

Yes

The unique identifier of the skill. Only letters, digits, underscores, and hyphens are supported. The length cannot exceed 64 characters.

code-review

Description

string

Yes

The description of the skill.

A Skill for reviewing code quality, security risks, and coding standards.

Metadata

any

Yes

The metadata of the skill, in JSON object format. One and only one content source must be provided. For specific fields, refer to the supplementary description of request parameters.

{"skillMd":"# Code Review\nCheck code quality, security risks, and coding standards."}

Visibility

string

No

The visibility of the skill. Valid values: user and tenant. Default value: user.

user

Metadata definition

NameTypeDescriptionExample
skillMdstringThe non-empty Markdown body of the skill. You do not need to specify name and description in the YAML front matter. This parameter is mutually exclusive with transitId and bundleUrl.# Code Review\nCheck code quality, security risks, and coding standards.
transitIdstringThe transit ID of the ZIP bundle that has been uploaded and confirmed. This parameter is mutually exclusive with skillMd and bundleUrl.transit_example123
bundleUrlstringThe public HTTPS direct link to the ZIP file. This parameter is only applicable to CreateSkill and maps to Python body.metadata.bundleUrl. This parameter is mutually exclusive with transitId and skillMd. The URL is used only for the current download and is not persisted as an artifact reference. For limits, see the following section.https://example.com/skills/code-review.zip

bundleUrl limits

  • Only public direct links are allowed. The protocol must be HTTPS and the port must be 443. The URL cannot be a web page or a download page that requires redirection. Redirection is not followed. Even if the redirect target meets the HTTPS requirements, the redirection is not executed.

  • The maximum download size is 10 MiB (10,485,760 bytes). This is the URL download limit and does not change the quotas for other upload methods.

  • After the download succeeds, the file must still pass the existing ZIP bundle verification. After passing the verification, the original bytes of the ZIP file are transferred and stored, and the platform-managed artifactId is used subsequently.

Request examples

The following example uses an uploaded and confirmed Transit bundle:

{
  "Name": "code-review",
  "Description": "A skill used to check code quality, security risks, and coding standards",
  "Metadata": {
    "transitId": "transit_example123"
  },
  "Visibility": "user"
}

To create a skill by using a Markdown body or a public HTTPS direct link to a ZIP file, replace Metadata with one of the following objects:

{"skillMd": "# Code Review\nCheck code quality, security risks, and coding standards."}
{"bundleUrl": "https://example.com/skills/code-review.zip"}

Response elements

Element

Type

Description

Example

object

SkillId

string

The skill ID.

skill_example123

Name

string

The unique identifier of the skill.

code-review

UpdatedAt

integer

The update time after the skill is created. The value is a UNIX timestamp in milliseconds.

1760000100000

Success

boolean

Indicates whether the operation is successful. true is returned when the skill and its body or bundle are fully created and readable. Business failures are returned in error responses.

true

RequestId

string

The request ID, which is used to locate and troubleshoot the request.

0A1B2C3D-4E5F-6789-ABCD-EF0123456789

Sample success responses

{
  "SkillId": "skill_example123",
  "Name": "code-review",
  "UpdatedAt": 1760000100000,
  "Success": true,
  "RequestId": "0A1B2C3D-4E5F-6789-ABCD-EF0123456789"
}

Examples

Success response

JSON format

{
  "SkillId": "skill_example123",
  "Name": "code-review",
  "UpdatedAt": 1760000100000,
  "Success": true,
  "RequestId": "0A1B2C3D-4E5F-6789-ABCD-EF0123456789"
}

Error codes

HTTP status code

Error code

Error message

Description

400 InvalidParameter The specified parameter is invalid.
400 Skill.BundleUrlRejected The skill bundle URL was rejected.
400 Skill.BundleInvalid The specified skill bundle is invalid.
401 Unauthenticated Authentication required.
500 InternalError Internal server error.
413 Skill.BundleTooLarge The skill bundle exceeds the allowed size.
404 Skill.BundleSourceNotFound The specified skill bundle source was not found.
503 ServiceUnavailable The service is not ready or temporarily unavailable.
504 ServiceTimeout A required service timed out.
504 Skill.BundleDownloadTimeout Downloading the skill bundle timed out.
504 Skill.OperationResultUnknown The result of the skill operation is unknown.
409 Skill.AlreadyExists A skill with the same name already exists.
409 Skill.BundleQuotaExceeded The skill bundle storage quota would be exceeded.

See Error CodesError Codes for a complete list.

Release notes

See Release NotesRelease Notes for a complete list.