企业官网建设流程全解析

如何用 nacos-cli 将本地 Skill 发布到 Nacos 注册中心并上线指定版本？

【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos

你手上有一个写好并验证过的本地 Skill 目录（含SKILL.md），希望把它发布到 Nacos 注册中心，让其他机器、Agent 或团队成员能通过nacos-cli skill-get安装，并且最终要把某个指定版本置为online状态。本文基于 Nacos 仓库中的 skills/nacos-skill-registry/SKILL.md 与 specs/zh-cn/ai/skill-spec.md 给出完整操作路径：安装配置 nacos-cli → 校验本地 Skill 包 → 上传草稿 → 提交审核 → 显式发布指定版本 → 按文档验收条件验证。

适用前提：有一个可访问的 Nacos 服务端；nacos-cli 已安装或可通过官方安装脚本安装。以下命令以文档说明的nacos-cli1.0.4生命周期契约为准。

准备 nacos-cli 并确认连接

先检查本机是否已安装：

which nacos-cli

未安装时，使用文档给出的官方安装脚本（Linux / macOS）：

curl -fsSL https://nacos.io/nacos-installer.sh | sudo bash -s -- --cli

Windows (PowerShell) 对应脚本为iwr -UseBasicParsing https://nacos.io/nacos-installer.ps1 -OutFile $env:TEMP\nacos-installer.ps1; & $env:TEMP\nacos-installer.ps1 -cli。该命令会通过 sudo 安装 CLI，注意执行环境权限。

安装后先确认版本和命令契约，因为不同 CLI 版本的发布流程不同：

nacos-cli -v nacos-cli --help

文档中的版本契约：1.0.4的发布流程为skill-upload→skill-review→ 等待审核通过 →skill-release；其他版本应先查看nacos-cli --help和各命令的--help，按实际存在的命令操作，不要照搬旧行为。

连接配置使用 profile 机制，配置文件存放在~/.nacos-cli/<profile>.conf，默认 profile 为default。检查是否已有可用 profile：

nacos-cli profile show

如果命令报错或显示为空，按文档做首次初始化：创建~/.nacos-cli/default.conf（例如mkdir -p ~/.nacos-cli后用编辑器打开），填入本机连接信息——Nacos 服务端 host 与 port、认证类型（none、nacos、aliyun或sts-hiclaw）、该认证类型所需的凭据、可选的 namespace（留空为 public 命名空间）。文档特别要求不要把真实用户名、密码、AK/SK 写进共享文档或示例。

配置完成后做连通性测试，文档指定用skill-list直接验证：

nacos-cli skill-list

能列出 Skill 即连接成功；若出现 401/403 检查凭据，连接被拒绝检查 host/port 与服务端是否运行，namespace 报错则核对 namespace ID。需要连接多个服务端时可用命名 profile，例如编辑~/.nacos-cli/dev.conf后以nacos-cli --profile dev skill-list使用。

确认本地 Skill 目录符合上传要求

上传前确认目录是一个合法的 Skill 包。按 specs/zh-cn/ai/skill-spec.md，Skill 包至少要求：

• 目录中存在SKILL.md，内容由 YAML frontmatter 和 Markdown 正文组成；
• name与description是必填 frontmatter 字段；license、compatibility、metadata、allowed-tools为可选字段；
• Skill name 需遵循上游命名规则：小写字母、数字和连字符，不能以连字符开头或结尾，不能包含连续连字符，长度不超过 64 个字符。

文档给出的确认命令（<path-to-skill>替换为你的 Skill 目录）：

ls <path-to-skill>/SKILL.md

文件不存在或缺少 frontmatter 时，先补齐再发布；否则服务端预检会返回NOT_A_SKILL或INVALID_SKILL（见文末限制说明）。仓库内的 skills/nacos-skill-registry/SKILL.md 本身就是一个符合该格式的结构示例，可参考其 frontmatter 写法。

