AI Registry Skill 快速上手指南

导入已有 Skill

在 Skill 列表页点击 导入 Skill，系统支持两种导入方式：

• 导入预置 Skill：系统内置了官方预置 Skill 模板，可直接勾选需要的 Skill 一键导入。

• 上传文件：将本地 Skill 目录打包为 ZIP 文件上传。

导入后系统自动生成草稿版本。

新建 Skill

1. 在左侧导航栏选择 AI 资源管理 > Skill，在页面顶部的工作空间下拉框中选择目标工作空间。

2. 点击右上角 + 新建 Skill。

3. 填写基础信息：

   配置项	是否必填	说明
   Skill 名称	是	最多 64 个字符，仅支持字母、数字、下划线和中划线
   描述	是	最多 1000 个字符，描述 Skill 的功能和用途
   标签	否	输入后按回车确认，用于业务分类和检索

4. 展开 高级选项 可设置可见性：私有（默认，仅自己可见）或 公开（所有人可见）。

5. 在编辑器中编写 SKILL.md（必填）。SKILL.md 使用 Markdown 格式，左侧编辑右侧实时预览。基本结构如下：

   • name（必填）：Skill 名称，用于标识

   • description（必填）：用途描述，说明 Skill 的功能和适用场景

   • instructions（必填）：核心指令，定义 Agent 如何使用该 Skill

   • 可选字段：tools（工具列表）、dependencies（依赖项）等

6. 编辑完成后，点击右上角 立即创建。

选择集成方式

配置 VPC 私网访问

如果选择公网访问，可跳过本小节，直接使用公网访问配置指南中的接入点域名作为后续host/ serverAddr。

如果选择VPC 私网访问，可在 AI治理中心控制台「接入管理」中一键关联 VPC，系统自动完成 PrivateLink 终端节点配置，无需手动到 VPC 控制台创建终端节点。

前提条件：

• 已在目标地域创建 VPC（参考 创建/删除专有网络与交换机）

• 已创建用于部署应用的 VPC 和交换机。如尚未创建，请参考创建专有网络和交换机

• 已创建安全组。如尚未创建，请参考使用安全组

配置步骤：

1. 登录 MSE 控制台，在左侧导航栏选择 AI Registry > 接入管理。

2. 在 VPC 接入 区域点击右上角 + 关联 VPC。

3. 在弹窗中按以下参数配置：

   配置项	说明
   选择 VPC	选择已创建的目标 VPC
   可用区与交换机	选择 VPC 内的可用区及对应交换机，可点击 + 添加交换机 配置多个；建议至少选择两个可用区以具备高可用能力
   安全组	选择允许 VPC 内访问的安全组
   描述	可选，便于识别该接入记录

4. 点击 确认关联。系统自动创建 VPC 端点，通常 1～2 分钟生效，状态变为 可用 即接入完成。

验证连通性：

接入完成后，VPC 接入 区域顶部展示当前地域的私网访问域名。若 VPC 内已有 ECS 实例，可在 ECS 上执行以下命令验证：

# 测试网络连通性（以杭州地域为例）
ping -c 4 airegistry.cn-hangzhou.mse.aliyuncs.com

方式 A：Nacos CLI

凭证配置： 在运行客户端的设备上执行以下命令配置登录凭证：

npx @nacos-group/cli profile edit

按提示填写：

验证连接：

npx @nacos-group/cli skill-list

若返回 Skill 列表或空列表，说明配置成功。

下载 Skill： 支持 QwenPaw、Qoder、Claude、Codex、Cursor 等多种 AI 编程工具。在控制台 Skill 详情页选择对应工具后，页面自动生成对应命令，复制执行即可：

# 下载最新版本
npx @nacos-group/cli skill-get <skill-name>

# 下载指定版本
npx @nacos-group/cli skill-get <skill-name> --version 1.0.0 -o ~/my-skills

# 按标签下载
npx @nacos-group/cli skill-get <skill-name> --label latest

方式 B：Java SDK

添加依赖：

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>${nacos.version}</version>
</dependency>

初始化 AiService：

将 SERVER_ADDR 替换为公网接入点域名或私网域名。

