Skill: sdk-team/alibabacloud-find-skills (version 0.0.7)

--- name: alibabacloud-find-skills description: > Use this skill when users want to search, discover, browse, or find Alibaba Cloud (阿里云) agent skills. Triggers include: "find a skill for X", "search alicloud skills", "阿里云有什么 skill","阿里云", "搜索阿里云技能", "有没有管理 ECS/RDS/OSS 的 skill", "阿里云 skills 有哪些类目", "帮我找一个 skill", "browse alicloud skills", "list alicloud skill categories", "is there an alicloud skill that can...", "what alicloud skills are available", "XX Skill 的内容是什么", "我想了解阿里云 XX Skill 具体做什么","帮我安装阿里云 Skill","使用阿里云相关的skill", "阿里云 agent skill 市场", "搜一下阿里云的 skill". --- > [!IMPORTANT] > **For any Alibaba Cloud query or management task:** > 1. **Search** — use this skill (`alibabacloud-find-skills`) to find the relevant Skill. > 2. **Install** — install the matched Skill (see [Installation](#installation)). > 3. **Execute** — follow the installed Skill's instructions to fulfill the request. # Alibaba Cloud Agent Skills Search & Discovery This skill helps users search, discover, and install Alibaba Cloud official Agent Skills through the `agentexplorer` CLI plugin. ## Scenario Description This skill enables users to: 1. **Search Skills** — Find Alibaba Cloud Agent Skills by keyword, category, or both 2. **Browse Categories** — Explore available skill categories and subcategories 3. **View Skill Details** — Get detailed information about specific skills 4. **Install Skills** — Guide users through skill installation process **Architecture**: Alibaba Cloud CLI + agentexplorer Plugin → Skills Repository ### Use Cases - "Find a skill for managing ECS instances" - "What Alibaba Cloud skills are available for databases?" - "阿里云有哪些 OSS 相关的 skill?" - "Browse all available alicloud skills" - "Install a skill for RDS management" ## Installation > **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](references/cli-installation-guide.md) for installation instructions. **[MUST] CLI User-Agent (API calls only)** — Every actual API invocation (e.g., `aliyun agentexplorer ...`) must include: `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills` > **Note**: This flag applies only to commands that hit the OpenAPI (such as `aliyun agentexplorer ...`). > Local/management commands like `aliyun configure ...`, `aliyun configure list`, `aliyun configure ai-mode ...`, > `aliyun plugin ...`, and `aliyun version` do **not** support the `--user-agent` flag — do not pass it to them. **[MUST] Region** — Every `aliyun agentexplorer ...` invocation must include `--region cn-hangzhou` (or another supported region). Without `--region`, the call will fail. ### Step 1: Authenticate Complete authentication first (see the **Authentication** section below). The next steps require valid credentials. ### Step 2: Enable Auto Plugin Install Once `aliyun configure list` shows a valid profile, enable automatic plugin installation: ```bash aliyun configure set --auto-plugin-install true ``` ### Step 3: Enable AI-Mode (Optional) Aliyun CLI provides AI-Mode. When enabled, the CLI automatically attaches AI identity information, allowing the server to identify and optimize Agent call chains. ```bash # Enable AI-Mode aliyun configure ai-mode enable # Set AI-Mode user-agent identifier aliyun configure ai-mode set-user-agent --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills # Disable AI-Mode aliyun configure ai-mode disable ``` ### Step 4: Update / Install Plugins ```bash # Refresh plugin index and update installed plugins aliyun plugin update # Install the agentexplorer plugin aliyun plugin install --names agentexplorer # Verify installation (this is an API call — UA + region required) aliyun agentexplorer --help ``` ## Authentication > **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 ## RAM Policy This skill uses read-only APIs from the AgentExplorer service. Required permissions: `agentexplorer:ListCategories`, `agentexplorer:SearchSkills`, `agentexplorer:GetSkillContent`. For the full RAM policy JSON, see [references/ram-policies.md](references/ram-policies.md). > **[MUST] Permission Failure Handling:** When any command or API call fails due to permission errors at any point during execution, follow this process: > > 1. Read `references/ram-policies.md` to get the full list of permissions required by this SKILL > 2. Use `ram-permission-diagnose` skill to guide the user through requesting the necessary permissions > 3. Pause and wait until the user confirms that the required permissions have been granted For detailed permission information, see [references/ram-policies.md](references/ram-policies.md). ## Core Workflow ### Step 1: Search Skills Based on user intent, choose keyword search, category search, or both: - **Keyword search**: Extract keywords from the user's request and execute search directly - **Category search**: Call `list-categories` to get all available categories, select the best match, and search - **Combined search**: Use both keyword and category to narrow results ```bash # Keyword search aliyun agentexplorer search-skills \ --keyword "<keyword>" \ --max-results 20 \ --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills # Get all categories aliyun agentexplorer list-categories \ --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills # Category search aliyun agentexplorer search-skills \ --category-code "<category-code>" \ --max-results 20 \ --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills # Combined search (keyword + category) aliyun agentexplorer search-skills \ --keyword "<keyword>" \ --category-code "<category-code>" \ --max-results 20 \ --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills ``` ### Step 2: Iterate Until Found If the target skill is not in the results, adjust search criteria and retry automatically: 1. Switch between Chinese and English keywords ("cloud server" → "ECS", "object storage" → "OSS") 2. Broaden keywords (drop qualifiers: "RDS backup automation" → "RDS") 3. Remove category filter, search by keyword only 4. Try synonyms or related terms ("instance" → "ECS", "bucket" → "OSS") 5. Browse the most relevant top-level category without keyword Repeat until the target skill is found or confirmed not to exist. If all attempts fail, inform the user what was tried. ### Step 3: View Skill Details (Optional) Optionally retrieve skill content to verify it matches user intent before installation. This step can be skipped if the search results already provide sufficient information. ```bash aliyun agentexplorer get-skill-content \ --skill-name "<skill-name>" \ --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills ``` ### Step 4: Install Skill Execute the installation command for the target skill. ```bash # Option A: Using npx skills add # By default this command is interactive (blocks for user input). # Recommended: use non-interactive mode to avoid blocking. # --agent <client> Agent client to install for (see references/npx-skills-agents.md) # -g Install globally (home dir); omit for project-local install # -y Skip confirmation (requires --agent and -g/-local to be set) npx skills add aliyun/alibabacloud-aiops-skills \ --skill <skill-name> \ --full-depth \ --agent qwen-code \ -g -y # Option B: Using npx clawhub install (OpenClaw ecosystem) npx clawhub install <skill-name> ``` Verify the skill appears in the available skills list after installation. ## Command Reference ### Parameters | Parameter Name | Required/Optional | Description | Default Value | | --------------- | -------------------------------- | ---------------------------------------------------------------- | ------------- | | `keyword` | Optional | Search keyword (product name, feature name, or description) | None | | `category-code` | Optional | Category code for filtering (e.g., "computing", "computing.ecs") | None | | `max-results` | Optional | Maximum number of results per page (1-100) | 20 | | `next-token` | Optional | Pagination token from previous response | None | | `skip` | Optional | Number of items to skip | 0 | | `skill-name` | Required (for get-skill-content) | Unique skill identifier | None | ### Pagination When search results span multiple pages, use `next-token` from the previous response to fetch the next page: ```bash aliyun agentexplorer search-skills \ --keyword "<keyword>" \ --max-results 20 \ --next-token "<next-token-from-previous-response>" \ --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills ``` ## Success Verification After each operation, verify success by checking: 1. **List Categories**: Response contains categoryCode and categoryName fields 2. **Search Skills**: Response contains skills array with valid skill objects 3. **Get Skill Content**: Response contains complete skill markdown content 4. **Install Skill**: Skill appears in Claude Code skills list For detailed verification steps, see [references/verification-method.md](references/verification-method.md). ## Search Strategies & Best Practices ### 1. Keyword Selection - **Use product codes**: `ecs`, `rds`, `oss`, `slb`, `vpc` (English abbreviations work best) - **Chinese names**: Also supported, e.g., "云服务器", "数据库", "对象存储" - **Feature terms**: "backup", "monitoring", "batch operation", "deployment" - **Generic terms**: When unsure, use broader terms like "compute", "storage", "network" ### 2. Category Filtering - **Browse first**: Use `list-categories` to understand available categories - **Top-level categories**: `computing`, `database`, `storage`, `networking`, `security`, etc. - **Subcategories**: Use dot notation like `computing.ecs`, `database.rds` - **Multiple categories**: Separate with commas: `computing,database` ### 3. Result Optimization - **Start broad**: Begin with keyword-only search, then add category filters - **Adjust page size**: Use `--max-results` based on display needs (20-50 typical) - **Check install counts**: Popular skills usually have higher install counts - **Read descriptions**: Match skill description to your specific use case ### 4. When No Results Found ```bash # Strategy 1: Try alternative keywords # Instead of "云服务器" try "ECS" or "instance" # Strategy 2: Remove filters # Drop category filter, search by keyword only # Strategy 3: Browse by category aliyun agentexplorer list-categories --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills aliyun agentexplorer search-skills --region cn-hangzhou --category-code "computing" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills # Strategy 4: Use broader terms # Instead of "RDS backup automation" try just "RDS" or "database" ``` ### 5. Display Results to Users When presenting search results, format as table: ``` Found N skills: | Skill Name | Display Name | Description | Category | Install Count | |------------|--------------|-------------|----------|---------------| | alibabacloud-ecs-batch | ECS Batch Operations | Batch manage ECS instances | Computing > ECS | 245 | | ... | ... | ... | ... | ... | ``` Include: - **skillName**: For installation and detailed queries - **displayName**: User-friendly name - **description**: Brief overview - **categoryName** + **subCategoryName**: Classification - **installCount**: Popularity indicator ## Cleanup This skill does not create any resources. No cleanup is required. ## Best Practices 1. **Always verify credentials first** — Use `aliyun configure list` before any search operation 2. **Iterate on search** — Automatically adjust keywords and retry until the target skill is found or confirmed absent 3. **Start with broad searches** — Narrow down with filters if too many results 4. **Show category structure** — Help users understand available categories before filtering 5. **Display results clearly** — Use tables to make skill comparison easy 6. **Provide skill names** — Always show `skillName` field for installation 7. **Handle pagination** — Offer to load more results if `nextToken` is present 8. **Check install counts** — Guide users toward popular, well-tested skills 9. **Show full details** — Use `get-skill-content` before installation recommendation 10. **Test after install** — Verify skill is available after installation ## Common Use Cases & Examples ### Example 1: Find ECS Management Skills ```bash # User: "Find skills for managing ECS instances" # Step 1: Search by keyword aliyun agentexplorer search-skills \ --keyword "ECS" \ --max-results 20 \ --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills # Step 2: Display results table and get details for the best match aliyun agentexplorer get-skill-content \ --skill-name "alibabacloud-ecs-batch-command" \ --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills ``` ### Example 2: Browse Database Skills ```bash # User: "What database skills are available?" # Step 1: List categories to show database category aliyun agentexplorer list-categories \ --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills # Step 2: Search database category aliyun agentexplorer search-skills \ --category-code "database" \ --max-results 20 \ --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills # Step 3: Display results grouped by subcategory ``` ### Example 3: Search with Chinese Keyword ```bash # User: "搜索 OSS 相关的 skill" # Step 1: Search using Chinese or English keyword aliyun agentexplorer search-skills \ --keyword "OSS" \ --max-results 20 \ --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills # Step 2: Display results in user's preferred language ``` ### Example 4: Narrow Down Search ```bash # User: "Find backup skills for RDS" # Step 1: Combined search aliyun agentexplorer search-skills \ --keyword "backup" \ --category-code "database.rds" \ --max-results 20 \ --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills # Step 2: Display targeted results ``` ## Reference Documentation | Reference | Description | | ---------------------------------------------------------------------------- | -------------------------------------------- | | [references/ram-policies.md](references/ram-policies.md) | Detailed RAM permission requirements | | [references/related-commands.md](references/related-commands.md) | Complete CLI command reference | | [references/verification-method.md](references/verification-method.md) | Success verification steps for each workflow | | [references/cli-installation-guide.md](references/cli-installation-guide.md) | Alibaba Cloud CLI installation guide | | [references/acceptance-criteria.md](references/acceptance-criteria.md) | Testing acceptance criteria and patterns | | [references/category-examples.md](references/category-examples.md) | Common category codes and examples | | [references/npx-skills-agents.md](references/npx-skills-agents.md) | Supported `--agent` values for `npx skills add` | ## Troubleshooting ### Error: "failed to load configuration" **Cause**: Alibaba Cloud CLI not configured with credentials. **Solution**: Follow authentication section above to configure credentials. ### Error: "Plugin not found" **Cause**: agentexplorer plugin not installed. **Solution**: Run `aliyun plugin install --names aliyun-cli-agentexplorer` ### No Results Returned **Cause**: Search criteria too specific or incorrect category code. **Solutions**: 1. Try broader keywords 2. Remove category filter 3. Use `list-categories` to verify category codes 4. Try English product codes instead of Chinese names ### Pagination Issues **Cause**: Incorrect nextToken or skip value. **Solution**: Use exact `nextToken` value from previous response, don't modify it. ## Notes - **Read-only operations**: This skill only performs queries, no resources are created - **No credentials required for browsing**: Some operations may work without full credentials - **Multi-language support**: Keywords support both English and Chinese - **Regular updates**: Skills catalog is regularly updated with new skills - **Community skills**: Some skills may be community-contributed, check descriptions carefully

path: references/acceptance-criteria.md
content: # Acceptance Criteria: alibabacloud-find-skills

**Skill Name**: `alibabacloud-find-skills`
**Purpose**: Validate correct CLI command patterns and ensure skill implementation follows best practices

---

## Prerequisites Validation

### 1. Aliyun CLI Version

#### ✅ CORRECT

```bash
# CLI version check returns >= 3.3.1
aliyun version
# Output: 3.3.2 (or higher)
```

#### ❌ INCORRECT

```bash
# Version too old (< 3.3.1)
aliyun version
# Output: 3.0.0
```

**Why**: This skill requires CLI version >= 3.3.1 for plugin support and modern command features.

---

### 2. Plugin Installation

#### ✅ CORRECT

```bash
# Install agentexplorer plugin
aliyun plugin install --names aliyun-cli-agentexplorer

# Verify installation
aliyun plugin list | grep agentexplorer
```

#### ❌ INCORRECT

```bash
# Incorrect plugin name
aliyun plugin install --names agentexplorer

# Wrong command
aliyun install plugin agentexplorer
```

**Why**: The plugin name must be exact: `aliyun-cli-agentexplorer`. CLI uses `plugin install --names` subcommand.

---

## CLI Command Patterns

### 1. Product Name Verification

#### ✅ CORRECT

```bash
# Correct product name
aliyun agentexplorer list-categories --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
aliyun agentexplorer search-skills --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
aliyun agentexplorer get-skill-content --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT

```bash
# Wrong product name
aliyun agent-explorer list-categories
aliyun skillexplorer search-skills
aliyun explorerAgent get-skill-content
```

**Why**: The product name is `agentexplorer` (no hyphens, no capitalization).

---

### 2. Command/Action Names

#### ✅ CORRECT

```bash
# Correct command names (lowercase with hyphens)
aliyun agentexplorer list-categories
aliyun agentexplorer search-skills
aliyun agentexplorer get-skill-content
```

#### ❌ INCORRECT

```bash
# Wrong command format (camelCase or incorrect names)
aliyun agentexplorer listCategories
aliyun agentexplorer SearchSkills
aliyun agentexplorer getSkillContent
aliyun agentexplorer list_categories
```

**Why**: Plugin mode uses lowercase with hyphens, NOT camelCase or underscores.

---

### 3. Parameter Names

#### ✅ CORRECT

```bash
# Correct parameter names
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --category-code "computing" \
  --max-results 20 \
  --next-token "abc123" \
  --skip 10 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

aliyun agentexplorer get-skill-content \
  --skill-name "alibabacloud-ecs-batch" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT

```bash
# Wrong parameter names
aliyun agentexplorer search-skills --keywords "ECS"  # plural
aliyun agentexplorer search-skills --category "computing"  # missing -code
aliyun agentexplorer search-skills --max-result 20  # singular
aliyun agentexplorer search-skills --nextToken "abc"  # camelCase
aliyun agentexplorer get-skill-content --skillName "name"  # camelCase
aliyun agentexplorer get-skill-content --name "name"  # wrong parameter
```

**Why**: Parameter names must match exactly as defined in `--help` output.

---

### 4. User-Agent and Region Flags (CRITICAL — API calls only)

#### ✅ CORRECT

```bash
# Every agentexplorer API command MUST include both --region and --user-agent
aliyun agentexplorer list-categories \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

aliyun agentexplorer get-skill-content \
  --skill-name "example" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT

```bash
# Missing user-agent flag
aliyun agentexplorer list-categories --region cn-hangzhou

# Missing --region (the call will fail)
aliyun agentexplorer search-skills --keyword "ECS" --user-agent AlibabaCloud-Agent-Skills

# Wrong user-agent value
aliyun agentexplorer list-categories --region cn-hangzhou --user-agent "MyAgent"

# Passing --user-agent to a local management command (NOT supported)
aliyun configure list
aliyun configure set --auto-plugin-install true --user-agent AlibabaCloud-Agent-Skills
aliyun plugin install --names agentexplorer --user-agent AlibabaCloud-Agent-Skills
aliyun version --user-agent AlibabaCloud-Agent-Skills
```

**Why**:
- Every `aliyun agentexplorer` API call MUST include `--region <region>` (e.g., `cn-hangzhou`) — without it, the call fails.
- Every `aliyun agentexplorer` API call MUST include `--user-agent AlibabaCloud-Agent-Skills` for tracking and compliance.
- Local management commands (`aliyun configure ...`, `aliyun configure list`, `aliyun configure set`, `aliyun configure ai-mode ...`, `aliyun plugin ...`, `aliyun version`) do **not** support `--user-agent` and do not need `--region`. Do not pass them.

---

### 5. Required Parameters

#### ✅ CORRECT

```bash
# get-skill-content requires --skill-name
aliyun agentexplorer get-skill-content \
  --skill-name "alibabacloud-ecs-batch" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# search-skills works with no required parameters (but keyword or category recommended)
aliyun agentexplorer search-skills \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# list-categories has no required parameters
aliyun agentexplorer list-categories \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT

```bash
# Missing required parameter
aliyun agentexplorer get-skill-content \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills
# ERROR: --skill-name is required
```

**Why**: `--skill-name` is mandatory for `get-skill-content`. Other commands have no required params beyond user-agent.

---

## Parameter Value Patterns

### 1. Category Code Format

#### ✅ CORRECT

```bash
# Top-level category
aliyun agentexplorer search-skills \
  --category-code "computing" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# Subcategory (dot notation)
aliyun agentexplorer search-skills \
  --category-code "computing.ecs" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# Multiple categories (comma-separated)
aliyun agentexplorer search-skills \
  --category-code "computing,database,storage" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# Mixed levels
aliyun agentexplorer search-skills \
  --category-code "computing.ecs,database" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT

```bash
# Wrong separator for multiple categories
aliyun agentexplorer search-skills --category-code "computing database"
aliyun agentexplorer search-skills --category-code "computing;database"

# Wrong subcategory format
aliyun agentexplorer search-skills --category-code "computing/ecs"
aliyun agentexplorer search-skills --category-code "computing:ecs"

# Invalid category codes
aliyun agentexplorer search-skills --category-code "invalid-category"
```

**Why**: Use dot notation for subcategories (e.g., `category.subcategory`), comma-separated for multiple.

---

### 2. Max Results Range

#### ✅ CORRECT

```bash
# Valid range: 1-100
aliyun agentexplorer search-skills \
  --max-results 1 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

aliyun agentexplorer search-skills \
  --max-results 50 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

aliyun agentexplorer search-skills \
  --max-results 100 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# Default (omit parameter)
aliyun agentexplorer search-skills \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills
# Uses default: 20
```

#### ❌ INCORRECT

```bash
# Out of range
aliyun agentexplorer search-skills --max-results 0
aliyun agentexplorer search-skills --max-results 101
aliyun agentexplorer search-skills --max-results 1000

# Invalid type
aliyun agentexplorer search-skills --max-results "twenty"
```

**Why**: `--max-results` must be an integer between 1 and 100 (inclusive).

---

### 3. Keyword Format

#### ✅ CORRECT

```bash
# Single word
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# Multiple words (quoted)
aliyun agentexplorer search-skills \
  --keyword "batch command" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# Chinese characters
aliyun agentexplorer search-skills \
  --keyword "云服务器" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# Mixed English and Chinese
aliyun agentexplorer search-skills \
  --keyword "ECS实例管理" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT

```bash
# Unquoted multi-word (may cause parsing errors)
aliyun agentexplorer search-skills --keyword batch command

# Special characters without quotes
aliyun agentexplorer search-skills --keyword ECS&RDS
```

**Why**: Multi-word keywords must be quoted. Special characters may need quoting or escaping.

---

### 4. Next Token Usage

#### ✅ CORRECT

```bash
# First page (no token)
RESULT=$(aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --max-results 20 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills)

# Extract nextToken from response
NEXT_TOKEN=$(echo "$RESULT" | jq -r '.nextToken')

# Second page (with token)
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --max-results 20 \
  --next-token "$NEXT_TOKEN" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT

```bash
# Manually crafted token
aliyun agentexplorer search-skills \
  --next-token "page2" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# Modified token
aliyun agentexplorer search-skills \
  --next-token "${NEXT_TOKEN}_modified" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# Using skip instead of next-token for pagination
aliyun agentexplorer search-skills \
  --skip 20 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills
# Note: --skip is valid but --next-token is preferred for pagination
```

**Why**: `nextToken` must be used exactly as returned by the API, without modification.

---

## Authentication Patterns

### 1. Credential Verification

#### ✅ CORRECT

```bash
# Check credentials before operations
aliyun configure list

# Never read/print credentials
# NEVER do: echo $ALIBABA_CLOUD_ACCESS_KEY_ID
# NEVER do: aliyun configure get --key access_key_id
```

#### ❌ INCORRECT

```bash
# Reading credentials
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET

# Printing credentials
aliyun configure get --key access_key_id

# Asking user to input credentials in conversation
# "Please provide your Access Key ID"
```

**Why**: Credentials must NEVER be read, printed, or requested directly for security reasons.

---

### 2. Configuration Check

#### ✅ CORRECT

```bash
# Use configure list to check status
aliyun configure list

# Check if output shows valid profile
# Example valid output:
# Profile   | Credential         | Valid   | Region
# --------- | ------------------ | ------- | --------
# default * | AK:***abc          | Valid   | cn-hangzhou
```

#### ❌ INCORRECT

```bash
# Don't test credentials by making API calls
aliyun agentexplorer list-categories --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
# (Use this for functionality, not credential verification)
```

**Why**: Use `configure list` specifically for credential validation before operations.

---

## Output Handling Patterns

### 1. JMESPath Filtering

#### ✅ CORRECT

```bash
# Filter for specific fields
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --cli-query "skills[].skillName" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# Filter with conditions
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --cli-query "skills[?installCount > \`100\`]" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# Select first item
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --cli-query "skills[0]" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT

```bash
# Invalid JMESPath syntax
aliyun agentexplorer search-skills --cli-query "skills.skillName"  # Missing []
aliyun agentexplorer search-skills --cli-query "skills[skillName]"  # Wrong syntax
```

**Why**: JMESPath syntax must be valid. Arrays require `[]`, conditions use `?`, literals use backticks.

---

### 2. Result Display

#### ✅ CORRECT

```markdown
# Display results in table format

| Skill Name             | Display Name  | Category  | Install Count |
| ---------------------- | ------------- | --------- | ------------- |
| alibabacloud-ecs-batch | ECS Batch Ops | Computing | 245           |

# Show key fields

- **Skill Name**: alibabacloud-ecs-batch
- **Description**: Batch manage ECS instances
- **Category**: Computing > ECS
```

#### ❌ INCORRECT

```bash
# Dumping raw JSON
echo "$RESULT"

# No formatting
echo "$RESULT" | jq
```

**Why**: Users need human-readable, formatted output with relevant fields highlighted.

---

## Error Handling Patterns

### 1. Missing Plugin

#### ✅ CORRECT

```bash
# Check plugin before use
if ! aliyun plugin list | grep -q "agentexplorer"; then
  echo "Installing agentexplorer plugin..."
  aliyun plugin install --names aliyun-cli-agentexplorer
fi
```

#### ❌ INCORRECT

```bash
# Assume plugin is installed
aliyun agentexplorer list-categories --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
# May fail if plugin not installed
```

**Why**: Verify prerequisites before execution to provide helpful error messages.

---

### 2. No Results Handling

#### ✅ CORRECT

```bash
RESULT=$(aliyun agentexplorer search-skills \
  --keyword "nonexistent" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills)

# Check if skills array is empty
if echo "$RESULT" | jq -e '.skills | length == 0' > /dev/null; then
  echo "No skills found for keyword 'nonexistent'"
  echo "Try: broader keywords, different category, or list all categories"
fi
```

#### ❌ INCORRECT

```bash
# Don't treat empty results as error
RESULT=$(aliyun agentexplorer search-skills --keyword "nonexistent" --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills)
if [ $? -ne 0 ]; then
  echo "Search failed"  # Wrong: empty results return exit code 0
fi
```

**Why**: Empty results are valid responses (exit code 0), not errors.

---

## Workflow Patterns

### 1. Search-Detail-Install Flow

#### ✅ CORRECT

```bash
# Step 1: Search
SEARCH_RESULT=$(aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills)

# Step 2: Display results to user, get confirmation
echo "Found skills: ..."
# [User selects: alibabacloud-ecs-batch]

# Step 3: Get details
aliyun agentexplorer get-skill-content \
  --skill-name "alibabacloud-ecs-batch" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

# Step 4: User confirms installation
npx skills add https://github.com/aliyun/alibabacloud-aiops-skills --skill alibabacloud-ecs-batch --full-depth
```

#### ❌ INCORRECT

```bash
# Skip presenting results to user
SKILL=$(aliyun agentexplorer search-skills --keyword "ECS" --cli-query "skills[0].skillName" --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills)
npx skills add https://github.com/aliyun/alibabacloud-aiops-skills --skill "$SKILL" --full-depth
# Wrong: Should present search results and skill details to user before installing
```

**Why**: Always present search results and skill details to the user before executing installation.

---

## Common Anti-Patterns

### ❌ ANTI-PATTERN 1: Arbitrary Hardcoded Values

```bash
# DON'T use keywords unrelated to the user's request
# e.g., User asks about databases but Agent searches for "ECS"
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --category-code "computing" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills
```

**✅ CORRECT**: Derive keyword and category from the user's intent.

---

### ❌ ANTI-PATTERN 2: Missing Error Handling

```bash
# DON'T ignore errors
aliyun agentexplorer search-skills --keyword "test" --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
# Continue regardless of result
```

**✅ CORRECT**: Check exit codes and handle errors.

---

### ❌ ANTI-PATTERN 3: Credential Exposure

```bash
# DON'T print or request credentials
echo "Your AK: $ALIBABA_CLOUD_ACCESS_KEY_ID"
```

**✅ CORRECT**: Use `configure list` to check status only.

---

## Testing Checklist

Before completing the skill, verify:

- [ ] All commands use correct product name: `agentexplorer`
- [ ] All commands use lowercase-with-hyphens format
- [ ] All parameters match `--help` output exactly
- [ ] Every `aliyun agentexplorer` command includes `--region <region>` (e.g., `cn-hangzhou`)
- [ ] Every `aliyun agentexplorer` command includes `--user-agent AlibabaCloud-Agent-Skills`
- [ ] Local management commands (`aliyun configure ...`, `aliyun plugin ...`, `aliyun version`) do **not** carry `--user-agent` or `--region`
- [ ] Required parameters are always provided
- [ ] Category codes use dot notation for subcategories
- [ ] Pagination uses exact `nextToken` from response
- [ ] Credentials are never read/printed
- [ ] User confirmation required before actions
- [ ] Empty results handled gracefully
- [ ] Errors provide actionable guidance
- [ ] Output formatted for readability

---

## Verification Commands

Run these commands to validate the skill:

```bash
# Test 1: List categories
aliyun agentexplorer list-categories --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills

# Test 2: Search by keyword
aliyun agentexplorer search-skills --keyword "ECS" --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills

# Test 3: Search by category
aliyun agentexplorer search-skills --category-code "computing" --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills

# Test 4: Get skill content
aliyun agentexplorer get-skill-content --skill-name "example-skill" --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills

# Test 5: Check credentials
aliyun configure list
```

All commands should execute without syntax errors (though some may return "no results" or "skill not found", which is acceptable).


path: references/category-examples.md
content: # Category Examples

This reference provides common category codes and examples to help users navigate the Alibaba Cloud Agent Skills catalog.

## How to Use This Reference

1. **Find your domain** — Locate the relevant top-level category
2. **Browse subcategories** — Check if there's a specific subcategory for your need
3. **Use the category code** — Copy the code for use in search commands

## Category Code Format

- **Top-level category**: Use the category code directly (e.g., `computing`)
- **Subcategory**: Use dot notation (e.g., `computing.ecs`)
- **Multiple categories**: Separate with commas (e.g., `computing,database`)

## Common Categories

This is a reference guide. For the complete, up-to-date list, always run:
```bash
aliyun agentexplorer list-categories --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## 1. Computing (计算)

**Category Code**: `computing`

**Description**: Skills related to computing resources and instance management.

### Subcategories

| Subcategory Code | Name | Example Use Cases |
|------------------|------|-------------------|
| `computing.ecs` | 云服务器 ECS | Instance creation, batch operations, monitoring |
| `computing.eci` | 弹性容器实例 ECI | Container instance management |
| `computing.sae` | Serverless 应用引擎 SAE | Serverless app deployment |
| `computing.fc` | 函数计算 FC | Function as a Service, serverless functions |
| `computing.ehpc` | 弹性高性能计算 EHPC | High-performance computing clusters |

### Example Searches

```bash
# All computing skills
aliyun agentexplorer search-skills \
  --category-code "computing" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Only ECS skills
aliyun agentexplorer search-skills \
  --category-code "computing.ecs" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# ECS batch operations
aliyun agentexplorer search-skills \
  --keyword "batch" \
  --category-code "computing.ecs" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## 2. Database (数据库)

**Category Code**: `database`

**Description**: Skills for database management and operations.

### Subcategories

| Subcategory Code | Name | Example Use Cases |
|------------------|------|-------------------|
| `database.rds` | 云数据库 RDS | RDS instance management, backup, migration |
| `database.polardb` | 云原生数据库 PolarDB | PolarDB operations |
| `database.mongodb` | 云数据库 MongoDB | MongoDB management |
| `database.redis` | 云数据库 Redis | Redis cache management |
| `database.memcache` | 云数据库 Memcache | Memcache operations |
| `database.oceanbase` | OceanBase | Distributed database operations |

### Example Searches

```bash
# All database skills
aliyun agentexplorer search-skills \
  --category-code "database" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# RDS backup skills
aliyun agentexplorer search-skills \
  --keyword "backup" \
  --category-code "database.rds" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Database and cache combined
aliyun agentexplorer search-skills \
  --category-code "database.rds,database.redis" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## 3. Storage (存储)

**Category Code**: `storage`

**Description**: Skills for object storage, file systems, and backup.

### Subcategories

| Subcategory Code | Name | Example Use Cases |
|------------------|------|-------------------|
| `storage.oss` | 对象存储 OSS | Object storage operations, bucket management |
| `storage.nas` | 文件存储 NAS | Network attached storage |
| `storage.oss-hdfs` | OSS-HDFS | HDFS-compatible object storage |
| `storage.cpfs` | 文件存储 CPFS | Parallel file system |
| `storage.hbr` | 混合云备份 HBR | Hybrid cloud backup |

### Example Searches

```bash
# All storage skills
aliyun agentexplorer search-skills \
  --category-code "storage" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# OSS bucket management
aliyun agentexplorer search-skills \
  --keyword "bucket" \
  --category-code "storage.oss" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Backup solutions
aliyun agentexplorer search-skills \
  --keyword "backup" \
  --category-code "storage" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## 4. Networking (网络)

**Category Code**: `networking`

**Description**: Skills for VPC, load balancers, and network management.

### Subcategories

| Subcategory Code | Name | Example Use Cases |
|------------------|------|-------------------|
| `networking.vpc` | 专有网络 VPC | VPC creation, VSwitch management |
| `networking.slb` | 负载均衡 SLB | Load balancer configuration |
| `networking.eip` | 弹性公网 IP EIP | Elastic IP management |
| `networking.nat` | NAT 网关 | NAT gateway operations |
| `networking.cdn` | CDN | Content delivery network |
| `networking.ga` | 全球加速 GA | Global acceleration |

### Example Searches

```bash
# All networking skills
aliyun agentexplorer search-skills \
  --category-code "networking" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# VPC setup
aliyun agentexplorer search-skills \
  --keyword "setup" \
  --category-code "networking.vpc" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Load balancer configuration
aliyun agentexplorer search-skills \
  --category-code "networking.slb" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## 5. Security (安全)

**Category Code**: `security`

**Description**: Skills for security management, access control, and compliance.

### Subcategories

| Subcategory Code | Name | Example Use Cases |
|------------------|------|-------------------|
| `security.ram` | 访问控制 RAM | IAM, user/role management |
| `security.kms` | 密钥管理服务 KMS | Key management, encryption |
| `security.waf` | Web 应用防火墙 WAF | Web application firewall |
| `security.ddos` | DDoS 防护 | DDoS protection |
| `security.sas` | 云安全中心 SAS | Security center operations |
| `security.saf` | 风险识别 SAF | Risk identification |

### Example Searches

```bash
# All security skills
aliyun agentexplorer search-skills \
  --category-code "security" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# RAM policy management
aliyun agentexplorer search-skills \
  --keyword "policy" \
  --category-code "security.ram" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Encryption and key management
aliyun agentexplorer search-skills \
  --category-code "security.kms" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## 6. Container (容器)

**Category Code**: `container`

**Description**: Skills for Kubernetes, container registry, and container management.

### Subcategories

| Subcategory Code | Name | Example Use Cases |
|------------------|------|-------------------|
| `container.ack` | 容器服务 Kubernetes ACK | K8s cluster management |
| `container.acr` | 容器镜像服务 ACR | Container registry operations |
| `container.eci` | 弹性容器实例 ECI | Serverless containers |
| `container.ask` | Serverless Kubernetes ASK | Serverless K8s |

### Example Searches

```bash
# All container skills
aliyun agentexplorer search-skills \
  --category-code "container" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Kubernetes deployment
aliyun agentexplorer search-skills \
  --keyword "deployment" \
  --category-code "container.ack" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Container image management
aliyun agentexplorer search-skills \
  --category-code "container.acr" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## 7. AI & Machine Learning (人工智能)

**Category Code**: `ai`

**Description**: Skills for AI services, machine learning, and model management.

### Subcategories

| Subcategory Code | Name | Example Use Cases |
|------------------|------|-------------------|
| `ai.pai` | 机器学习 PAI | Machine learning platform |
| `ai.nlp` | 自然语言处理 NLP | NLP services |
| `ai.vision` | 视觉智能 | Computer vision APIs |
| `ai.bailian` | 百炼 | Model service platform |

### Example Searches

```bash
# All AI skills
aliyun agentexplorer search-skills \
  --category-code "ai" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Machine learning workflows
aliyun agentexplorer search-skills \
  --keyword "training" \
  --category-code "ai.pai" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# NLP services
aliyun agentexplorer search-skills \
  --category-code "ai.nlp" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## 8. Big Data (大数据)

**Category Code**: `bigdata`

**Description**: Skills for data processing, analytics, and data warehousing.

### Subcategories

| Subcategory Code | Name | Example Use Cases |
|------------------|------|-------------------|
| `bigdata.maxcompute` | MaxCompute | Data warehousing, big data processing |
| `bigdata.datav` | DataV | Data visualization |
| `bigdata.emr` | E-MapReduce | Hadoop/Spark cluster management |
| `bigdata.dataworks` | DataWorks | Data development and orchestration |
| `bigdata.hologres` | Hologres | Real-time data warehouse |

### Example Searches

```bash
# All big data skills
aliyun agentexplorer search-skills \
  --category-code "bigdata" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Data warehouse operations
aliyun agentexplorer search-skills \
  --category-code "bigdata.maxcompute" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Data visualization
aliyun agentexplorer search-skills \
  --category-code "bigdata.datav" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## 9. Monitoring & Operations (监控运维)

**Category Code**: `monitoring`

**Description**: Skills for monitoring, logging, and operational management.

### Subcategories

| Subcategory Code | Name | Example Use Cases |
|------------------|------|-------------------|
| `monitoring.cms` | 云监控 CMS | Cloud monitoring, alerts |
| `monitoring.arms` | 应用实时监控 ARMS | APM, application monitoring |
| `monitoring.sls` | 日志服务 SLS | Log collection and analysis |
| `monitoring.oos` | 运维编排服务 OOS | Operation orchestration |

### Example Searches

```bash
# All monitoring skills
aliyun agentexplorer search-skills \
  --category-code "monitoring" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Alert configuration
aliyun agentexplorer search-skills \
  --keyword "alert" \
  --category-code "monitoring.cms" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Log analysis
aliyun agentexplorer search-skills \
  --category-code "monitoring.sls" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## 10. Developer Tools (开发者工具)

**Category Code**: `devtools`

**Description**: Skills for CI/CD, code management, and development workflows.

### Subcategories

| Subcategory Code | Name | Example Use Cases |
|------------------|------|-------------------|
| `devtools.cr` | 容器镜像服务 CR | Container registry |
| `devtools.rdc` | 云效 DevOps | CI/CD pipelines |
| `devtools.emas` | 移动研发平台 EMAS | Mobile development |

### Example Searches

```bash
# All developer tools
aliyun agentexplorer search-skills \
  --category-code "devtools" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# CI/CD pipeline
aliyun agentexplorer search-skills \
  --keyword "pipeline" \
  --category-code "devtools.rdc" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## Search Strategy Examples

### Example 1: Find Skills for a Specific Product

```bash
# I need skills for RDS database management
aliyun agentexplorer search-skills \
  --keyword "RDS" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Or search within database category
aliyun agentexplorer search-skills \
  --keyword "RDS" \
  --category-code "database" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Or directly search RDS subcategory
aliyun agentexplorer search-skills \
  --category-code "database.rds" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

### Example 2: Find Skills for Cross-Service Scenarios

```bash
# I need skills for VPC + ECS setup
aliyun agentexplorer search-skills \
  --keyword "VPC ECS" \
  --category-code "computing,networking" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Or search separately and combine results
aliyun agentexplorer search-skills \
  --keyword "network setup" \
  --category-code "computing.ecs" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

### Example 3: Find Skills by Feature

```bash
# I need backup-related skills across all services
aliyun agentexplorer search-skills \
  --keyword "backup" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Or narrow to database backups
aliyun agentexplorer search-skills \
  --keyword "backup" \
  --category-code "database" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

### Example 4: Browse a Domain

```bash
# I want to see all security-related skills
aliyun agentexplorer search-skills \
  --category-code "security" \
  --max-results 50 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Narrow to specific security service
aliyun agentexplorer search-skills \
  --category-code "security.ram,security.kms" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## Tips for Category Selection

### 1. Start Broad, Then Narrow

```bash
# Step 1: Browse top-level category
aliyun agentexplorer search-skills \
  --category-code "computing" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Step 2: If too many results, narrow to subcategory
aliyun agentexplorer search-skills \
  --category-code "computing.ecs" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Step 3: Add keyword for further filtering
aliyun agentexplorer search-skills \
  --keyword "batch" \
  --category-code "computing.ecs" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

### 2. Use Multiple Categories for Cross-Service Skills

```bash
# Find skills that work with both ECS and RDS
aliyun agentexplorer search-skills \
  --category-code "computing.ecs,database.rds" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

### 3. Combine Keyword with Category

```bash
# Most effective search strategy
aliyun agentexplorer search-skills \
  --keyword "monitoring" \
  --category-code "computing.ecs" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## Troubleshooting

### No Results for Category Code

**Possible causes**:
1. Category code doesn't exist (check spelling)
2. No skills in that category yet
3. Wrong separator (use dot for subcategory, comma for multiple)

**Solution**:
```bash
# List all valid categories
aliyun agentexplorer list-categories --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Verify the correct category code
```

### Too Many Results

**Solution**: Add filters
```bash
# Add keyword filter
aliyun agentexplorer search-skills \
  --keyword "specific-feature" \
  --category-code "category" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Reduce to subcategory
aliyun agentexplorer search-skills \
  --category-code "category.subcategory" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

### Not Sure Which Category

**Solution**: Use keyword-only search first
```bash
# Search by product name only
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Check the categoryName and subCategoryName in results
# Then refine with category filter
```

---

## Quick Reference Table

| I Want To... | Search Strategy |
|--------------|-----------------|
| Find all skills for a product | `--keyword "ProductName"` |
| Browse a service category | `--category-code "category"` |
| Find specific subcategory skills | `--category-code "category.subcategory"` |
| Search across multiple categories | `--category-code "cat1,cat2,cat3"` |
| Find cross-service solutions | `--keyword "feature" --category-code "cat1,cat2"` |
| Narrow search results | Add both `--keyword` and `--category-code` |
| See all available categories | `aliyun agentexplorer list-categories --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills` |

---

## Notes

- **Always use `list-categories` first**: Get the most up-to-date category structure
- **Category names may change**: Official names and codes may be updated over time
- **Chinese and English**: Many skills support both language descriptions
- **Skill count varies**: Some categories have many skills, others have few
- **New categories added regularly**: Check back for new categories and skills


path: references/cli-installation-guide.md
content: # Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

> **Aliyun CLI 3.3.3+**: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

## Installation

### macOS

**Using Homebrew (Recommended)**
```bash
brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version
```

**Using Binary**
```bash
# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version
```

### Linux

**Debian/Ubuntu**
```bash
# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version
```

**CentOS/RHEL**
```bash
# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version
```

**ARM64 Architecture**
```bash
# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/
```

### Windows

**Using Binary**
1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip
2. Extract the ZIP file
3. Add the directory to your PATH environment variable
4. Open new Command Prompt or PowerShell
5. Verify: `aliyun version`

**Using PowerShell**
```powershell
# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version
```

## Configuration

### Quick Start

```bash
aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou
```

All `aliyun configure` commands support non-interactive flags, which is the recommended approach —
it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

**Where to Get Access Keys**

1. Log in to Aliyun Console: https://ram.console.aliyun.com/
2. Navigate to: AccessKey Management
3. Create a new AccessKey pair
4. Save the secret immediately — it's only shown once

### Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

#### 1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

```bash
aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou
```

Configuration is stored in `~/.aliyun/config.json`:

```json
{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}
```

#### 2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

```bash
aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou
```

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

#### 3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

```bash
aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou
```

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

#### 4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

```bash
aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou
```

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

#### 5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

```bash
aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou
```

#### 6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

```bash
aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou
```

### Environment Variables

**Highest priority** - overrides config file

**Access Key Mode**
```bash
export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou
```

**STS Token Mode**
```bash
export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou
```

**ECS RAM Role Mode**
```bash
export ALIBABA_CLOUD_ECS_METADATA=role_name
```

**Use Case**:
- CI/CD pipelines
- Docker containers
- Temporary credential override

### Managing Multiple Profiles

**Create Named Profiles**

```bash
aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai
```

**Use Specific Profile**

```bash
aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA
```

**List and Switch Profiles**

```bash
aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile
```

### Credential Priority

Credentials are loaded in this order (first found wins):

1. **Command-line flag**: `--profile <name>`
2. **Environment variable**: `ALIBABA_CLOUD_PROFILE`
3. **Environment credentials**: `ALIBABA_CLOUD_ACCESS_KEY_ID`, etc.
4. **Configuration file**: `~/.aliyun/config.json` (current profile)
5. **ECS Instance RAM Role**: If running on ECS with attached role

## Verification

### Test Authentication

```bash
# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions
```

**If successful**, you'll see:
```json
{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}
```

**If failed**, you'll see error messages:
- `InvalidAccessKeyId.NotFound` - Wrong Access Key ID
- `SignatureDoesNotMatch` - Wrong Access Key Secret
- `InvalidSecurityToken.Expired` - STS token expired (for StsToken mode)
- `Forbidden.RAM` - Insufficient permissions

### Debug Configuration

```bash
# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode
```

## Security Best Practices

### 1. Use RAM Users (Not Root Account)

❌ **Don't**: Use Aliyun root account credentials
✅ **Do**: Create RAM users with specific permissions

```bash
# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys
```

### 2. Principle of Least Privilege

Grant only the minimum permissions needed:

```bash
# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess
```

### 3. Rotate Access Keys Regularly

```bash
# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console
```

### 4. Use STS Tokens for Temporary Access

```bash
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou
```

### 5. Use ECS RAM Roles When Possible

```bash
aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou
```

### 6. Never Commit Credentials

```bash
# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead
```

### 7. Secure Config File

```bash
# Restrict permissions
chmod 600 ~/.aliyun/config.json
```

## Troubleshooting

### Issue: Command Not Found

```bash
# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH
```

### Issue: Authentication Failed

```bash
# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active
```

### Issue: Permission Denied

```bash
# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations
```

### Issue: STS Token Expired

```bash
# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou
```

### Issue: Wrong Region

```bash
# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai
```

## Advanced Configuration

### Custom Endpoint

```bash
# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com
```

### Proxy Settings

```bash
# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com
```

### Timeout Settings

```bash
# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30
```

## Next Steps

After installation and configuration:

1. **Install plugins** for services you need (v3.3.3+ supports all published product plugins):
   ```bash
   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote
   ```

2. **Explore commands**:
   ```bash
   aliyun ecs --help
   aliyun fc --help
   ```

3. **Read documentation**:
   - [Command Syntax Guide](./command-syntax.md)
   - [Global Flags Reference](./global-flags.md)
   - [Common Scenarios](./common-scenarios.md)

## References

- Official Documentation: https://help.aliyun.com/zh/cli/
- RAM Console: https://ram.console.aliyun.com/
- Access Key Management: https://ram.console.aliyun.com/manage/ak
- Plugin Repository: https://github.com/aliyun/aliyun-cli


path: references/npx-skills-agents.md
content: # Supported `--agent` Values for `npx skills add`

| Value | Agent Client |
|---|---|
| `augment` | Augment |
| `bob` | Bob |
| `claude-code` | Claude Code |
| `openclaw` | OpenClaw |
| `codebuddy` | CodeBuddy |
| `command-code` | Command Code |
| `continue` | Continue |
| `cortex` | Cortex |
| `crush` | Crush |
| `droid` | Droid |
| `goose` | Goose |
| `junie` | Junie |
| `iflow-cli` | iFlow CLI |
| `kilo` | Kilo |
| `kiro-cli` | Kiro CLI |
| `kode` | Kode |
| `mcpjam` | MCPJam |
| `mistral-vibe` | Mistral Vibe |
| `mux` | Mux |
| `openhands` | OpenHands |
| `pi` | Pi |
| `qoder` | Qoder |
| `qwen-code` | Qwen Code |
| `roo` | Roo |
| `trae` | Trae |
| `trae-cn` | Trae CN |
| `windsurf` | Windsurf |
| `zencoder` | Zencoder |
| `neovate` | Neovate |
| `pochi` | Pochi |
| `adal` | Adal |


path: references/ram-policies.md
content: # RAM Policies for alibabacloud-find-skills

This document lists all RAM permissions required by the `alibabacloud-find-skills` skill.

## Required Permissions

The skill uses the following AgentExplorer service APIs:

| API Operation | Description | Permission Required |
|---------------|-------------|---------------------|
| `ListCategories` | List all available skill categories | `agentexplorer:ListCategories` |
| `SearchSkills` | Search skills by keyword and category | `agentexplorer:SearchSkills` |
| `GetSkillContent` | Retrieve detailed skill content | `agentexplorer:GetSkillContent` |

## Minimal RAM Policy

```json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "agentexplorer:ListCategories",
        "agentexplorer:SearchSkills",
        "agentexplorer:GetSkillContent"
      ],
      "Resource": "*"
    }
  ]
}
```

## Policy Explanation

### agentexplorer:ListCategories

- **Purpose**: Retrieve the complete catalog of skill categories and subcategories
- **Resource**: Public catalog, no resource-specific restrictions
- **Risk Level**: Low (read-only, public data)

### agentexplorer:SearchSkills

- **Purpose**: Query skills based on keywords, categories, or filters
- **Resource**: Public skills repository, no resource-specific restrictions
- **Risk Level**: Low (read-only, public data)

### agentexplorer:GetSkillContent

- **Purpose**: Fetch the full markdown content of a specific skill
- **Resource**: Public skill content, no resource-specific restrictions
- **Risk Level**: Low (read-only, public data)

## How to Apply This Policy

### Option 1: Via Alibaba Cloud Console

1. Log in to [RAM Console](https://ram.console.aliyun.com/)
2. Navigate to **Permissions** > **Policies**
3. Click **Create Policy**
4. Select **JSON** tab
5. Paste the minimal RAM policy JSON above
6. Name the policy (e.g., `AgentExplorerReadOnly`)
7. Click **OK**
8. Attach the policy to your RAM user or role

### Option 2: Via Aliyun CLI

```bash
# Create the policy
aliyun ram create-policy \
  --policy-name AgentExplorerReadOnly \
  --policy-document '{
    "Version": "1",
    "Statement": [{
      "Effect": "Allow",
      "Action": [
        "agentexplorer:ListCategories",
        "agentexplorer:SearchSkills",
        "agentexplorer:GetSkillContent"
      ],
      "Resource": "*"
    }]
  }' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Attach to RAM user
aliyun ram attach-policy-to-user \
  --policy-name AgentExplorerReadOnly \
  --policy-type Custom \
  --user-name <your-ram-user-name> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

## Permission Verification

To verify that your account has the required permissions:

```bash
# Test ListCategories permission
aliyun agentexplorer list-categories --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Test SearchSkills permission
aliyun agentexplorer search-skills --keyword "test" --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Test GetSkillContent permission
aliyun agentexplorer get-skill-content --skill-name "example-skill" --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

If any command returns a permission error (e.g., `403 Forbidden`, `NoPermission`), you need to apply the RAM policy above.

## Common Permission Errors

### Error: "User not authorized to operate on the specified resource"

**Cause**: Missing one or more required permissions.

**Solution**: Apply the complete RAM policy shown above.

### Error: "The specified action is not found"

**Cause**: AgentExplorer service may not be available in your region or account type.

**Solution**: Verify that you're using a supported account type and region.

## Security Best Practices

1. **Read-only access**: These permissions only allow reading public data, no write operations
2. **Minimal scope**: Only grants access to AgentExplorer APIs, not other services
3. **No resource restrictions needed**: Skills catalog is public, no need for resource-level filtering
4. **Suitable for automation**: Safe to use in CI/CD pipelines or automated scripts
5. **No sensitive data**: Skills content is public documentation, no confidential information

## Permission Escalation

This skill does **not** require any additional permissions beyond the minimal set listed above. If you encounter permission errors after applying this policy, it may indicate:

- Account-level restrictions (contact your administrator)
- Service availability issues (check Alibaba Cloud service status)
- Incorrect policy attachment (verify policy is attached to correct user/role)

## Related Documentation

- [Alibaba Cloud RAM User Guide](https://www.alibabacloud.com/help/ram)
- [RAM Policy Syntax](https://www.alibabacloud.com/help/ram/user-guide/policy-structure-and-syntax)
- [AgentExplorer Service Documentation](https://www.alibabacloud.com/help/agentexplorer)


path: references/related-commands.md
content: # Related CLI Commands

Complete reference for all Aliyun CLI commands used in the `alibabacloud-find-skills` skill.

## Command Summary

| Command | Purpose | Required Parameters |
|---------|---------|---------------------|
| `aliyun agentexplorer list-categories` | List all skill categories | None |
| `aliyun agentexplorer search-skills` | Search for skills | None (keyword or category-code recommended) |
| `aliyun agentexplorer get-skill-content` | Get skill details | `--skill-name` (required) |
| `aliyun plugin install` | Install CLI plugins | `--names` (required) |
| `aliyun configure list` | Check credential configuration | None |
| `aliyun version` | Check CLI version | None |

---

## 1. aliyun agentexplorer list-categories

**Description**: List all available skill categories and subcategories.

**Syntax**:
```bash
aliyun agentexplorer list-categories [flags]
```

**Parameters**: None required.

**Common Flags**:
- `--region <region>` — **Required**: API region (e.g., `cn-hangzhou`)
- `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills` — **Required**: Identify requests from this skill
- `--cli-query <jmespath>` — Filter output using JMESPath expression
- `-q, --quiet` — Suppress output

**Example Usage**:
```bash
# List all categories
aliyun agentexplorer list-categories \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# List categories with JMESPath filtering
aliyun agentexplorer list-categories \
  --cli-query "categories[].categoryName" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

