Skill management APIs

How it works

A skill is uniquely identified by its Name, which cannot be changed after creation. The name can contain only lowercase letters, digits, underscores, and hyphens, must start with a letter, and cannot exceed 64 characters. anthropic and claude are reserved words.

The execution content of a skill is carried by its Definition, where the SKILL.md body serves as the working instructions that the agent follows during execution. The name and description determine when the agent invokes the skill, while the body specifies how to perform the task.

Write operations are consistent with agent APIs. UpdateSkill supports passing ExpectedVersion for version verification, and each successful modification generates a new version. The response is an operation receipt containing SkillId, Name, and the modification time. To retrieve the full content, you need to read the skill back.

Usage notes

API calls take effect within the tenant and region associated with the calling identity. Platform built-in skills with a Scope value of SYSTEM are read-only and cannot be modified or deleted.

Ownership is determined at creation and cannot be changed afterward. When the value is USER, the skill is visible only to you. When the value is TENANT, the skill is visible to all members within the tenant.

Skill packages that contain scripts and assets are uploaded as zip files through the console. For more information, see skill development and MCP integration. The APIs manage the metadata and body content of skills.

Query the skill list

The list API is used to compare skill inventories across environments. Filter parameters determine whether the comparison scope is complete.

1. Call ListSkills and use PageNumber and PageSize for pagination. For a full synchronization, iterate through pages until the number of returned results is less than the page size.

2. Use Scope to distinguish the source. When comparing custom skills, always pass CUSTOM to avoid counting built-in skills as differences.

3. Use Visibility to filter by ownership, use Q for keyword matching against names and descriptions, and use CreatorId to filter by creator.

4. To retrieve the full body of a specific skill, call GetSkill. The list returns only summary information, and the body content is available only through a single-object read.

Create a skill

Once a skill is mounted to an agent, it participates in actual execution. The accuracy of the description is as important as the executability of the body.

1. Determine the Name. Follow the naming rules and use a stable, environment-independent identifier. This column cannot be changed after creation.

2. Specify the Description to explain what the skill does and when it should be used. The agent decides whether to invoke the skill based on this description. A vague description leads to incorrect or missed invocations.

3. Construct the Definition and write the SKILL.md body. Organize the execution workflow in steps, declare input requirements and output formats for each step, and specify scenarios where the skill is not applicable.

4. Set Visibility. For skills shared across the team, pass TENANT. For skills used only for personal validation, pass USER or omit the parameter.

5. Call CreateSkill to submit the skill, and then call GetSkill to read it back and verify that the body content is complete and not truncated.

Modify a skill and publish a new version

Modifications immediately affect all agents and scheduled tasks that have the skill mounted. Determine the impact scope before making changes, and verify the changes before releasing them for general use.

1. Call GetSkill to retrieve the current content and version number.

2. Modify the retrieved content and construct an UpdateSkill request with ExpectedVersion.

3. After submission, read the skill back to confirm the changes.

4. Run a real invocation on a test agent, covering three scenarios: normal input, default input, and abnormal input.

5. After verification passes, allow the agents in the production environment to use this version.

Before making changes, call ListAgents to check which agents have this skill mounted. Skill modifications do not trigger notifications to the mounting agents. Scheduled tasks reflect the new content only at the next trigger. For more information, see scheduled tasks.

Delete a skill

After deletion, invocations from mounting agents will fail, and the failure occurs at execution time rather than at configuration time.

Before calling DeleteSkill, make sure that no agents still have the skill mounted. If you want to stop using a skill but retain its content, unmount the skill from all agents first and keep the skill itself for future restoration.

Apply to the production environment

Maintain skill body content in a code repository. Use files as the source and publish to each environment through APIs, so that every change to the body has a review record and a diff.

The deployment workflow consists of five fixed steps: read, compare, submit, read back, and verify. The execution effect of a skill body change cannot be determined from API response values alone and can only be verified through real invocations.

Use different tenants and identity credentials for the test environment and the production environment. Publish and verify the same skill in the test tenant first, and then publish it to the production tenant to avoid affecting agents that are in use during verification.

The delete permission is granted separately. Do not grant DeleteSkill permission to the identity credentials used by batch deployment scripts. For more information, see API overview and authentication.

Quotas and limits

FAQ

• Q: Why does the agent behavior remain unchanged after I modify a skill?

  A: An ongoing session uses the skill content that was loaded when the session was initiated. Start a new session to verify the changes. Scheduled tasks will use the updated content only at the next trigger.

• Q: Can I upload a skill package by using the API?

  A: Zip skill packages that contain scripts and assets must be uploaded through the console, with a maximum file size of 50 MB. You can use the API to manage skill metadata and the SKILL.md content.

• Q: Why do I receive an invalid name error during creation?

  A: Verify the following: the name contains only lowercase letters, digits, underscores (_), and hyphens (-); the name starts with a letter; and the name is no longer than 64 characters. Also make sure that the reserved words anthropic and claude are not used.

• Q: How do I find out which agents use a specific skill?

  A: Call the ListAgents operation to retrieve the list of agents, and then check the skill references returned for each agent. The skill side does not provide a reverse lookup of associated agents.