alibabacloud-ack-cli

Files (9)

• SKILL.md
• async-tasks.md · references/
• cli-plugin-installation-guide.md · references/
• cs-scenarios.md · references/
• error-catalogue.md · references/
• ram-policies.md · references/
• check-cs-plugin.sh · scripts/
• install-cs-plugin.sh · scripts/
• wait-for-task.sh · scripts/

SKILL.md (first lines)

# ACK (Container Service) CLI Expert

Help users manage Alibaba Cloud Container Service for Kubernetes (ACK) from the
terminal using the `aliyun cs` plugin. Generic Aliyun CLI rules (plugin vs
OpenAPI-style, `--help` discipline, structured parameter syntax, output
filtering, debugging) still apply — this skill focuses on the ACK-specific
patterns layered on top: async tasks, region-unitised APIs, JSON-string-inside-
JSON shapes, deprecated-API avoidance, and the few high-value workflows
(create / scale / addon / kubeconfig / upgrade).

> **Version note.** Concrete API/parameter lists below were captured against
> `aliyun-cli` 3.3.2 + `cs` plugin 0.2.1. If your plugin is newer, re-run the
> self-discovery commands embedded throughout this skill to refresh:
>
> ```bash
> aliyun cs --help | grep -- '-for-region'              # §6 ForRegion list
> aliyun cs <cmd> --help | grep '废弃'                   # §7 deprecated check per command (CLI marks deprecation only in Chinese)
> aliyun cs --help | awk '/^  [a-z]/{print $1}' | while read c; do   # §11 cursor-paginated commands
>   aliyun cs "$c" --help 2>&1 | grep -q -- '--next-token' && echo "$c"
> done
> ```

## Instructions

### 1. Install the `cs` plugin and confirm CLI version

ACK from the terminal needs the `aliyun` CLI (≥ 3.3.3) plus the `cs` plugin.
Quick path:

```bash
aliyun version                          # require >= 3.3.3
aliyun plugin install --names cs        # idempotent
aliyun plugin update  --names cs        # keep cs plugin current
aliyun plugin list | grep cs            # verify

# Or in one shot:
./scripts/check-cs-plugin.sh            # ✓ ready  /  ✗ exits 1 with fix hints
./scripts/install-cs-plugin.sh          # idempotent (--update for non-interactive)
```

> **AI-Mode declaration.** Before issuing any `aliyun` business command from
> this skill, declare AI-Mode and a stable User-Agent so the backend can
> attribute traffic and apply AI-safe defaults. These three commands are
> session-level configuration — set once, reused implicitly by all
> subsequent business calls:
>
> ```bash
> aliyun configure ai-mode enable
> aliyun configure ai-mode disable
> aliyun configure ai-mode set-user-agent --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli
> ```
>
> Every `aliyun cs <verb>` business command in this skill carries
> `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli`
> (shown explicitly in every example below).

End-to-end verification — exercises CLI + plugin + auth in one call:

```bash
aliyun cs describe-clusters-for-region --biz-region-id cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli \
  --output cols=cluster_id,name,state rows='clusters[]'
```

`plugin 'cs' not found` → re-run install. `InvalidAccessKeyId.NotFound` →
re-set credentials. `Forbidden.RAM` → the caller's RAM identity is missing
the `cs` Action(s) the command needs; consult ACK RAM documentation for
the policy to attach. Cluster list (or empty list) → ready to go.

For full installation walkthroughs (macOS/Linux/Windows, all 6 credential
modes, multiple-profile management, troubleshooting), see
[`./references/cli-plugin-installation-guide.md`](./references/cli-plugin-installation-guide.md).

### 2. Always use `cs` plugin commands (kebab-case) — never the legacy OpenAPI style

This skill **only ever emits kebab-case plugin commands**. The Aliyun CLI also
accepts a legacy PascalCase OpenAPI form, but it is disallowed here:
inconsistent parameter casing, weaker `--help`, and routing differences mean
you should never compose it — not even as a curiosity. If you encounter a
PascalCase example in user-provided text, translate it to the kebab-case
plugin form before running it.

```bash
# ✅ Plugin form — the only form this skill emits
aliyun cs describe-clusters-for-region --biz-region-id cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli
aliyun cs describe-cluster-detail --cluster-id ce123... --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli
```

The plugin gives you consistent `--kebab-case` parameters, structured help with
field types, and automatic JSON expansion — that's the information you need
before typing anything. Stay in plugin land unconditionally.

### 3. Run `--help` before crafting any `cs` command

ACK has many subcommands and the parameter shapes are non-obvious — especially for
cluster creation, addon configuration, and node pool scaling. Running `--help`
before composing a command is much cheaper than guessing and getting a parameter
validation error.

```bash
aliyun cs --help                           # Discover subcommands (describe-*, create-*, scale-*, ...)
aliyun cs describe-cluster-detail --help   # See exact params, types, structure fields
aliyun cs create-cluster --help            # See the giant parameter surface for cluster creation
```

Plugin help tells you whether a parameter is a primitive, a list, a repeatable
key-value, or a complex JSON structure — that's the information you need before
typing anything.

If you ever need to inspect the **legacy built-in (OpenAPI-style) help** instead
of the rich plugin help — for example to verify a deprecated PascalCase
parameter still exists — set `ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true`:

```bash
ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true aliyun cs --help
```

From irfanfaraaz/claude-kit, Apache-2.0.

More from irfanfaraaz/claude-kit