**Output Structure**:
```json
{
  "categories": [
    {
      "categoryCode": "computing",
      "categoryName": "计算",
      "subCategories": [
        {
          "categoryCode": "ecs",
          "categoryName": "云服务器 ECS"
        }
      ]
    }
  ]
}
```

---

## 2. aliyun agentexplorer search-skills

**Description**: Search for Alibaba Cloud Agent Skills by keyword, category, or both.

**Syntax**:
```bash
aliyun agentexplorer search-skills [flags]
```

**Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--keyword` | string | No | Search keyword (product name, feature, description) |
| `--category-code` | string | No | Category code filter (comma-separated for multiple) |
| `--max-results` | int | No | Maximum results per page (1-100, default: 20) |
| `--next-token` | string | No | Pagination token from previous response |
| `--skip` | int | No | Number of items to skip |

**Common Flags**:
- `--region <region>` — **Required**: API region (e.g., `cn-hangzhou`)
- `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills` — **Required**: Identify requests from this skill
- `--cli-query <jmespath>` — Filter output using JMESPath expression
- `--pager` — Auto-merge all pages
- `-q, --quiet` — Suppress output

**Example Usage**:

```bash
# Search by keyword only
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Search by category only
aliyun agentexplorer search-skills \
  --category-code "computing" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Search by subcategory (dot notation)
aliyun agentexplorer search-skills \
  --category-code "computing.ecs" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Combined keyword and category
aliyun agentexplorer search-skills \
  --keyword "backup" \
  --category-code "database.rds" \
  --max-results 10 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Multiple categories
aliyun agentexplorer search-skills \
  --category-code "computing,database" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Paginated search (page 2)
aliyun agentexplorer search-skills \
  --keyword "monitoring" \
  --max-results 20 \
  --next-token "<token-from-previous-response>" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Skip first N results
aliyun agentexplorer search-skills \
  --keyword "OSS" \
  --skip 10 \
  --max-results 20 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Filter results with JMESPath
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --cli-query "skills[].skillName" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

**Output Structure**:
```json
{
  "skills": [
    {
      "skillName": "alibabacloud-ecs-batch-command",
      "displayName": "ECS 批量命令执行",
      "description": "批量在多台 ECS 实例上执行命令",
      "categoryCode": "computing",
      "categoryName": "计算",
      "subCategoryCode": "ecs",
      "subCategoryName": "云服务器 ECS",
      "installCount": 245,
      "likeCount": 18
    }
  ],
  "totalCount": 100,
  "nextToken": "eyJwYWdlIjoyfQ=="
}
```

---

## 3. aliyun agentexplorer get-skill-content

