Alibabacloud Find Skills

[!IMPORTANT]

For any Alibaba Cloud query or management task:

1. Search — use this skill (alibabacloud-find-skills) to find the relevant Skill(s).

2. Install — install the selected Skill(s) only when the user asks to install or use them to complete the task.

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 from the AgentExplorer catalog.

Scenario Description

This skill enables users to:

1. Search Skills — Find Alibaba Cloud Agent Skills by intent phrase, keyword, category listing, or combined semantic search 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 when installation is requested

Architecture: curl + AgentExplorer HTTP API → Skills Repository

Discovery uses the AgentExplorer HTTP API directly through curl; do not use Aliyun CLI or install/update the agentexplorer CLI plugin for search, browse, or detail workflows.

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"

AgentExplorer HTTP API

Base URL: https://agentexplorer.aliyuncs.com

Every AgentExplorer HTTP request must include these headers.

# Bash-compatible header snippet for macOS, Linux, WSL, and Git Bash.
# On Windows, use the PowerShell command shape below instead.
-H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
-H 'x-acs-version: 2026-03-17' \
-H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

x-acs-date must be generated at request execution time. Use the timestamp expression for the active shell; never replace it with a copied, static, or literal value such as YYYY-MM-DDT00:00:00Z.

Every AgentExplorer HTTP curl / curl.exe request must include --connect-timeout 10 --max-time 30.

Shell-compatible curl usage

Before running AgentExplorer commands, choose the command shape for the active shell/OS. If the environment is Windows, use the Windows PowerShell shape in API Shapes; see references/curl-shell-compatibility.md for shell-specific details.

API Shapes

Bash-compatible Examples

# Bash-compatible examples for macOS, Linux, WSL, and Git Bash.
# On Windows, use the PowerShell command shape below and replace endpoint/query parameters.

# Search skills
curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=<user-intent-or-keyword>' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# List categories
curl -sS --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/categories' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# Get skill content
curl -sS --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills/<skillName>' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Windows PowerShell Search Example

Use this command shape on Windows and replace only query parameters as needed:

powershell -NoProfile -Command "curl.exe -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' --data-urlencode 'keyword=<user-intent-or-keyword>' --data-urlencode 'searchMode=semantic' --data-urlencode 'maxResults=20' -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' -H 'x-acs-version: 2026-03-17' -H ('x-acs-date: ' + [DateTimeOffset]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ'))"

Core Workflow

Step 1: Understand What They Need

Before searching, identify:

1. Domain — The relevant area or Alibaba Cloud product family, e.g., ECS, RDS, OSS, SLS, PAI, testing, deployment, data analysis. 2. Specific task — What the user wants to do, e.g., diagnose ECS issues, sync files to OSS, build a data analysis project, review permissions. 3. Skill likelihood — Whether this is a common enough task that an existing Skill likely exists. 4. Category fit — Whether the domain obviously maps to a known category. Call /openapi/for-agent/categories when the user asks to browse categories or when a categoryCode must be confirmed; otherwise avoid category calls during initial understanding.

Use this understanding to choose the request shape first, then form search text only when using a keyword or semantic request. keyword supports both short keywords and full intent phrases. Because searchMode=semantic matches Skill descriptions, prefer the user's intent when available, such as 建一个数据分析项目, instead of reducing every request to a single product word.

Before searching, convert this analysis into searchable intent units using Intent Analysis for Search. For compound requests, each meaningful requirement or support need must become its own searchable intent unit and be searched independently.

The Search Phrase must be capability-oriented. It should not simply copy the user's surface wording unless the surface wording already names the capability, product, or service clearly.

If a search phrase is mostly domain-specific labels, document titles, organization-specific terms, policy names, or private/internal terminology, rewrite it toward the underlying capability before searching.

Step 2: Search Skills

Choose from the command shapes below based on the request and available category context. For broad product-family discovery, confirm category context before keyword search, then use category listing or category-scoped search. Default to semantic intent search for task-matching requests without useful category context.