Properties properties = new Properties();
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "airegistry.cn-hangzhou.mse.aliyuncs.com:80");
properties.setProperty(PropertyKeyConst.NAMESPACE, "xxxxxx-xxxx-xxxx-xxxx-xxxxxx");
properties.setProperty(PropertyKeyConst.ACCESS_KEY, "LTAI5tXXXXXXXXXXXXXX");
properties.setProperty(PropertyKeyConst.SECRET_KEY, "XXXXXXXXXXXXXXXXXXXXxx");

AiService aiService = AiFactory.createAiService(properties);

一个 AiService 实例对应一个命名空间。访问多个命名空间时需分别创建实例；应用内尽量复用同一实例，退出时调用 shutdown() 释放资源。

下载 Skill ZIP：

SDK 提供按名称、按版本、按标签三种下载方式，返回 ZIP 字节数组（byte[]），包含 SKILL.md 和全部资源文件（二进制资源自动从 Base64 解码）。

try {
    // 下载最新版本
    byte[] skillZip = aiService.downloadSkillZip("my-first-skill");

    // 下载指定版本
    byte[] skillZipByVer = aiService.downloadSkillZipByVersion("my-first-skill", "1.0.0");

    // 按标签下载
    byte[] skillZipByLabel = aiService.downloadSkillZipByLabel("my-first-skill", "latest");
} catch (NacosException e) {
    e.printStackTrace();
}

订阅 Skill 变更：

通过 subscribeSkill 订阅 Skill 更新，当 ZIP 内容变化时通过监听器回调。version、label 可选，用于限定订阅范围：

try {
    aiService.subscribeSkill("my-first-skill", null, null, new AbstractNacosSkillListener() {
        @Override
        public void onEvent(SkillEvent event) {
            byte[] newZip = event.getSkillZip();
            System.out.println("skill updated, size: " + newZip.length);
        }
    });
} catch (NacosException e) {
    e.printStackTrace();
}

方式 C：AgentScope

通过 agentscope-extensions-nacos-skill 模块在 AgentScope 框架中使用 AI 治理中心的 Skill。

添加依赖：

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-nacos-skill</artifactId>
</dependency>

完整示例（复制即用）：

将 SERVER_ADDR 替换为公网接入点域名或私网域名。

import com.alibaba.nacos.api.PropertyKeyConst;
import com.alibaba.nacos.api.ai.AiFactory;
import com.alibaba.nacos.api.ai.AiService;
import io.agentscope.core.ReActAgent;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.message.Msg;
import io.agentscope.core.nacos.skill.NacosSkillRepository;
import io.agentscope.core.skill.AgentSkill;
import io.agentscope.core.skill.SkillBox;
import java.util.Properties;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        // 1. 连接 AI Registry
        Properties props = new Properties();
        props.put(PropertyKeyConst.SERVER_ADDR, "airegistry.cn-hangzhou.mse.aliyuncs.com:80");
        props.put(PropertyKeyConst.NAMESPACE, "xxxxxx-xxxx-xxxx-xxxx-xxxxxx");
        props.put(PropertyKeyConst.ACCESS_KEY, "your-access-key");
        props.put(PropertyKeyConst.SECRET_KEY, "your-secret-key");
        AiService aiService = AiFactory.createAiService(props);

        // 2. 加载 Skill
        NacosSkillRepository repo = new NacosSkillRepository(aiService, "public");
        AgentSkill skill = repo.getSkill("my-first-skill");

        // 3. 绑定到 Agent
        SkillBox skillBox = new SkillBox(repo);
        ReActAgent agent = ReActAgent.builder()
                .name("MyAgent")
                .model(DashScopeChatModel.builder()
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .modelName("qwen-max")
                        .build())
                .skillBox(skillBox)
                .build();

        // 4. 对话
        Msg response = agent.call(Msg.of("你好"));
        System.out.println(response.getText());

        aiService.shutdown();
    }
}

支持按版本（AGENTSCOPE_NACOS_SKILL_VERSION）或标签（AGENTSCOPE_NACOS_SKILL_LABEL）筛选具体版本，仓库为只读。

更多配置选项和高级用法请参考 AgentScope 对接 Nacos AI Registry 使用 Skill。