如果上传的是已有 Skill 的新版本，文档要求先做版本门禁：用skill-describe对比本地版本与远端 online/latest 版本。两者相同时可直接走上传路径；远端版本更新时，应先下载远端版本、与本地 diff 合并后再发布合并结果，不要直接上传本地目录。

执行发布：upload、review、release 三步

以下命令以文档示例 Skill 名my-skill演示，目录参数替换为你的实际 Skill 目录路径。

第一步，上传创建编辑中草稿：

nacos-cli skill-upload ./my-skill

skill-upload会创建或更新一个editing草稿版本（对应生命周期状态draft）。若目录里有多个 Skill，文档提供了批量入口nacos-cli skill-upload --all ./skills-folder，注意它会上传目录下所有 Skill，只在目录内容都属于本次发布任务时使用。

上传版本的来源优先级在 specs/zh-cn/ai/skill-spec.md 中有定义：SKILL.mdfrontmatter 的version、frontmatter 的metadata.version、同目录_meta.json的version、请求参数targetVersion、服务端默认版本，按此顺序取第一个合法且可用的版本。

第二步，提交草稿进入审核：

nacos-cli skill-review my-skill

skill-review将草稿移向reviewing状态。按 specs/zh-cn/ai/ai-resource-lifecycle-spec.md 的状态模型，reviewing（已提交到发布流水线审核）通过后会变为reviewed（审核完成，等待显式发布），此时才具备发布条件。

第三步，确认目标版本已审核通过，再显式发布指定版本：

nacos-cli skill-describe my-skill # 等待目标版本变为 reviewed/approved 后再执行 nacos-cli skill-release my-skill --version <version> nacos-cli skill-describe my-skill

<version>替换为要上线的具体版本号。两个必须遵守的约束：skill-release要求显式传--version；在目标版本仍为editing或还在等待审核时不要执行skill-release。文档同时说明，在1.0.4中skill-publish已废弃，仅为兼容执行skill-upload+skill-review，不会完成skill-release，不要用它代替上述流程。

验证发布结果

文档给出的验收方式不是只看skill-list里出现 Skill 名，而是核对指定版本的状态。依次执行：

nacos-cli skill-list --name my-skill nacos-cli skill-describe my-skill nacos-cli skill-describe my-skill --output json

按文档对1.0.4的最小验收标准：

• release 之前：目标版本在skill-describe中应为 reviewed/approved；
• release 之后：目标版本状态为online；
• 若未使用--update-latest=false：labels.latest等于目标版本；
• 其他客户端按指定版本下载后：本地_meta.json的version与请求的版本一致。

最后一条可用文档给出的安装方式验证（--version指定要下载的版本）：

nacos-cli skill-get my-skill --version <version> cat ~/.skills/my-skill/_meta.json

skill-get会把 Skill 安装到~/.skills/并写入_meta.json（含ownerId、slug、version、publishedAt字段），其中version即从 Nacos 安装的版本，与请求版本一致说明发布链路完整。

限制与注意事项

• 上传已有 Skill 而调用方缺少写权限时，失败项会返回NO_PERMISSION，且结果在可获取时包含当前 owner。
• 已有审核中版本时上传会被阻断（预检码REVIEWING_EXISTS）；已有编辑中草稿时只能覆盖后继续（DRAFT_EXISTS）。预检码优先级为NOT_A_SKILL、INVALID_SKILL、NO_PERMISSION、REVIEWING_EXISTS、DRAFT_EXISTS、VERSION_ADJUSTED、READY，未知编码应按阻断处理。
• 生命周期规范明确：对online/offline状态的版本再次提交 Submit 会返回INVALID_PARAM且不修改状态；latestlabel 由服务端维护，客户端传入的latest值会被忽略。
• Nacos 注册中心路径不会在 upload、query 或 download 过程中执行包内脚本，包内scripts/等目录仅作为 Skill resource 存储和分发。

发布完成后，团队成员即可用nacos-cli skill-get my-skill安装；需要固定版本时用--version，需要按标签取版本时（如 stable）用--label。

【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos