命令行工具 acr-skill-容器镜像服务(ACR)-阿里云帮助中心

acr-skill是专为 AI Agent Skill 管理设计的命令行工具，提供 Skill 的完整生命周期管理能力，包括发布、安装、更新、列表查看、验证等功能。

适用范围

已创建企业版实例，在实例中创建存储技能的专用命名空间（例如skills），并开启自动创建仓库功能。
已为ACR企业版实例配置网络访问控制，使客户端可以通过公网或VPC访问实例。
已获取ACR企业版实例的用户名和密码，或已配置 RAM 用户的 AccessKey。

快速入门

步骤一：安装并配置工具

下载acr-skill的预编译二进制文件：

平台	架构	下载链接
Linux	x86	acr-skill-linux-amd64
macOS	Arm (Apple Silicon)	acr-skill-darwin-arm64

安装工具：

Linux

添加文件操作权限：
```
chmod +x acr-skill-linux-amd64
```

将文件移动到bin文件夹中：

mv acr-skill-linux-amd64 /usr/local/bin/acr-skill

macOS

添加文件操作权限：
```
chmod +x acr-skill-darwin-arm64
```

将文件移动到bin文件夹中：

mv acr-skill-darwin-arm64 /usr/local/bin/acr-skill

验证安装效果：

acr-skill --help

预期输出：

acr-skill is a command-line tool for packaging, uploading, downloading, 
and extracting OCI artifacts. It exclusively supports Alibaba Cloud ACR Enterprise Edition.

Usage:
  acr-skill [command]

Available Commands:
  ...

请通过容器镜像服务控制台获取访问凭证并为工具配置。

当多个认证信息同时存在时，acr-skill工具按以下优先级获取凭证：

优先级	来源	说明
1（最高）	命令行指定	通过 --username、--password 等参数直接指定
2（最低）	环境变量	读取`REGISTRY_`、`ACR_SKILL_`等环境变量指定

通过环境变量配置

设置环境变量：

同时适用于Linux和macOS。

export REGISTRY_USERNAME="<USERNAME>"
export REGISTRY_PASSWORD="<PASSWORD>"

通过命令行参数指定

执行acr-skill命令时，直接配置参数：

acr-skill publish --username <USERNAME> --password <PASSWORD> ...

步骤二：发布及安装Skill

创建一个示例Skill：

mkdir my-skill
cat > my-skill/SKILL.md << 'EOF'
---
name: hello-world
description: 一个简单的示例Skill
version: 1.0.0
---

# Hello World Skill

这是一个示例Skill。
EOF

验证Skill的有效性：

acr-skill validate -d ./my-skill

预期输出：

✓ Validating skill structure...
  ✓ SKILL.md exists and is valid
  ✓ YAML frontmatter parsed successfully
  ✓ Required fields: name ✓, description ✓
  ✓ name format valid: content-research-writer
  ✓ No sensitive files detected
  ✓ Size: 21.1 KB (limit: 50.0 MB) ✓

Validation passed!

将CONTAINER_REGISTRY替换为ACR企业版示例链接后，执行下方命令，将Skill发布到ACR企业版实例：

acr-skill publish \
  --dir ./my-skill \
  --registry CONTAINER_REGISTRY \
  --namespace skills \
  --name hello-world \
  --version 1.0.0

预期输出：

Validating skill structure...
   ✓ Validation passed
Packaging skill from /Users/...
   ✓ Created tarball
Publishing to <registry>/skills/hello-world:1.0.0
   ✓ Successfully published (1.1s)    
    Digest: sha256:47ed657...

将CONTAINER_REGISTRY替换为ACR企业版示例链接后，执行下方命令，从ACR企业版实例安装Skill：

acr-skill install hello-world \
  --registry CONTAINER_REGISTRY \
  --namespace skills \
  --version 1.0.0

预期输出：

Pulling <registry>/skills/hello-world:1.0.0
Extracting to skills/hello-world
   ✓ Successfully installed hello-world:1.0.0 (905ms)

验证已安装的Skill：

acr-skill list

预期输出：

NAME  VERSION  REGISTRY  NAMESPACE  INSTALLED_AT  INSTALL_DIR
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
hello-world  1.0.0  <registry>  skills  2026-**-**T**:18:15Z  skills/hello-world

使用参考

命令结构

acr-skill <command> [flags]

控制命令输出

acr-skill 支持以下输出格式控制：

静默模式：使用--quiet或-q参数，仅输出错误信息。
选择输出格式：部分命令支持--format参数，可选值包括table、json、yaml、text等。

命令返回码

返回码	说明
0	命令执行成功
1	命令执行失败（参数错误、认证失败、网络错误等）

命令列表

