CreateSkill
Creates a skill.
Operation description
- Creation rules:
Namemust be unique within the current tenant and cannot be the same as an official skill.DescriptionandMetadataare required.Metadatamust 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. UseNameandDescriptionfor the name and description.transitId: Upload and confirm a ZIP file through Transit. The call sequence is as follows:Call
CreateTransitUploadPolicyand pass inFileShowNameto obtainTransitId,FilePath, andPolicyInfo.Use
PolicyInfoandFilePathto upload the ZIP file to Object Storage Service (OSS).Call
ConfirmTransitUploadand pass inTransitId. Proceed with creation only ifConfirmed=trueis returned.Call
CreateSkilland pass the confirmedTransitIdinMetadata.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
|
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 |
Metadata definition
| Name | Type | Description | Example |
skillMd | string | The 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. |
transitId | string | The transit ID of the ZIP bundle that has been uploaded and confirmed. This parameter is mutually exclusive with skillMd and bundleUrl. | transit_example123 |
bundleUrl | string | The 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
artifactIdis 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.