Creating an Enterprise-developed Skill_Skills Management_Workspace APIs_API Reference

Function

This API is used to create an enterprise-developed skill and upload the skill package.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies

workspace:skill:create

Write

-

-

-

-

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
workspace:skill:create	Write	-	-	-	-

URI

POST /v3/ai-agents/skills

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
X-Language	No	String	Language, which is used for internationalization. en-us: English. zh-cn: Chinese.
X-Client-Token	No	String	Idempotency key, in UUID format. Creation APIs carry this request header, and the server implements idempotence control based on this header. The response header returns the same value.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
slug	Yes	String	Skill slug, which cannot be changed after being created.
display_name	Yes	String	Skill name.
alias_name	No	String	Alias (name that can be changed on the service page).
description	No	String	Skill description.
category	Yes	String	Skill category.
tags	No	Array of strings	Skill tag.
cover	No	String	Base64-encoded cover image.
source	No	String	Skill source. The default value is CUSTOM.
support_os_types	No	Array of strings	List of supported OS types.
packages	No	Array of CreateSkillPackage objects	Skill package information list.

**Table 3** CreateSkillPackage
Parameter	Mandatory	Type	Description
version	Yes	String	Version.
package_name	Yes	String	Name of the skill package file (the same as the value of packageName in getUploadUrls). The server constructs the OBS path based on the value.
package_hash	Yes	String	SHA-256 hash value of the skill package (calculated before the frontend uploads the package).
package_size	Yes	Long	Skill package size, in bytes. The maximum value is 104857600.
regions	Yes	Array of PackageRegionWithStatusInfo objects	OBS storage region information (including the upload status).

**Table 4** PackageRegionWithStatusInfo
Parameter	Mandatory	Type	Description
region	Yes	String	Region ID (for example, cn-north-7).
upload_status	Yes	String	Upload status.

Response Parameters

Status code: 201

**Table 5** Response header parameters
Parameter	Type	Description
X-Request-Id	String	-

**Table 6** Response body parameters
Parameter	Type	Description
id	String	Skill ID.
slug	String	Skill slug.
display_name	String	Skill name.
alias_name	String	Alias.
description	String	Skill description.
category	String	Skill category.
tags	Array of strings	Skill tag.
owner_type	String	Skill owner type.
visibility_scope	String	Visibility scope.
visible_domain_ids	Array of strings	IDs of tenants in the visibility scope. This parameter is returned only when visibility_scope is set to SPECIFIC_TENANTS.
status	String	Skill status.
current_package_id	String	ID of the skill package that is currently in effect.
cover	String	Base64-encoded skill cover image.
source	String	Skill source.
support_os_types	Array of strings	List of supported OS types.
packages	Array of SkillPackageSummary objects	Skill package summary list.
create_time	String	Creation time (UTC time in ISO 8601 format).
update_time	String	Update time (UTC time in ISO 8601 format).
attach_instance_number	Integer	Number of bound instances.

**Table 7** SkillPackageSummary
Parameter	Type	Description
id	String	Skill package ID.
version	String	Version.
revision	Integer	Version revision number.
package_status	String	Skill package status.
regions	Array of strings	Deployed region IDs.

Status code: 400

**Table 8** Response header parameters
Parameter	Type	Description
X-Request-Id	String	-

**Table 9** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Status code: 401

**Table 10** Response header parameters
Parameter	Type	Description
X-Request-Id	String	-

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Status code: 403

**Table 12** Response header parameters
Parameter	Type	Description
X-Request-Id	String	-

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Status code: 500

**Table 14** Response header parameters
Parameter	Type	Description
X-Request-Id	String	-

**Table 15** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Example Requests

/v3/ai-agents/skills

{
  "slug" : "internal-doc-helper",
  "display_name" : "Doc Helper",
  "alias_name" : "Doc Helper",
  "description" : "Enterprise internal document processing skill",
  "category" : "DOC_KNOWLEDGE",
  "tags" : [ "document", "knowledge" ],
  "cover" : "data:image/png;base64,iVBOR...",
  "source" : "CUSTOM",
  "support_os_types" : [ "Windows", "Linux" ],
  "packages" : [ {
    "version" : "1.0.0",
    "package_name" : "internal-doc-helper-1.0.0.zip",
    "package_hash" : "sha256-abc123...",
    "package_size" : 52428800,
    "regions" : [ {
      "region" : "cn-north-7",
      "upload_status" : "UPLOADED"
    } ]
  } ]
}

Example Responses

Status code: 201

{
  "id" : "skill-uuid-002",
  "slug" : "internal-doc-helper",
  "display_name" : "Doc Helper",
  "alias_name" : "Doc Helper",
  "description" : "Enterprise internal document processing skill",
  "category" : "DOC_KNOWLEDGE",
  "tags" : [ "document", "knowledge" ],
  "owner_type" : "TENANT",
  "visibility_scope" : "OWNER_ONLY",
  "status" : "ACTIVE",
  "current_package_id" : "pkg-uuid-010",
  "cover" : "data:image/png;base64,iVBOR...",
  "source" : "CUSTOM",
  "support_os_types" : [ "Windows", "Linux" ],
  "packages" : [ {
    "id" : "pkg-uuid-010",
    "version" : "1.0.0",
    "revision" : 1,
    "package_status" : "PUBLISHED",
    "regions" : [ "cn-north-7" ]
  } ],
  "create_time" : "2026-05-13T08:00:00Z",
  "update_time" : "2026-05-13T08:00:00Z",
  "attach_instance_number" : 0
}

Status Codes

Status Code	Description
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
500	Internal Server Error

Error Codes

See Error Codes.

Creating an Enterprise-developed Skill