命令	说明
validate	验证 Skill 目录的结构、元数据和内容是否符合规范。
publish	将本地 Skill 目录打包成 OCI 制品并发布到 ACR 企业版实例。
list	显示本地已安装的 Skill 列表。
install	从 ACR 企业版实例拉取 Skill 制品并安装到本地目录
update	检查并更新已安装的 Skill 到最新版本

validate

在发布之前，验证 Skill 目录的结构、元数据和内容是否符合规范。

重要

建议在发布前始终执行validate命令。在 CI/CD 流水线中，推荐使用--strict模式检查 Skill 质量。

命令格式

acr-skill validate [flags]

选项说明

选项	简写	默认值	说明
--directory	-d	.	Skill 目录路径
--max-size	无	50MB	最大体积限制（支持 MB/GB）
--strict	无	false	严格模式（将警告视为错误）
--format	无	text	输出格式（text/json）

验证内容

SKILL.md文件的存在性和非空性检查。
YAML 语法和字段验证（name、description、version）。
Skill 名称格式验证（小写字母、数字、连字符，1~64 个字符）。
敏感文件检测（如 .env、.ssh、*.key、*.pem、credentials 等）。
总体积检查（默认上限 50 MB）。
版本号语义化格式检查（警告级别）。

使用示例

验证当前目录：

acr-skill validate

验证指定目录：

acr-skill validate -d ./my-skill

publish

将本地 Skill 目录打包成 OCI 制品并发布到 ACR 企业版实例。

命令格式

# 方式一：通过完整路径指定
acr-skill publish <registry>/<namespace>/<skill-name>:<version> [flags]

# 方式二：通过参数分别指定
acr-skill publish [flags]

实际推送前可以通过--dry-run参数验证Skill目录结构和认证配置是否正确。

选项说明

选项	简写	默认值	说明
--dir	-d	无	源目录路径，包含 SKILL.md（必需）
--registry	-r	无	Registry 地址
--namespace	-n	无	命名空间
--name	无	无	Skill 名称
--version	-v	latest	Skill 版本号
--username	-u	无	ACR 企业版实例用户名
--password	-p	无	ACR 企业版实例密码
--dry-run	无	false	仅验证，不实际发布
--skip-validation	无	false	跳过发布前验证
--quiet	-q	false	静默模式，仅输出错误

使用示例

通过完整路径发布：

acr-skill publish <registry>/skills/my-skill:1.0.0 \
  --username "<USERNAME>" \
  --password "<PASSWORD>" \
  --dir ./my-skill

使用环境变量认证发布：

export REGISTRY_USERNAME="<USERNAME>"
export REGISTRY_PASSWORD="<PASSWORD>"
acr-skill publish \
  --dir ./my-skill \
  --registry <registry> \
  --namespace skills \
  --name my-skill \
  --version 1.0.0

list

显示已安装的 Skill 列表。

命令格式

acr-skill list [flags]

选项说明

选项	简写	默认值	说明
--directory	-d	./skills	Skill 安装目录
--format	无	table	输出格式（table/json/yaml）

使用示例

列出默认目录的Skill：
```
acr-skill list
```
列出指定目录的Skill：
```
acr-skill list --directory ./my-skills
```
JSON格式输出：
```
acr-skill list --format json
```

install

从 ACR 企业版实例拉取 Skill 制品并安装到本地目录。

命令格式

# 方式一：通过 Skill 名称和参数指定
acr-skill install <skill-name> [flags]

# 方式二：通过完整路径指定
acr-skill install <registry>/<namespace>/<skill-name>:<version> [flags]

选项说明

选项	简写	默认值	说明
--version	-v	latest	安装的版本号
--registry	-r	无	Registry 地址
--namespace	-n	无	命名空间
--dir	-d	./skills	安装路径
--force	-f	false	强制覆盖已安装的 Skill
--username	-u	无	ACR 企业版实例用户名
--password	-p	无	ACR 企业版实例密码
--quiet	-q	false	静默模式

使用示例

安装 Skill 到默认目录（./skills）：

acr-skill install <registry>/skills/my-skill:1.0.0 \
  --username "<USERNAME>" \
  --password "<PASSWORD>"

update

检查并更新已安装的 Skill 到最新版本。

命令格式

acr-skill update [skill-name] [flags]

选项说明

选项	简写	默认值	说明
--all	无	false	更新所有 Skill
--directory	-d	./skills	Skill 安装目录
--dry-run	无	false	仅检查，不更新
--force	-f	false	强制更新
--check-only	无	false	仅检查可用更新
--username	-u	无	ACR 企业版实例用户名
--password	-p	无	ACR 企业版实例密码
--quiet	-q	false	静默模式

使用示例

更新指定 Skill：
```
acr-skill update my-skill
```
更新所有 Skill：
```
acr-skill update --all
```
仅检查可用更新（不实际更新）：
```
acr-skill update --all --check-only
```
模拟更新（查看将要执行的操作）：
```
acr-skill update --all --dry-run
```