**Description**: Retrieve the complete markdown content of a specific skill.

**Syntax**:
```bash
aliyun agentexplorer get-skill-content --skill-name <name> [flags]
```

**Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--skill-name` | string | **Yes** | Unique skill identifier (from search results) |

**Common Flags**:
- `--region <region>` — **Required**: API region (e.g., `cn-hangzhou`)
- `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills` — **Required**: Identify requests from this skill
- `--cli-query <jmespath>` — Filter output using JMESPath expression
- `-q, --quiet` — Suppress output

**Example Usage**:

```bash
# Get skill content
aliyun agentexplorer get-skill-content \
  --skill-name "alibabacloud-ecs-batch-command" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Get only the description field
aliyun agentexplorer get-skill-content \
  --skill-name "alibabacloud-ecs-batch-command" \
  --cli-query "description" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

**Output Structure**:
```json
{
  "skillName": "alibabacloud-ecs-batch-command",
  "displayName": "ECS 批量命令执行",
  "description": "批量在多台 ECS 实例上执行命令",
  "content": "---\nname: alibabacloud-ecs-batch-command\n...",
  "categoryCode": "computing",
  "categoryName": "计算",
  "subCategoryCode": "ecs",
  "subCategoryName": "云服务器 ECS",
  "installCount": 245,
  "likeCount": 18,
  "createTime": "2024-01-15T10:30:00Z",
  "updateTime": "2024-03-20T14:45:00Z"
}
```

