Alibaba Cloud RDS Copilot Skill Configuration Guide

This document covers the complete setup process for the alibabacloud-rds-copilot skill — from initial installation and credential configuration through plugin installation and end-to-end validation.

0. Overview

0.1 What This Skill Does

alibabacloud-rds-copilot is a Claude Code skill that serves as the AIOps agent for Alibaba Cloud RDS Copilot:

Submit RDS-related requests in natural language (Chinese or English) — query instances, optimize SQL, troubleshoot, analyze performance, etc.
The skill automatically calls aliyun rdsai chat-messages (RdsAi OpenAPI) to fetch real-time results
Provides explanations, diagnostics, and risk alerts for the results

0.2 Architecture

User natural language → Claude (trigger skill) → Alibaba Cloud CLI → RdsAi OpenAPI (rdsai.aliyuncs.com) → AI response

Key dependencies: Alibaba Cloud CLI + rdsai plugin + valid AK credential + RDS Copilot Professional Edition activated.

0.3 Prerequisites

Requirement	Description
Claude Code	Installed and able to run `npx`
Alibaba Cloud AccessKey	AK ID + Secret from the primary account or a RAM user
RAM permission	At least `rdsai:ChatMessages`. To query instances or slow query logs, add RDS read-only permissions (see Appendix).
RDS Copilot Professional Edition	Must be activated. Otherwise, calls return `No valid order found` (see Troubleshooting).
Network	Can access GitHub (to download the CLI) and Alibaba Cloud OpenAPI

Activate RDS Copilot Professional Edition:

1. Install the Skill

Command

npx skills add aliyun/alibabacloud-aiops-skills \
  --skill alibabacloud-rds-copilot \
  --agent claude-code -g -y --full-depth

Parameters

Parameter	Description
`aliyun/alibabacloud-aiops-skills`	Skill source repository (GitHub)
`--skill alibabacloud-rds-copilot`	Install only this skill (the repository contains 202 in total)
`--agent claude-code`	Target agent is Claude Code
`-g`	Global install (installs to `~/.claude/skills/`)
`-y`	Non-interactive, auto-confirm
`--full-depth`	Pull the complete skill including references sub-files

Expected Result

Clone repository → find 202 skills → select 1 → copy to ~/.claude/skills/alibabacloud-rds-copilot/
The install summary runs a security scan (Gen/Socket/Snyk). Note that Snyk may flag a Med Risk — read through SKILL.md before use.

Verify

ls ~/.claude/skills/alibabacloud-rds-copilot/
# Expected: SKILL.md  references/
ls ~/.claude/skills/alibabacloud-rds-copilot/references/
# Expected: acceptance-criteria.md  ram-policies.md  related-apis.md  verification-method.md

After installation, alibabacloud-rds-copilot appears in the active skills list of your Claude Code session.

2. Prepare Alibaba Cloud Credentials

The skill requires an AccessKey ID + AccessKey Secret pair to call OpenAPI. Configure them manually.

2.1 Manual Configuration

Use the interactive command directly. The secret stays in the CLI credential store and never enters your command history:

aliyun configure --mode AK --profile rdsai
# Follow the prompts to enter: Access Key Id / Access Key Secret / Default Region Id (enter cn-hangzhou)

The skill explicitly requires: do not use environment variables like export ALIBABA_CLOUD_ACCESS_KEY_ID=... as the regular configuration path.

3. Install Alibaba Cloud CLI

3.1 Check if Already Installed

command -v aliyun && aliyun version

Installed and >= 3.3.3 → skip to Step 4
Not installed or version too old → continue

3.2 Download and Install (Linux)

# Query the latest version and linux-amd64 download URL
REL=$(curl -fsSL https://api.github.com/repos/aliyun/aliyun-cli/releases/latest)
VER=$(echo "$REL" | jq -r .tag_name)
URL=$(echo "$REL" | jq -r '.assets[] | select(.name|test("linux.*amd64")) | .browser_download_url' | head -1)
echo "Version: $VER  Download: $URL

# Download, extract, and install
curl -fsSL "$URL" -o /tmp/aliyun-cli.tgz
tar xzf /tmp/aliyun-cli.tgz -C /tmp
install -m 0755 /tmp/aliyun /usr/local/bin/aliyun

# Verify
aliyun version   # Tested: 3.4.10

For macOS, you can use brew install aliyun-cli or the one-click script: /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)".

3.3 Verify Success

aliyun version outputs 3.4.10 (or higher), meeting the skill's requirement of >= 3.3.3.

4. Configure CLI Credentials (profile = rdsai)

Continue using the ID/SEC variables from Step 2.1. You must be in the same shell session. If not, rerun the value extraction command from 2.1 first.

4.1 Write the Profile

aliyun configure set \
  --mode AK \
  --profile rdsai \
  --region cn-hangzhou \
  --access-key-id "$ID" \
  --access-key-secret "$SEC"

Parameters:

Parameter	Description
`--mode AK`	Use AccessKey authentication (not STS/role)
`--profile rdsai`	Profile name. The skill uses this name by default.
`--region cn-hangzhou`	Default region. The skill specifies Hangzhou when no region is given.
`--access-key-id "$ID"`	Use a variable reference to avoid plaintext in the command line
`--access-key-secret "$SEC"`	Same as above. The secret is not echoed.

4.2 Enable Automatic Plugin Installation (skill MUST item)

aliyun configure set --auto-plugin-install true --profile rdsai

4.3 Verify Credential Status

aliyun configure list | sed -E 's/(LTAI[A-Za-z0-9]{0,6})[A-Za-z0-9]+/\1…(masked)/g'

Expected output (focus on the rdsai line):

Profile   | Credential   | Valid   | Region        | Language
--------- | ------------ | ------- | ------------- | --------
default   |              | Invalid |               | en
rdsai *   | AK:***…      | Valid   | cn-hangzhou   | en

Success criteria: the rdsai line shows Valid, has * (current profile), and Region = cn-hangzhou.

If it shows Invalid or reports InvalidAccessKeyId/SignatureDoesNotMatch → go back to Step 2 and check whether the AK ID/Secret split is correct (especially the pipe character).

5. Install the rdsai Plugin

5.1 Enable and Check Plugin Support

# auto-plugin-install was enabled in Step 4.2
aliyun plugin list            # View installed plugins
aliyun plugin search rdsai    # Search for the rdsai plugin

plugin search rdsai should return aliyun-cli-rdsai (some version, Status: Not installed).

5.2 Install the Dedicated Plugin

aliyun plugin install --names aliyun-cli-rdsai
# Expected: Plugin aliyun-cli-rdsai 0.7.1 installed successfully!

The aliyun rdsai command has product metadata built into the CLI (API Version 2025-05-07), so you can run basic commands without the dedicated plugin. The dedicated plugin provides enhanced capabilities and is recommended.

5.3 Verify rdsai Capabilities

aliyun rdsai --help                  # Should display Product: RdsAi
aliyun rdsai chat-messages --help    # Should display "Sends chat messages" and its parameters

If it reports 'plugin' is not a valid command or product → the CLI version is too old (< 3.3.0). Go back to Step 3 to upgrade.

6. Daily Use

Once configuration is complete, you can directly make RDS requests to Claude in natural language. The skill will automatically run the commands above. Examples:

"Help me check the RDS instances in the Hong Kong region."

「Optimize this SQL: SELECT * FROM users WHERE name LIKE "%test%"」
「Instance rm-bp1xxx is reporting connection timeout with Too many connections — help me troubleshoot (Hangzhou).」
「Analyze the performance and slow query logs of instance rm-xxx (Beijing).」
「Routine Instance Inspection: rm-xxxx (Hong Kong)」

Key points:

The default region is cn-hangzhou. If you mention another city (e.g., "Beijing"), the skill will use cn-beijing.
For complex issues, you can have multi-turn conversations. The skill reuses the ConversationId from the previous turn to maintain context.
When SQL or operation suggestions carry risk, the skill will prompt you to validate in a test environment first, to avoid running large-table DELETE/UPDATE/DDL directly in production.

7. Security Recommendations (Important)

The current local credential is the root AccessKey (the STS-returned ARN contains :root), which has full permissions but carries the highest risk: a leak means the entire Alibaba Cloud account is compromised. Furthermore, this AK exists in two locations: ~/.claude.json (MCP env) and ~/.alibabacloud/ (CLI credential store).

Recommendation: Use a RAM User with Least Privilege

1. Create a dedicated RAM user in the RAM console and generate an AccessKey for it.

2. Grant the least privilege policy:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["rdsai:ChatMessages"],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "rds:DescribeDBInstances",
        "rds:DescribeDBInstanceAttribute",
        "rds:DescribeDBInstancePerformance",
        "rds:DescribeSlowLogRecords",
        "rds:DescribeParameters"
      ],
      "Resource": "*"
    }
  ]
}

3. Rerun Step 4 aliyun configure set with the new AK to overwrite the rdsai profile.

4. Rotate AKs regularly.

For the complete policy, see /root/.claude/skills/alibabacloud-rds-copilot/references/ram-policies.md.

8. Troubleshooting Quick Reference

Symptom	Cause / Solution
`aliyun: command not found`	Not installed in Step 3 or not in PATH. Check `/usr/local/bin`
`aliyun version` < 3.3.3	Upgrade the CLI(`aliyun upgrade --yes` or reinstall)
`'plugin' is not a valid command`	CLI < 3.3.0, Upgrade first, then install the plugin.
`InvalidAccessKeyId` / `SignatureDoesNotMatch`	AK is invalid or split incorrectly. Check the `\|` separator in `ALIYUN_ACCESS_TOKEN` (Step 2.1).
`No valid order found`	RDS Copilot Professional Edition is not activated. See Section 6.5.
`Forbidden` / insufficient permissions	RAM has not granted `rdsai:ChatMessages` (or the RDS read-only extension). See Section 8 for the policy.
`unknown profile rdsai`	Profile not configured. Go back to Step 4.
Call hangs with no response	Check network connectivity to `rdsai.aliyuncs.com`

Community