• Intent search (default for task matching): Use the user's task or full intent phrase as keyword, with searchMode=semantic.
• Keyword search: Use concise product/task keywords with searchMode=semantic when the intent is broad, noisy, or already names a product/capability.
• Category browsing: Call /openapi/for-agent/categories when the user asks for available categories or when a category code must be confirmed.
• List skills in a category: Use categoryCode only. Do not pass keyword or searchMode=semantic; this mode supports pagination.
• Combined semantic search: After category selection, use both keyword and categoryCode with searchMode=semantic only when the user asks for best matches inside that category.

Choose one request shape based on the user request:

# Bash-compatible examples for macOS, Linux, WSL, and Git Bash.
# On Windows, use the PowerShell command shape above and replace endpoint/query parameters.

# Intent or keyword search
curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=<user-intent-or-keyword>' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# Get all categories before listing skills in a category
curl -sS --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/categories' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# List skills in a category
curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=<category-code>' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# Fetch the next category page if nextToken is returned
curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=<category-code>' \
  --data-urlencode 'maxResults=20' \
  --data-urlencode 'nextToken=<next-token-from-previous-response>' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# Combined semantic search after category selection
curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=<user-intent-or-keyword>' \
  --data-urlencode 'categoryCode=<category-code>' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Step 3: Iterate Until Found

If a searchable intent unit has no clearly covering Skill, or the results are weak, overly generic, or only match surface/domain-specific wording, revise the search phrase and retry automatically before declaring a gap:

1. Start with the user's full intent phrase when available 2. Extract direct product/task keywords from the request 3. Switch between Chinese and English terms ("cloud server" → "ECS", "object storage" → "OSS") 4. Broaden or simplify keywords (drop qualifiers: "RDS backup automation" → "RDS") 5. Use /openapi/for-agent/categories, select the best category, then retry with combined search 6. Try synonyms or related terms ("instance" → "ECS", "bucket" → "OSS")

Do not conclude "no dedicated Skill exists" until you have tried at least one capability-oriented search phrase for that intent unit.

Repeat until every searchable intent unit has a clearly covering Skill, is covered by a complementary selected Skill, or is confirmed as a known gap. If all attempts fail for an intent unit, inform the user what was tried.

Step 4: 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-compatible example for macOS, Linux, WSL, and Git Bash.
# On Windows, use the PowerShell command shape above and replace endpoint/query parameters.

curl -sS --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills/<skillName>' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Step 5: Install Selected Skill(s)

Skip this step when the user only asks to list, browse, compare, or inspect Skills without installation. When installation is requested, execute the installation command for each selected Skill.

# 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 <selected-skill-name>

Verify each selected Skill appears in the available skills list after installation.

API Reference

For complete HTTP parameter details and search parameter rules, see references/agentexplorer-api.md.

Success Verification

After each operation, verify success by checking:

1. List Categories: Response contains data with category code and name fields 2. Search Skills: Response contains data with valid skill objects 3. Get Skill Content: Response contains complete skill markdown content 4. Install Selected Skill(s): Each selected Skill appears in the available skills list

For detailed verification steps, see references/verification-method.md.

Search Strategies

1. Intent Analysis for Search

Before choosing search text, analyze the user's request into searchable intent units. A searchable intent unit should describe what capability the Skill must provide, not only the user's surface wording.

For each meaningful requirement, identify:

• Action: What operation is needed, e.g., query, generate, diagnose, deploy, install, validate, transform
• Object: What the operation applies to, e.g., document, knowledge base, video, script, database, CLI environment
• Context/source: Where the information or resource comes from, e.g., internal docs, cloud service, local file, OSS, database, runtime environment
• Expected output: What the user expects back, e.g., answer with citations, generated script, report, command guidance, installed dependency
• Support needs: Whether the request also needs plugins, runtime dependencies, environment checks, or troubleshooting

Treat explicit support, blocker, and fallback clauses as searchable intents, even when they are conditional. This includes requirements about setup, dependencies, runtime environment, plugins, connectivity, validation, troubleshooting, remediation, or handling errors that may occur during execution. Do not drop these clauses just because they are not the primary business goal; if they may require a separate Skill, search them independently.

Then form one or more searchable intent phrases using:

<action> + <object/capability> + <context/source> + <expected output>

For compound requests, create one searchable intent unit per meaningful requirement and search each unit independently. Do not assume one Skill covers the whole request unless the search result clearly states that it does.