---

## 4. aliyun plugin install

**Description**: Install Aliyun CLI plugins.

**Syntax**:
```bash
aliyun plugin install --names <plugin-name> [flags]
```

**Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--names` | string | **Yes** | Plugin name to install |

**Example Usage**:

```bash
# Install agentexplorer plugin
aliyun plugin install --names aliyun-cli-agentexplorer

# Install multiple plugins (comma-separated)
aliyun plugin install --names aliyun-cli-agentexplorer,aliyun-cli-another-plugin
```

---

## 5. aliyun configure list

**Description**: List all configured credentials and profiles.

**Syntax**:
```bash
aliyun configure list [flags]
```

**Parameters**: None required.

> **Note**: `aliyun configure list` is a local management command. It does **not** support `--user-agent` or `--region` — do not pass them.

**Example Usage**:

```bash
# List all profiles
aliyun configure list
```

**Output Example**:
```
Profile   | Credential         | Valid   | Region           | Language
--------- | ------------------ | ------- | ---------------- | --------
default * | AK:***abc          | Valid   | cn-hangzhou      | en
profile1  | STS:***def         | Valid   | cn-beijing       | zh
```

---

## 6. aliyun version

**Description**: Display Aliyun CLI version.

**Syntax**:
```bash
aliyun version
```

**Parameters**: None.

**Example Usage**:

```bash
aliyun version
```

**Output Example**:
```
3.3.2
```

---

## 7. aliyun configure set

**Description**: Configure CLI settings (used for enabling auto plugin install). **Run this only after authentication is complete** (verify with `aliyun configure list`).

**Syntax**:
```bash
aliyun configure set [flags]
```

**Common Flags**:
- `--auto-plugin-install <bool>` — Enable/disable automatic plugin installation

> **Note**: `aliyun configure set` is a local management command. It does **not** support `--user-agent` — do not pass it.

**Example Usage**:

```bash
# Enable automatic plugin installation (requires an authenticated profile)
aliyun configure set --auto-plugin-install true
```

---

## Advanced Usage Patterns

### Pattern 1: Search with Auto-pagination

```bash
# Automatically fetch all pages
aliyun agentexplorer search-skills \
  --keyword "monitoring" \
  --pager \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

