Acr-skill CLI-Container Registry(ACR)-阿里云帮助中心

acr-skill is a command-line tool that manages the full lifecycle of AI agent skills, including publishing, installing, updating, listing, and validating.

Prerequisites

You have created an Enterprise Edition instance, created a dedicated namespace (for example, skills) within it to store skills, and enabled automatic repository creation.
You have configured network access control on the ACR Enterprise Edition instance to allow client access over the public network or a VPC.
You have obtained the username and password for the ACR Enterprise Edition instance or configured an AccessKey for a RAM user.

Quick start

Step 1: Install and configure the tool

Download the prebuilt acr-skill binary:

Platform	Architecture	Download link
Linux	x86	acr-skill-linux-amd64
macOS	Arm (Apple Silicon)	acr-skill-darwin-arm64

Install the tool:

Linux

Add executable permissions:
```
chmod +x acr-skill-linux-amd64
```

Move the file to the bin directory:

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

macOS

Add executable permissions:
```
chmod +x acr-skill-darwin-arm64
```

Move the file to the bin directory:

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

Verify the installation:

acr-skill --help

Expected output:

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

Obtain credentials from the Container Registry Console and use them to configure the tool.

When multiple authentication methods are available, acr-skill prioritizes them in the following order:

Priority	Source	Description
1 (Highest)	Command-line parameters	Set with parameters such as --username and --password.
2 (Lowest)	Environment variables	Read from environment variables such as `REGISTRY_` and `ACR_SKILL_`.

Environment variables

Set the environment variables:

Applies to both Linux and macOS.

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

Command-line parameters

Specify the parameters directly when running the acr-skill command:

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

Step 2: Publish and install a skill

Create a sample Skill:

mkdir my-skill
cat > my-skill/SKILL.md << 'EOF'
---
name: hello-world
description: A simple sample Skill
version: 1.0.0
---

# Hello World Skill

This is a sample Skill.
EOF

Validate the Skill:

acr-skill validate -d ./my-skill

Expected output:

✓ 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!

Replace CONTAINER_REGISTRY with the endpoint of your ACR Enterprise Edition instance, and run the following command:

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

Expected output:

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...

Replace CONTAINER_REGISTRY with the endpoint of your ACR Enterprise Edition instance, and run the following command:

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

Expected output:

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

Verify the installed Skill:

acr-skill list

Expected output:

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

Usage reference

Command syntax

acr-skill <command> [flags]

Command output

Control acr-skill output with the following options:

Quiet mode: Use the --quiet or -q flag to display only error messages.
Output format: Some commands support the --format option. Supported formats are table, json, yaml, and text.

Command exit codes

Exit code	Description
0	The command completed successfully.
1	The command failed. Common causes include invalid parameters, authentication failure, or network errors.

Commands

Command	Description
validate	Verifies that a Skill directory's structure, metadata, and content meet specifications.
publish	Packages a local Skill directory into an OCI artifact and publishes it to an ACR Enterprise instance.
list	Lists locally installed Skills.
install	Pulls a Skill artifact from an ACR Enterprise instance and installs it locally.
update	Updates installed Skills to their latest available versions.

validate

Validates a Skill directory's structure, metadata, and content for compliance before publishing.

Important

Always run the validate command before publishing. In a CI/CD pipeline, use the --strict mode to enforce stricter quality checks.

Syntax

acr-skill validate [flags]

Options

Option	Shorthand	Default	Description
--directory	-d	.	Path to the Skill directory.
--max-size	N/A	50MB	Maximum size limit (supports MB/GB).
--strict	N/A	false	Enables strict mode, which treats warnings as errors.
--format	N/A	text	Output format (text/json).

Validation checks

Verifies that the SKILL.md file exists and is not empty.
Validates the YAML syntax and the required fields: name, description, and version.
Validates the Skill name format (1-64 characters, lowercase letters, digits, and hyphens).
Detects sensitive files, such as .env, .ssh, *.key, *.pem, and credentials.
Checks the total size (default limit: 50 MB).
Checks the version format against semantic versioning standards, issuing a warning for non-compliance.

Examples

Validate the current directory:

acr-skill validate

Validate a specific directory:

acr-skill validate -d ./my-skill

publish

Packages a local Skill directory into an OCI artifact and publishes it to an ACR Enterprise instance.

Syntax

# Method 1: Specify by full path
acr-skill publish <registry>/<namespace>/<skill-name>:<version> [flags]

# Method 2: Specify with individual parameters
acr-skill publish [flags]

Before publishing, use the --dry-run flag to verify the Skill directory structure and authentication configuration without publishing the artifact.

Options

Option	Shorthand	Default	Description
--dir	-d	N/A	Path to the source directory containing SKILL.md (required).
--registry	-r	N/A	Registry address.
--namespace	-n	N/A	Target namespace.
--name	N/A	N/A	Skill name.
--version	-v	latest	Skill version.
--username	-u	N/A	Username for the ACR Enterprise instance.
--password	-p	N/A	Password for the ACR Enterprise instance.
--dry-run	N/A	false	Performs a validation check without publishing.
--skip-validation	N/A	false	Skips the pre-publish validation step.
--quiet	-q	false	Enables quiet mode, which displays only errors.

Examples

Publish using a full path:

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

Publish using environment variables for authentication:

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

Lists locally installed Skills.

Syntax

acr-skill list [flags]

Options

Option	Shorthand	Default	Description
--directory	-d	./skills	Path to the Skill installation directory.
--format	N/A	table	Output format (table/json/yaml).

Examples

List Skills in the default directory:
```
acr-skill list
```
List Skills in a specific directory:
```
acr-skill list --directory ./my-skills
```
Output the list in JSON format:
```
acr-skill list --format json
```

install

Pulls a Skill artifact from an ACR Enterprise instance and installs it locally.

Syntax

# Method 1: Specify by Skill name and parameters
acr-skill install <skill-name> [flags]

# Method 2: Specify by full path
acr-skill install <registry>/<namespace>/<skill-name>:<version> [flags]

Options

Option	Shorthand	Default	Description
--version	-v	latest	Skill version to install.
--registry	-r	N/A	Registry address.
--namespace	-n	N/A	Target namespace.
--dir	-d	./skills	Local installation path.
--force	-f	false	Forces reinstallation if the Skill already exists.
--username	-u	N/A	Username for the ACR Enterprise instance.
--password	-p	N/A	Password for the ACR Enterprise instance.
--quiet	-q	false	Enables quiet mode.

Example

Install a Skill to the default directory (./skills):

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

update

Updates installed Skills to their latest available versions.

Syntax

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

Options

Option	Shorthand	Default	Description
--all	N/A	false	Updates all installed Skills.
--directory	-d	./skills	Path to the Skill installation directory.
--dry-run	N/A	false	Performs a dry run, checking for updates without applying them.
--force	-f	false	Forces the update, overwriting the existing installation.
--check-only	N/A	false	Checks for available updates without installing them.
--username	-u	N/A	Username for the ACR Enterprise instance.
--password	-p	N/A	Password for the ACR Enterprise instance.
--quiet	-q	false	Enables quiet mode.

Examples

Update a specific Skill:
```
acr-skill update my-skill
```
Update all installed Skills:
```
acr-skill update --all
```
Check for available updates without installing them:
```
acr-skill update --all --check-only
```
Simulate an update to preview its actions:
```
acr-skill update --all --dry-run
```