GetSkill

Updated at:
Copy as MD

Queries the skills visible to the current caller by name.

Operation description

  • Query target:
    • Queries by Name. Querying by SkillId is not supported.

    • Prioritizes returning skills with the same name that are visible to the caller under the current tenant. If no visible records are found, it queries official skills with the same name.

    • If SkillVersion is omitted, the current skill is returned. This parameter is omitted by default.

  • Download URL:
    • Network supports public and internal. If omitted, no download URL is generated.

    • If the skill has an accessible artifact, a temporary DownloadUrl and the corresponding DownloadUrlNetwork are returned.

    • If the artifact does not exist, access is denied, or URL generation fails, the skill query still succeeds, but the download URL-related fields may not be returned.

    • The original bundleUrl used during creation is not saved and will not be echoed back through this API.

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:GetSkill

get

*All Resource

*

None None

Request parameters

Parameter

Type

Required

Description

Example

Name

string

Yes

The name of the skill.

code-review

SkillVersion

integer

No

Specifies the published historical version number to query. If omitted, the current primary record of the skill is returned.

2

Network

string

No

The network type of the download URL. Valid values: public and internal. If omitted, no download URL is generated.

public

  • Name is a required parameter and specifies the name of the skill to query.

  • If SkillVersion is omitted, the current primary record of the skill is returned. If this parameter is specified, the corresponding published historical version is returned.

  • To generate a bundle download URL, set Network to public or internal. If this parameter is omitted, no download URL is generated.

  • Network only controls the generation of the download URL. If the artifact does not exist, access is denied, or URL generation fails, the skill query still succeeds, but the download URL-related fields may not be returned.

Request example

{
  "Name": "code-review",
  "SkillVersion": 2,
  "Network": "public"
}

Response elements

Element

Type

Description

Example

object

The skill information returned by the GetSkill API.

SkillId

string

The skill ID.

skill_example123

Name

string

The name of the skill.

code-review

Description

string

The description in the current primary record of the skill.

A skill for performing code review and risk alerts

Visibility

string

The visibility of the current skill. Common values are user and tenant.

user

Status

string

The current status of the skill. Common values are DRAFT and PUBLISHED.

PUBLISHED

CreatedAt

integer

The creation time of the skill. The value is a UNIX timestamp in milliseconds.

1760000000000

UpdatedAt

integer

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

1760000300000

Metadata

any

The metadata of the skill, which is mapped to the metadata field in the backend response.

{"skillMd":"# Code Review\nCheck code quality.","artifactId":"artifact_example003"}

DownloadUrl

string

The download URL of the bundle. This field is returned when the network is specified, an accessible artifact exists, and presigning is successful.

https://example.com/artifacts/code-review-v2.zip?signature=example

DownloadUrlNetwork

string

The network type actually used to generate the download URL.

public

CanModify

boolean

Indicates whether the current caller can modify the skill.

true

Official

boolean

Indicates whether the skill is an official skill.

false

CanDelete

boolean

Indicates whether the current caller can delete the skill.

true

IconUrl

string

The URL of the skill icon, which is derived from the iconUrl in the metadata. This field may be empty if no icon is configured.

https://example.com/icons/code-review.png

RequestId

string

The request ID, which is used for Tracing Analysis and troubleshooting.

0A1B2C3D-4E5F-6789-ABCD-EF0123456789

Metadata definition

NameTypeDescriptionExample
skillMdstringThe inline body of SKILL.md, excluding the YAML front matter.# Code Review\nCheck code quality and security risks.
artifactIdstringThe ID of the artifact currently associated with the skill, which is used to read or generate the bundle download URL.artifact_example003

Sample success response

{
  "SkillId": "skill_example123",
  "Name": "code-review",
  "Description": "A skill for performing code review and risk alerts",
  "Visibility": "user",
  "Status": "PUBLISHED",
  "CreatedAt": 1760000000000,
  "UpdatedAt": 1760000300000,
  "Metadata": {
    "skillMd": "# Code Review\nCheck code quality and security risks.",
    "artifactId": "artifact_example003"
  },
  "DownloadUrl": "https://example.com/artifacts/code-review-v2.zip?signature=example",
  "DownloadUrlNetwork": "public",
  "CanModify": true,
  "Official": false,
  "CanDelete": true,
  "RequestId": "0A1B2C3D-4E5F-6789-ABCD-EF0123456789"
}

Examples

Success response

JSON format

{
  "SkillId": "skill_example123",
  "Name": "code-review",
  "Description": "A skill for code review and risk alerting",
  "Visibility": "user",
  "Status": "PUBLISHED",
  "CreatedAt": 1760000000000,
  "UpdatedAt": 1760000300000,
  "Metadata": "{\"skillMd\":\"# Code Review\\nCheck code quality.\",\"artifactId\":\"artifact_example003\"}",
  "DownloadUrl": "https://example.com/artifacts/code-review-v2.zip?signature=example",
  "DownloadUrlNetwork": "public",
  "CanModify": true,
  "Official": false,
  "CanDelete": true,
  "IconUrl": "https://example.com/icons/code-review.png",
  "RequestId": "0A1B2C3D-4E5F-6789-ABCD-EF0123456789"
}

Error codes

HTTP status code

Error code

Error message

Description

400 InvalidParameter The specified parameter is invalid.
401 Unauthenticated Authentication required.
500 InternalError Internal server error.
404 Skill.ResourceNotFound The specified skill was not found.
404 Skill.VersionNotFound The specified skill version was not found.
503 ServiceUnavailable The service is not ready or temporarily unavailable.
504 ServiceTimeout A required service timed out.

See Error CodesError Codes for a complete list.

Release notes

See Release NotesRelease Notes for a complete list.