### Pattern 2: Filter Output with JMESPath

```bash
# Get only skill names from search results
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --cli-query "skills[].skillName" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Get skills with install count > 100
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --cli-query "skills[?installCount > \`100\`]" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

### Pattern 3: Hierarchical Category Search

```bash
# Search all computing skills
aliyun agentexplorer search-skills \
  --category-code "computing" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Search only ECS skills (computing.ecs)
aliyun agentexplorer search-skills \
  --category-code "computing.ecs" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

### Pattern 4: Multi-category Search

```bash
# Search across multiple top-level categories
aliyun agentexplorer search-skills \
  --category-code "computing,database,storage" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills

# Search across multiple subcategories
aliyun agentexplorer search-skills \
  --category-code "computing.ecs,database.rds,storage.oss" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## Troubleshooting Commands

### Check Plugin Installation

```bash
# List installed plugins
aliyun plugin list

# Check if agentexplorer is installed
aliyun plugin list | grep agentexplorer
```

### Verify Credentials

```bash
# Check if credentials are configured (no --user-agent / --region — local command)
aliyun configure list

# Test API access
aliyun agentexplorer list-categories \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

### Debug Mode

```bash
# Enable debug logging
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --log-level DEBUG \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

### Dry Run Mode

```bash
# Preview request without sending
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --cli-dry-run \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
```

---

## Command Comparison Table

| Task | Command | Key Parameters |
|------|---------|----------------|
| Browse all categories | `list-categories` | None |
| Search by keyword | `search-skills` | `--keyword` |
| Search by category | `search-skills` | `--category-code` |
| Combined search | `search-skills` | `--keyword`, `--category-code` |
| Get skill details | `get-skill-content` | `--skill-name` |
| Paginate results | `search-skills` | `--max-results`, `--next-token` |
| Install plugin | `plugin install` | `--names` |
| Check credentials | `configure list` | None |

---

## Notes

- **Region Required**: Every `aliyun agentexplorer` command MUST include `--region <region>` (e.g., `--region cn-hangzhou`). Without it the call fails.
- **User-Agent Required (API only)**: Every `aliyun agentexplorer` command MUST include `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills`. Local management commands (`aliyun configure ...`, `aliyun plugin ...`, `aliyun version`) do **not** support `--user-agent`.
- **Plugin Mode**: Commands use plugin mode format (lowercase with hyphens)
- **Pagination**: Use `--next-token` from response for subsequent pages
- **Category Codes**: Use dot notation for subcategories (e.g., `computing.ecs`)
- **Multiple Values**: Comma-separate for multiple category codes
- **JMESPath**: Use `--cli-query` for client-side filtering


path: references/verification-method.md
content: # Verification Methods

This document provides detailed verification steps for each workflow in the `alibabacloud-find-skills` skill.

## Overview

After executing each workflow, verify success by checking:

1. Command exit code (0 = success)
2. Response structure matches expected format
3. Data content is valid and non-empty
4. Appropriate error handling for edge cases

---

## Workflow 1: Search Skills by Keyword

### Success Criteria

✅ **Command executes successfully**

```bash
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --max-results 20 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
echo "Exit code: $?"  # Should be 0
```

✅ **Response contains expected fields**

```bash
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --cli-query "skills[0].skillName" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
# Should return a valid skill name, not null
```

✅ **Skills array is not empty** (when results exist)

```bash
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --cli-query "length(skills)" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
# Should return a number > 0
```

✅ **Each skill has required fields**

- `skillName` — Non-empty string
- `displayName` — Non-empty string
- `description` — Non-empty string
- `categoryName` — Non-empty string
- `installCount` — Non-negative integer
- `likeCount` — Non-negative integer

### Verification Script

```bash
#!/bin/bash
KEYWORD="ECS"

echo "=== Verifying Search Skills by Keyword ==="

# Execute search
RESULT=$(aliyun agentexplorer search-skills \
  --keyword "$KEYWORD" \
  --max-results 5 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills 2>&1)

EXIT_CODE=$?

# Check exit code
if [ $EXIT_CODE -eq 0 ]; then
  echo "✅ Command executed successfully (exit code: $EXIT_CODE)"
else
  echo "❌ Command failed (exit code: $EXIT_CODE)"
  echo "$RESULT"
  exit 1
fi

# Check if result contains skills array
if echo "$RESULT" | grep -q '"skills"'; then
  echo "✅ Response contains 'skills' array"
else
  echo "❌ Response missing 'skills' array"
  exit 1
fi

# Check skill count
SKILL_COUNT=$(echo "$RESULT" | grep -o '"skillName"' | wc -l)
if [ $SKILL_COUNT -gt 0 ]; then
  echo "✅ Found $SKILL_COUNT skills"
else
  echo "⚠️  No skills found for keyword '$KEYWORD'"
fi

echo "=== Verification Complete ==="
```

---

## Workflow 2: Browse Skills by Category

### Success Criteria

✅ **List categories succeeds**

```bash
aliyun agentexplorer list-categories \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
echo "Exit code: $?"  # Should be 0
```

✅ **Categories structure is valid**

```bash
aliyun agentexplorer list-categories \
  --cli-query "categories[0].categoryCode" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
# Should return a valid category code
```

✅ **Search by category returns filtered results**

```bash
aliyun agentexplorer search-skills \
  --category-code "computing" \
  --cli-query "skills[0].categoryCode" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
# Should return "computing"
```

### Verification Script

```bash
#!/bin/bash

echo "=== Verifying Browse Skills by Category ==="

# Step 1: List categories
echo "Step 1: Listing categories..."
CATEGORIES=$(aliyun agentexplorer list-categories \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills 2>&1)

if [ $? -eq 0 ]; then
  echo "✅ list-categories succeeded"
else
  echo "❌ list-categories failed"
  echo "$CATEGORIES"
  exit 1
fi

# Extract first category code
CATEGORY_CODE=$(echo "$CATEGORIES" | grep -o '"categoryCode":"[^"]*"' | head -1 | cut -d'"' -f4)

if [ -n "$CATEGORY_CODE" ]; then
  echo "✅ Found category code: $CATEGORY_CODE"
else
  echo "❌ No category codes found"
  exit 1
fi

# Step 2: Search by category
echo "Step 2: Searching skills in category '$CATEGORY_CODE'..."
SKILLS=$(aliyun agentexplorer search-skills \
  --category-code "$CATEGORY_CODE" \
  --max-results 5 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills 2>&1)

if [ $? -eq 0 ]; then
  echo "✅ search-skills by category succeeded"
else
  echo "❌ search-skills by category failed"
  echo "$SKILLS"
  exit 1
fi

# Verify results belong to the category
if echo "$SKILLS" | grep -q "\"categoryCode\":\"$CATEGORY_CODE\""; then
  echo "✅ Results correctly filtered by category"
else
  echo "⚠️  Results may not be filtered correctly"
fi

echo "=== Verification Complete ==="
```

---

## Workflow 3: Get Skill Details

### Success Criteria

✅ **Command succeeds with valid skill name**

```bash
aliyun agentexplorer get-skill-content \
  --skill-name "alibabacloud-ecs-batch-command" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
echo "Exit code: $?"  # Should be 0
```

✅ **Response contains content field**

```bash
aliyun agentexplorer get-skill-content \
  --skill-name "alibabacloud-ecs-batch-command" \
  --cli-query "content" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
# Should return non-empty markdown content
```

✅ **Content is valid markdown**

- Starts with `---` (YAML frontmatter)
- Contains `name:` field
- Contains `description:` field

### Verification Script

```bash
#!/bin/bash

echo "=== Verifying Get Skill Details ==="

# First, search for a skill to get a valid skill name
echo "Step 1: Finding a valid skill name..."
SEARCH_RESULT=$(aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --max-results 1 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills 2>&1)

SKILL_NAME=$(echo "$SEARCH_RESULT" | grep -o '"skillName":"[^"]*"' | head -1 | cut -d'"' -f4)

if [ -z "$SKILL_NAME" ]; then
  echo "❌ Could not find a valid skill name"
  exit 1
fi

echo "✅ Found skill name: $SKILL_NAME"

# Step 2: Get skill content
echo "Step 2: Retrieving skill content..."
CONTENT=$(aliyun agentexplorer get-skill-content \
  --skill-name "$SKILL_NAME" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills 2>&1)

if [ $? -eq 0 ]; then
  echo "✅ get-skill-content succeeded"
else
  echo "❌ get-skill-content failed"
  echo "$CONTENT"
  exit 1
fi

# Verify content field exists and is not empty
if echo "$CONTENT" | grep -q '"content"'; then
  echo "✅ Response contains 'content' field"
else
  echo "❌ Response missing 'content' field"
  exit 1
fi

# Extract content and check for markdown frontmatter
MARKDOWN_CONTENT=$(echo "$CONTENT" | grep -o '"content":"[^"]*"' | cut -d'"' -f4)

if echo "$MARKDOWN_CONTENT" | grep -q '---'; then
  echo "✅ Content appears to be valid markdown"
else
  echo "⚠️  Content may not be valid markdown"
