alibabacloud-resourcecenter-search

What this skill does

## 1. Prerequisites

> **[MUST] CLI User-Agent** — Every `aliyun` CLI command invocation must include:
> `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search`

> **[MUST] Enable AI-Mode** — AI-mode is required for Agent Skill execution.
> Run the following commands before any other `aliyun` CLI invocation:
> ```bash
> aliyun configure ai-mode enable
> aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search"
> ```

> **Pre-check: Aliyun CLI >= 3.3.3 required**
> Run `aliyun version` to verify >= 3.3.3. If not installed or version too low,
> run `curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash` to install/update,
> or see `references/cli-installation-guide.md` for installation instructions.
> Then **[MUST]** run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation.
> Then **[MUST]** run `aliyun plugin update` to ensure that any existing plugins on your local machine are always up-to-date.

> **Pre-check: Alibaba Cloud Credentials Required**
>
> **Security Rules:**
>
> - **NEVER** read, echo, or print AK/SK values (e.g., `echo $ALIBABA_CLOUD_ACCESS_KEY_ID` is FORBIDDEN)
> - **NEVER** ask the user to input AK/SK directly in the conversation or command line
> - **NEVER** use `aliyun configure set` with literal credential values
> - **ONLY** use `aliyun configure list` to check credential status
>
> ```bash
> aliyun configure list
> ```
>
> Check the output for a valid profile (AK, STS, or OAuth identity).
>
> **If no valid profile exists, STOP here.**
>
> 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak)
> 2. Configure credentials **outside of this session** (via `aliyun configure` in terminal or environment variables in shell profile)
> 3. Return and re-run after `aliyun configure list` shows a valid profile

> **[MUST] Disable AI-Mode at EVERY exit point** — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed.
> AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.
> ```bash
> aliyun configure ai-mode disable
> ```

---

## 2. Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call,
> ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks,
> passwords, domain names, resource specifications, etc.) MUST be confirmed with the
> user. Do NOT assume and use default values without explicit user approval.

| Parameter | Required/Optional | Description | Default Value |
| - | - | - | - |
| `Scope` | Required (cross-account) | Cross-account search scope: Resource Directory ID, Root Folder ID, Folder ID, or Member ID | None |
| `ResourceType` | Optional | Resource type (e.g., `ACS::ECS::Instance`) | None (all types) |
| `RegionId` | Optional | Resource Region ID (e.g., `cn-hangzhou`) | None (all regions) |
| `ResourceId` | Optional | Resource ID | None |
| `ResourceName` | Optional | Resource name  | None |
| `VpcId` | Optional | VPC ID (e.g., `vpc-xxx`) | None |
| `VSwitchId` | Optional | VSwitch (e.g., `vsw-xxx`) | None |
| `IpAddress` | Optional | IP address | None |
| `GroupByKey` | Optional | Statistics grouping dimension: `ResourceType`, `RegionId`, `ResourceGroupId` | None |
| `MaxResults` | Optional | Page size for paginated APIs. | 20 |

---

## 3. RAM Policy

See [references/ram-policies.md](references/ram-policies.md) for full permission lists.

Recommended system policies:

- **Read-only**: `AliyunResourceCenterReadOnlyAccess`
- **Full access**: `AliyunResourceCenterFullAccess`

> Opening Resource Center will auto-create the service-linked role `AliyunServiceRoleForResourceMetaCenter`.

### Resource Visibility Scope

RAM policies (defined in `ram-policies.md`) control whether a user **can call** a Resource Center API. However, for **search APIs** (`SearchResources`, `GetResourceCounts`, `GetResourceConfiguration`, `SearchMultiAccountResources`, `GetMultiAccountResourceCounts`, `GetMultiAccountResourceConfiguration`), the **scope of resources visible** in results is determined by each cloud product's own permissions:

#### Single Account

- **Cloud resource read permissions**: A RAM user can only see resources in Resource Center for which they have read-only access on the corresponding cloud product. For example, granting `ReadOnlyAccess` lets the user see all resources they have access to; granting only `AliyunVPCReadOnlyAccess` limits visibility to VPC resources.
- **Resource group scoped permissions**: If resources are organized by resource groups, you can grant a RAM user read access scoped to a specific resource group. The user will only see resources within that group, achieving resource isolation.

#### Cross-Account

- Grant the system policy `AliyunResourceCenterFullAccess` to the RAM user of the **Resource Directory management account** to enable cross-account resource search.

---

## 4. Core Workflow

### Step 1: Identify APIs Based on User Requirements

Determine which APIs are needed based on the user's specific scenario. Refer to the scenario cards below.

### Step 2: **[MUST]** Read API Documentation Before Every CLI Call

> **CRITICAL WARNING**: DO NOT execute any `aliyun resourcecenter` command without first reading the exact parameter format in `references/related-apis.md`.
>
> **Failure Pattern**: Guessing parameters like `--filter` format will cause errors. The correct JSON structure MUST be copied from the documentation.
>
> **Mandatory Action**: Open and read the specific API section in [references/related-apis.md](references/related-apis.md) BEFORE constructing any CLI command.

---

### Scenario Cards

#### Scenario 1: Service Activation

| Requirement | Account Type | API | Description |
| - | - | - | - |
| Check if enabled | Single-account | `get-resource-center-service-status` | Returns service status |
| Enable service | Single-account | `enable-resource-center` | Required for first-time use |
| Check cross-account status | Resource Directory | `get-multi-account-resource-center-service-status` | Multi-account scenario |
| Enable cross-account service | Resource Directory | `enable-multi-account-resource-center` | Requires management account or delegated admin |

---

#### Scenario 2: ResourceType Discovery

| Requirement | Account Type | Script | Description |
| - | - | - | - |
| Find resource type codes by keyword | Single-account | `scripts/query-resource-types.py` | Search across ResourceType, ProductName, and ResourceTypeName fields |

**Decision Logic**:

- When you needs to filter by resource type but doesn't know the exact code -> Use this script first
- After discovering the correct `ResourceType` code -> Use it in search or count API with `--filter` parameter

---

#### Scenario 3: Resource Search

| Requirement | Account Scope | API | Key Parameters |
| - | - | - | - |
| Search resources by criteria | Current account | `search-resources` | `--filter` |
| Cross-account resource search | Resource Directory | `search-multi-account-resources` | `--scope` + `--filter` |
| Search including deleted resources | Current account | `search-resources` | `--include-deleted-resources=true` |

---

#### Scenario 4: View Resource Details

| Requirement | Account Scope | API | Use Case |
| - | - | - | - |
| Get single resource configuration | Current account | `get-resource-configuration` | Get complete configuration details |
| Batch get multiple resource configurations | Current account | `batch-get-resource-configurations` | Get multiple resources at once |
| Get resource configuration from another account | Resource Directory | `get-multi-account-resource-configuration` | Cross-account view |

---

#### Scena