A single searchable intent unit may still require multiple complementary Skills. When one Skill covers the main action but another Skill is needed for supporting needs such as plugins, runtime setup, data access, or validation, select both and explain their roles separately.

2. Search Text Selection

• Use intent phrases first: Prefer the user's natural-language task or requirement, e.g., "建一个数据分析项目", "把本地文件同步到 OSS"
• Use product/task keywords when intent is broad or noisy: Extract concise product and action terms, e.g., "ECS 诊断", "OSS 同步"
• Use product codes as fallback or refinement: ecs, rds, oss, slb, vpc
• Use Chinese and English variants: e.g., "云服务器" / "ECS", "对象存储" / "OSS"
• Use broader terms only after specific intent searches fail: e.g., "compute", "storage", "network"

3. Category Filtering

• Browse when needed: Use /openapi/for-agent/categories when the user asks about categories or when the domain should narrow the search
• Select the best category: Map the domain to the closest categoryCode, then pass it as categoryCode
• Combine with intent: For clear tasks inside a clear domain, use the task phrase as keyword and the selected category as categoryCode

4. Result Optimization

• Start with intent: Begin with the user's task description, then add category filtering only when the domain is clear or initial results are too broad
• Keep complementary Skills together: If one Skill handles the main task and another handles required setup, access, validation, or troubleshooting, include both instead of choosing only the top-ranked main Skill
• Check install counts: Popular skills usually have higher install counts
• Read descriptions: Match skill description to your specific use case

5. When No Results Found

# Bash-compatible examples for macOS, Linux, WSL, and Git Bash.
# On Windows, use the PowerShell command shape above and replace endpoint/query parameters.

# Strategy 1: Try the full user intent
# Instead of just "OSS", try "把本地文件同步到 OSS"

# Strategy 2: Extract product/task keywords
# Instead of "云服务器故障排查", try "ECS 诊断"

# Strategy 3: Try Chinese and English variants
# Instead of "云服务器" try "ECS" or "instance"

# Strategy 4: Use broader terms
# Instead of "RDS backup automation" try just "RDS" or "database"

# Strategy 5: Browse or filter by category
curl -sS --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/categories' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=ECS 实例管理' \
  --data-urlencode 'categoryCode=<selected-category-code>' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

6. 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. Choose the right search mode — Use semantic intent or keyword search for task matching; use category listing without searchMode=semantic when the user asks to list all Skills in a category 2. Search by intent units — Split compound requests into meaningful capability and support needs, then search each unit independently 3. Refine weak results — If results only match surface wording or miss an intent unit, rewrite the phrase toward the underlying capability and retry before declaring a gap 4. Keep complementary Skills together — Select multiple Skills when one covers the main task and another covers required setup, access, validation, troubleshooting, or runtime support 5. Display results clearly — Use tables with skillName, display name, category, description, and install count 6. Install only when requested — Do not install for list-only, browse-only, or compare-only requests 7. Verify before installation — Use the skill content endpoint when search results are not sufficient to confirm fit 8. Verify after installation — Confirm every selected Skill is available after installation

Common Use Cases & Examples

For examples, see references/search-examples.md.

Reference Documentation

Troubleshooting

Error: MissingDate

Cause: The request is missing x-acs-date.

Solution: Add the UTC timestamp header:

# Bash-compatible header snippet for macOS, Linux, WSL, and Git Bash.
# On Windows, use the PowerShell command shape above instead.
-H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Error: InvalidTimeStamp.Expired or Invalidx-acs-date

Cause: x-acs-date is stale, local time, malformed, copied from an earlier request, or hardcoded as a literal timestamp.

Solution: Regenerate current UTC time at request execution time and retry the same request. On Windows PowerShell, use the exact timestamp expression from references/curl-shell-compatibility.md; do not switch to Unix timestamps, invent a different PowerShell date expression, or reuse an old header value.

If the failed Windows command contains $(date -u ...), it used the Bash timestamp expression. Retry with the Windows powershell -NoProfile -Command template above.

If PowerShell reports Invoke-WebRequest or parameter-binding errors, the command used the curl alias. Retry with curl.exe.

Error: DNS, connection, or TLS failure

Cause: Network access to agentexplorer.aliyuncs.com failed.

Solutions:

1. Retry once; transient network failures are possible. 2. Check proxy or network policy if running in a restricted agent sandbox. 3. Do not switch to Aliyun CLI as a workaround unless the user explicitly asks.

No Results Returned

Cause: Search mode, search phrase, or category code does not match the user's request.

Solutions:

1. For semantic intent search, rewrite the phrase toward the underlying capability instead of repeating private/internal wording 2. Try Chinese and English variants, product codes, and concise product/task keywords 3. For weak semantic results, retry with a selected categoryCode and searchMode=semantic 4. For category listing, verify the categoryCode with /openapi/for-agent/categories, omit keyword and searchMode, and use nextToken when pagination is returned 5. Declare a gap only after each searchable intent unit has been retried with at least one capability-oriented phrase

Notes

• Read-only operations: This skill only performs queries, no resources are created
• No CLI prerequisite: Discovery uses curl; downstream selected Skills may have their own CLI or permission requirements
• 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

Acceptance Criteria: alibabacloud-find-skills

Skill Name: alibabacloud-find-skills Purpose: Validate correct AgentExplorer HTTP API usage and skill-discovery behavior.

Discovery Prerequisites

Correct

The discovery workflow uses curl directly:

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=ECS' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Incorrect

aliyun version
aliyun plugin search agentexplorer
aliyun plugin install --names aliyun-cli-agentexplorer
aliyun plugin update --name aliyun-cli-agentexplorer
aliyun agentexplorer search-skills --keyword "ECS"
aliyun configure list

Why: Finding, browsing, and inspecting Skills uses direct HTTP requests and no longer requires Aliyun CLI or the AgentExplorer CLI plugin.

HTTP API Patterns

1. Search Skills

Correct

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=RDS backup automation' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Incorrect

# Missing -G: query params are not appended as intended
curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=RDS backup automation'

# Wrong parameter names from CLI mode
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'search-mode=semantic' \
  --data-urlencode 'max-results=20'

# Wrong endpoint path
curl -sS -G 'https://agentexplorer.aliyuncs.com/search-skills'

Why: HTTP query parameters use API names such as searchMode, maxResults, categoryCode, and nextToken.

2. List Categories

Correct

curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/categories' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Incorrect

curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/category'
curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/list-categories'

3. Get Skill Content

Correct

curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills/alibabacloud-cli-guidance' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Incorrect

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'skillName=alibabacloud-cli-guidance'

curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skill/alibabacloud-cli-guidance'

Why: Skill content uses a path parameter: /openapi/for-agent/skills/{skillName}.

Header Requirements

Correct

Every discovery API call includes all three headers:

-H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
-H 'x-acs-version: 2026-03-17' \
-H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Incorrect

# Missing date header
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=ECS' \
  -H 'x-acs-version: 2026-03-17'

# Wrong user agent
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=ECS' \
  -H 'User-Agent: MyAgent'

# Wrong header shape for this workflow
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  -H 'x-acs-api-version: 2026-03-17'

Why: x-acs-date is mandatory. The skill user-agent is required for attribution. The API version header must be x-acs-version.

Search Parameter Rules

Correct

# Intent search
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=把本地文件同步到 OSS' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# Category listing
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=database' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# Combined semantic search
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=backup' \
  --data-urlencode 'categoryCode=database' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Incorrect

# Category listing should not use semantic mode
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=database' \
  --data-urlencode 'searchMode=semantic'

# Multi-word values are not URL-encoded
curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills?keyword=RDS backup automation'

Pagination Rules

Correct

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=database' \
  --data-urlencode 'maxResults=20' \
  --data-urlencode 'nextToken=<next-token-from-previous-response>' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Incorrect

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'next-token=abc'

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'nextToken=page2'

Why: Use the API field name nextToken, and pass the returned token exactly.

Result Handling

Correct

Present users a concise table:

| Skill Name | Display Name | Category | Install Count | Why it fits |
| --- | --- | --- | ---: | --- |
| alibabacloud-ecs-batch | ECS Batch Ops | 计算 > ECS | 245 | Handles batch ECS operations |

Incorrect

# Dumping raw JSON without summarizing
echo "$RESULT"

Installation Rules

Correct

Only install when the user asks to install or use a selected Skill:

npx skills add aliyun/alibabacloud-aiops-skills \
  --skill <skill-name> \
  --full-depth \
  --agent qwen-code \
  -g -y

Incorrect

# Installing during browse-only/search-only requests
npx skills add aliyun/alibabacloud-aiops-skills --skill <skill-name>

Failure Handling

• On MissingDate, add x-acs-date.
• On network failure, retry once and report endpoint/network context.
• On weak or empty results, rewrite the search phrase toward the underlying capability.
• Do not tell the user to install or configure Aliyun CLI for this discovery workflow.

Final Checklist

• [ ] Uses curl, not aliyun, for discovery
• [ ] Uses https://agentexplorer.aliyuncs.com/openapi/for-agent/skills for search/listing
• [ ] Uses https://agentexplorer.aliyuncs.com/openapi/for-agent/categories for categories
• [ ] Uses /openapi/for-agent/skills/{skillName} for details
• [ ] Includes User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills
• [ ] Includes x-acs-version: 2026-03-17
• [ ] Includes x-acs-date
• [ ] Uses --data-urlencode for query parameters
• [ ] Splits compound requests into searchable intent units
• [ ] Installs selected Skills only when requested

AgentExplorer HTTP API Reference

Complete reference for HTTP requests used by the alibabacloud-find-skills skill.

Discovery uses curl directly. Do not install Aliyun CLI or the agentexplorer CLI plugin for this skill's search, browse, or detail workflows.

Common Request Headers

Every AgentExplorer request must include:

-H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
-H 'x-acs-version: 2026-03-17' \
-H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

x-acs-date is mandatory and must be current UTC time.

For Windows PowerShell, Command Prompt, macOS, Linux, WSL, and Git Bash curl templates, see curl-shell-compatibility.md.

API Summary

Base URL:

https://agentexplorer.aliyuncs.com

1. Search Or List Skills

Endpoint:

GET https://agentexplorer.aliyuncs.com/openapi/for-agent/skills

Query parameters:

Semantic Intent Or Keyword Search

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=<keyword-or-intent>' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

List Skills In A Category

Use when the user asks to list or browse all Skills under a category. Do not pass keyword or searchMode=semantic.

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=<category-code>' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Fetch the next page only when nextToken is returned:

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=<category-code>' \
  --data-urlencode 'maxResults=20' \
  --data-urlencode 'nextToken=<next-token-from-previous-response>' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Combined Semantic Search

Use only after category selection when the user asks for best matches inside a category.

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=<keyword-or-intent>' \
  --data-urlencode 'categoryCode=<category-code>' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Response shape:

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

2. List Categories

Endpoint:

GET https://agentexplorer.aliyuncs.com/openapi/for-agent/categories

Example:

curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/categories' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Response shape:

{
  "data": [
    {
      "code": "computing",
      "name": "计算",
      "children": [
        {
          "code": "ecs",
          "name": "云服务器 ECS"
        }
      ]
    }
  ],
  "requestId": "..."
}

3. Get Skill Content

Endpoint:

GET https://agentexplorer.aliyuncs.com/openapi/for-agent/skills/{skillName}

Example:

curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills/<skillName>' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Response shape:

{
  "requestId": "...",
  "content": "---\nname: alibabacloud-ecs-batch-command\n..."
}

Category Code Rules

• Top-level category: use the category code directly, e.g. computing
• Child category: use dot notation only when the API supports it for the target category, e.g. computing.ecs
• Multiple categories: comma-separate category codes, e.g. computing,database
• If a bare child category such as ecs does not filter as expected, use it as keyword or confirm the current category list first

Search Usage Patterns

Use the same semantic-search shape for both keywords and full intent phrases:

# Keyword search
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=ECS' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# Intent search
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=把本地文件同步到 OSS' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Notes

• Do not use Aliyun CLI flags such as --endpoint, --region, --user-agent, or --cli-query in the HTTP workflow.
• Use jq only if it is already available; otherwise inspect the JSON response directly and summarize the relevant fields.

Category Examples

This reference provides common category codes and examples for navigating the Alibaba Cloud Agent Skills catalog.

For the complete, current category list, call:

curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/categories' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Category Code Format