fi

echo "=== Verification Complete ==="
```

---

## Workflow 4: Install a Skill

### Success Criteria

✅ **Installation command succeeds**

```bash
npx skills add https://github.com/aliyun/alibabacloud-aiops-skills --skill <skill-name> --full-depth
echo "Exit code: $?"  # Should be 0
```

✅ **Skill appears in Claude Code skills list**

```bash
# Verify skill is installed (implementation-specific)
# Check in Claude Code UI or skills directory
```

### Verification Steps

1. **Before Installation**: Check that skill is not already installed
2. **During Installation**: Monitor output for errors
3. **After Installation**: Verify skill is available
4. **Test Skill**: Trigger the skill to ensure it works

### Manual Verification Checklist

- [ ] Installation command completed without errors
- [ ] Skill appears in Claude Code skills list
- [ ] Skill can be triggered with appropriate keywords
- [ ] Skill loads successfully when triggered
- [ ] Skill's functions work as expected

---

## Workflow 5: Combined Search (Keyword + Category)

### Success Criteria

✅ **Combined search executes successfully**

```bash
aliyun agentexplorer search-skills \
  --keyword "backup" \
  --category-code "database.rds" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
echo "Exit code: $?"  # Should be 0
```

✅ **Results match both filters**

- Each result's `categoryCode` or `subCategoryCode` matches the filter
- Each result's `displayName` or `description` contains keyword (case-insensitive)

### Verification Script

```bash
#!/bin/bash

KEYWORD="backup"
CATEGORY="database"

echo "=== Verifying Combined Search ==="

# Execute combined search
RESULT=$(aliyun agentexplorer search-skills \
  --keyword "$KEYWORD" \
  --category-code "$CATEGORY" \
  --max-results 10 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills 2>&1)

if [ $? -eq 0 ]; then
  echo "✅ Combined search succeeded"
else
  echo "❌ Combined search failed"
  echo "$RESULT"
  exit 1
fi

# Check if results contain the category
if echo "$RESULT" | grep -q "\"categoryCode\":\"$CATEGORY\""; then
  echo "✅ Results correctly filtered by category '$CATEGORY'"
else
  echo "⚠️  No results with category '$CATEGORY' found"
fi

# Count results
SKILL_COUNT=$(echo "$RESULT" | grep -o '"skillName"' | wc -l)
echo "Found $SKILL_COUNT skills matching both filters"

echo "=== Verification Complete ==="
```

---

## Workflow 6: Paginated Search

### Success Criteria

✅ **First page returns results and nextToken**

```bash
RESULT=$(aliyun agentexplorer search-skills \
  --keyword "monitoring" \
  --max-results 5 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills)

echo "$RESULT" | grep -q '"nextToken"'
# Should find nextToken if more results exist
```

✅ **Second page uses nextToken correctly**

```bash
NEXT_TOKEN=$(echo "$RESULT" | grep -o '"nextToken":"[^"]*"' | cut -d'"' -f4)

aliyun agentexplorer search-skills \
  --keyword "monitoring" \
  --max-results 5 \
  --next-token "$NEXT_TOKEN" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills
# Should return different results
```

✅ **No duplicate results across pages**

### Verification Script

```bash
#!/bin/bash

KEYWORD="ECS"
PAGE_SIZE=5

echo "=== Verifying Paginated Search ==="

# Page 1
echo "Fetching page 1..."
PAGE1=$(aliyun agentexplorer search-skills \
  --keyword "$KEYWORD" \
  --max-results $PAGE_SIZE \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills 2>&1)

if [ $? -ne 0 ]; then
  echo "❌ Page 1 fetch failed"
  exit 1
fi

echo "✅ Page 1 fetched successfully"

# Extract nextToken
NEXT_TOKEN=$(echo "$PAGE1" | grep -o '"nextToken":"[^"]*"' | head -1 | cut -d'"' -f4)

if [ -z "$NEXT_TOKEN" ]; then
  echo "⚠️  No nextToken found (may be last page)"
  echo "=== Verification Complete ==="
  exit 0
fi

echo "✅ Found nextToken: ${NEXT_TOKEN:0:20}..."

# Page 2
echo "Fetching page 2..."
PAGE2=$(aliyun agentexplorer search-skills \
  --keyword "$KEYWORD" \
  --max-results $PAGE_SIZE \
  --next-token "$NEXT_TOKEN" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills 2>&1)

if [ $? -eq 0 ]; then
  echo "✅ Page 2 fetched successfully"
else
  echo "❌ Page 2 fetch failed"
  exit 1
fi

# Check for different skill names
SKILLS_PAGE1=$(echo "$PAGE1" | grep -o '"skillName":"[^"]*"' | cut -d'"' -f4 | sort)
SKILLS_PAGE2=$(echo "$PAGE2" | grep -o '"skillName":"[^"]*"' | cut -d'"' -f4 | sort)

if [ "$SKILLS_PAGE1" != "$SKILLS_PAGE2" ]; then
  echo "✅ Page 2 contains different results from page 1"
else
  echo "⚠️  Pages may contain duplicate results"
fi

echo "=== Verification Complete ==="
```

---

## General Verification Checklist

Use this checklist after implementing any workflow:

### Command Execution

- [ ] Command exits with code 0 on success
- [ ] Command exits with non-zero code on error
- [ ] Error messages are clear and actionable

### Response Format

- [ ] Response is valid JSON
- [ ] Response contains expected top-level keys
- [ ] All required fields are present
- [ ] Field types match expected types (string, int, array, etc.)

### Data Validity

- [ ] String fields are non-empty when expected
- [ ] Numeric fields are non-negative
- [ ] Array fields contain valid elements
- [ ] Nested objects have correct structure

### Edge Cases

- [ ] Empty results handled gracefully (no error)
- [ ] Invalid parameters return appropriate errors
- [ ] Missing required parameters return clear error messages
- [ ] Pagination works correctly at boundaries

### User Experience

- [ ] Results are displayed in user-friendly format
- [ ] Tables align properly
- [ ] Important information is highlighted
- [ ] Next steps are clear to the user

---

## Automated Test Suite

Create a comprehensive test script:

```bash
#!/bin/bash

# Test suite for alibabacloud-find-skills

set -e  # Exit on first error

echo "========================================"
echo "  alibabacloud-find-skills Test Suite"
echo "========================================"

# Test 1: List Categories
echo -e "\n[Test 1] List Categories"
aliyun agentexplorer list-categories \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills \
  --cli-query "categories[0].categoryCode" > /dev/null
echo "✅ PASS"

# Test 2: Search by Keyword
echo -e "\n[Test 2] Search by Keyword"
aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --max-results 5 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills \
  --cli-query "skills[0].skillName" > /dev/null
echo "✅ PASS"

# Test 3: Search by Category
echo -e "\n[Test 3] Search by Category"
aliyun agentexplorer search-skills \
  --category-code "computing" \
  --max-results 5 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills \
  --cli-query "skills[0].categoryCode" > /dev/null
echo "✅ PASS"

# Test 4: Combined Search
echo -e "\n[Test 4] Combined Search"
aliyun agentexplorer search-skills \
  --keyword "backup" \
  --category-code "database" \
  --max-results 5 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills > /dev/null
echo "✅ PASS"

# Test 5: Get Skill Content
echo -e "\n[Test 5] Get Skill Content"
SKILL_NAME=$(aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --max-results 1 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills \
  --cli-query "skills[0].skillName" 2>/dev/null | tr -d '"' | tr -d '\n')

if [ -n "$SKILL_NAME" ]; then
  aliyun agentexplorer get-skill-content \
    --skill-name "$SKILL_NAME" \
    --region cn-hangzhou \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills \
    --cli-query "content" > /dev/null
  echo "✅ PASS"
else
  echo "⚠️  SKIP (no skills found)"
fi

# Test 6: Pagination
echo -e "\n[Test 6] Pagination"
RESULT=$(aliyun agentexplorer search-skills \
  --keyword "ECS" \
  --max-results 2 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-find-skills 2>/dev/null)

if echo "$RESULT" | grep -q '"nextToken"'; then
  echo "✅ PASS"
else
  echo "⚠️  SKIP (no pagination needed)"
fi

echo -e "\n========================================"
echo "  All Tests Completed Successfully!"
echo "========================================"
```

Save as `test-skill.sh` and run with:

```bash
chmod +x test-skill.sh
./test-skill.sh
```

---

## Troubleshooting Verification Failures

### Issue: Command returns non-zero exit code

**Check**:

1. Credentials configured: `aliyun configure list` (local command — does **not** support `--user-agent` or `--region`)
2. Plugin installed: `aliyun plugin list | grep agentexplorer`
3. CLI version: `aliyun version` (should be >= 3.3.3)
4. Network connectivity: `ping api.aliyun.com`

### Issue: Response missing expected fields

**Check**:

1. CLI version is up-to-date
2. Plugin version is latest: `aliyun plugin list`
3. API version changes (check official docs)

### Issue: No results returned

**Check**:

1. Keyword spelling
2. Category code validity
3. Try broader search terms
4. Check if any skills exist in category

---

## Success Metrics

Track these metrics to assess skill effectiveness:

| Metric                    | Target      | Measurement                              |
| ------------------------- | ----------- | ---------------------------------------- |
| Command success rate      | > 99%       | Exit code 0 / total commands             |
| Average response time     | < 3 seconds | Time to receive response                 |
| Empty results rate        | < 20%       | Searches with 0 results / total searches |
| Installation success rate | > 95%       | Successful installs / install attempts   |
| User satisfaction         | > 4/5       | User feedback rating                     |

---

## Continuous Monitoring

Set up periodic checks:

```bash
# Cron job example (run daily at 2 AM)
0 2 * * * /path/to/test-skill.sh >> /var/log/skill-tests.log 2>&1
```

Monitor for:

- API availability
- Response time degradation
- New error patterns
- Skill catalog updates


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)