• Top-level category: use the category code directly, e.g. computing
• Child category: when supported, use dot notation, e.g. computing.ecs
• Multiple categories: comma-separate codes, e.g. computing,database
• If child code filtering is uncertain, confirm with /openapi/for-agent/categories, then use either dot notation or a semantic keyword

Common Categories

Example Searches

Browse A Top-Level Category

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=database' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Search Within A Category

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=RDS backup automation' \
  --data-urlencode 'categoryCode=database' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Try A Child Category Or Product Keyword

# Child category form, when supported
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=computing.ecs' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# Product keyword fallback
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=ECS instance management' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Domain Mapping Hints

Curl Shell Compatibility Guide

AgentExplorer HTTP APIs use the same URL, query parameters, and headers on every operating system. Only shell syntax differs: quoting, line continuation, and UTC timestamp generation.

Bash-compatible Shells

Use this template on macOS, Linux, WSL, and Git Bash:

curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=computing' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Debian/Ubuntu, CentOS/RHEL, and ARM64 Linux use the same syntax. If curl is missing, install it with the system package manager first.

Key Differences

Windows

Use this one-line PowerShell invocation for AgentExplorer API calls on Windows:

powershell -NoProfile -Command "curl.exe -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' `
  --data-urlencode 'categoryCode=computing' `
  --data-urlencode 'maxResults=20' `
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' `
  -H 'x-acs-version: 2026-03-17' `
  -H ('x-acs-date: ' + [DateTimeOffset]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ'))"

Keep the x-acs-date header as the expression above. Do not replace it with a literal timestamp such as YYYY-MM-DDT00:00:00Z.

Translation Rules

• Keep the same AgentExplorer endpoint and query parameters on every shell.
• Keep the same required headers: User-Agent, x-acs-version, and x-acs-date.
• Keep --connect-timeout 10 --max-time 30 on AgentExplorer HTTP calls.
• On Windows, use curl.exe, not curl.
• Generate the Windows x-acs-date header inline with [DateTimeOffset]::UtcNow; do not precompute it in a separate $date variable or hardcode it as a clock value.

Supported --agent Values for npx skills add

Search Examples

Examples moved from SKILL.md to keep the main skill instructions focused.

All examples use AgentExplorer HTTP API directly through curl.

Common Use Cases & Examples

Example 1: Simple Single-Capability Request

User: "Find skills for diagnosing ECS instance connectivity and performance issues."

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=ECS instance diagnosis connectivity CPU disk' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# Display results table, then get details for the best candidate if needed
curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills/<selected-skill-name>' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Example 2: Category Listing Request

Use category listing when the user asks to list all Skills under a category. After listing all category results, review the enumerated skills and highlight likely matches for the user's subtask. Do not install when the user asks to list only.

User: "List all database Skills and point out which ones may fit RDS daily operations."

curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/categories' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=database' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# If nextToken is returned, fetch the next page
curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=database' \
  --data-urlencode 'maxResults=20' \
  --data-urlencode 'nextToken=<next-token-from-previous-response>' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Example 3: Natural-Language Intent Search

User: "把本地文件同步到 OSS"

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=把本地文件同步到 OSS' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Example 4: Refine Weak Results

If the first search only matches surface wording, rewrite the search phrase toward the underlying capability before declaring a gap.

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=knowledge base retrieval document Q&A content citation' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Example 5: Compound Request With Support Needs

For compound requests, create one searchable intent unit for each meaningful requirement or support need, then search each unit independently.

User: "Generate an output from a source document, consult internal standards first, and handle setup or runtime blockers if needed."

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=document parsing content generation structured output' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=knowledge base retrieval document Q&A content citation' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=runtime dependency installation environment troubleshooting' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Before installation, present the final de-duplicated install plan:

Final global Skills to install:

| Skill Name | Solves |
| ---------- | ------ |
| <content-generation-skill> | Generates the requested output |
| <knowledge-retrieval-skill> | Retrieves and cites internal standards |
| <environment-guidance-skill> | Handles setup or runtime blockers |

Verification Methods

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

Discovery workflows use curl against AgentExplorer HTTP API.

Overview

After executing each workflow, verify success by checking:

1. curl exits with code 0 2. Response is valid JSON 3. Response contains the expected field: data, content, or requestId 4. Data content is valid and relevant 5. Errors are handled without switching to Aliyun CLI

Workflow 1: Search Skills By Keyword

Success Criteria

The request succeeds:

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=ECS' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo "Exit code: $?"

Expected response fields:

• data: array of skill objects
• totalCount: number
• requestId: string
• maxResults: number

Each skill should have:

• skillName: non-empty string
• displayName: non-empty string
• description: non-empty string
• categoryName: non-empty string
• installCount: non-negative integer
• likeCount: non-negative integer

Minimal Verification Script

#!/bin/bash
KEYWORD="ECS"

RESULT=$(curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode "keyword=$KEYWORD" \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=5' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)")

if [ $? -ne 0 ]; then
  echo "search request failed"
  exit 1
fi

echo "$RESULT" | grep -q '"data"' || { echo "missing data"; exit 1; }
echo "$RESULT" | grep -q '"skillName"' && echo "skills found" || echo "no skills found"

Workflow 2: Browse Skills By Category

Success Criteria

List categories succeeds:

curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/categories' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Expected category fields:

• data: array
• code: category code
• name: category display name
• children: child category array

Search by category succeeds:

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=database' \
  --data-urlencode 'maxResults=20' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Search results should contain categoryCode matching the requested top-level category.

Workflow 3: Get Skill Details

Success Criteria

The request succeeds with a valid skill name:

curl -sS 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills/alibabacloud-cli-guidance' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Expected response fields:

• requestId: string
• content: non-empty markdown string

The content value should include skill frontmatter with name: and description:.

Workflow 4: Combined Search

Success Criteria

Combined keyword and category search succeeds:

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'keyword=backup' \
  --data-urlencode 'categoryCode=database' \
  --data-urlencode 'searchMode=semantic' \
  --data-urlencode 'maxResults=10' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Results should be relevant to both the keyword and category.

Workflow 5: Paginated Category Listing

Success Criteria

First page returns nextToken when more results exist:

PAGE1=$(curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=database' \
  --data-urlencode 'maxResults=2' \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)")

echo "$PAGE1" | grep -q '"nextToken"'

Second page uses the returned token exactly:

NEXT_TOKEN="<next-token-from-previous-response>"

curl -sS -G 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \
  --data-urlencode 'categoryCode=database' \
  --data-urlencode 'maxResults=2' \
  --data-urlencode "nextToken=$NEXT_TOKEN" \
  -H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \
  -H 'x-acs-version: 2026-03-17' \
  -H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Do not invent or edit pagination tokens.

Workflow 6: Install A Skill

Installation is separate from AgentExplorer discovery.

npx skills add aliyun/alibabacloud-aiops-skills \
  --skill <skill-name> \
  --full-depth \
  --agent qwen-code \
  -g -y

Manual checklist:

• [ ] Installation command completed without errors
• [ ] Skill appears in the target agent's skill list
• [ ] Skill can be triggered with appropriate keywords
• [ ] Installed Skill's own prerequisites are followed

Error Verification

Missing x-acs-date

If x-acs-date is omitted, the API returns an error similar to:

{
  "Code": "MissingDate",
  "Message": "Date is mandatory for this action."
}

Fix by adding:

-H "x-acs-date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Network Failure

For DNS, proxy, or TLS errors:

1. Retry once 2. Check network/proxy access to agentexplorer.aliyuncs.com 3. Report the failure with the attempted endpoint and operation 4. Do not fall back to Aliyun CLI unless the user explicitly requests it

General Verification Checklist

Request Execution

• [ ] Uses curl, not aliyun
• [ ] Uses https://agentexplorer.aliyuncs.com
• [ ] Includes User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills
• [ ] Includes x-acs-version: 2026-03-17
• [ ] Includes x-acs-date
• [ ] Uses --data-urlencode for query values with spaces, Chinese text, or tokens

Response Format

• [ ] Search response has data
• [ ] Category response has data
• [ ] Detail response has content
• [ ] Error response is summarized clearly

User Presentation

• [ ] Results are shown as a table or concise list
• [ ] skillName, display name, category, description, and install count are included when available
• [ ] The final install plan is de-duplicated
• [ ] Installation is performed only when the user asked for it