alibabacloud-find-skills：根据用户使用阿里云的场景和需求，搜索并安装使用阿里云官方 Agent Skills。

阿里云 Agent Skills 搜索与发现

本 Skill 帮助用户从 AgentExplorer 目录中搜索、发现和安装阿里云官方 Agent Skills。

场景说明

本 Skill 使用户能够：

1. 搜索 Skill —— 通过意图短语、关键词、类目列表或组合语义搜索查找阿里云 Agent Skills
2. 浏览类目 —— 探索可用 Skill 类目和子类目
3. 查看 Skill 详情 —— 获取特定 Skill 的详细信息
4. 安装 Skill —— 当用户请求安装时，引导用户完成 Skill 安装

架构：curl + AgentExplorer HTTP API → Skills 仓库

发现流程直接通过 curl 使用 AgentExplorer HTTP API；搜索、浏览或详情工作流不要使用 Aliyun CLI，也不要安装 / 更新 agentexplorer CLI 插件。

适用场景

• "找一个管理 ECS 实例的 skill"
• "阿里云有哪些数据库相关的 skills？"
• "阿里云有哪些 OSS 相关的 skill？"
• "浏览所有可用的阿里云 skills"
• "安装一个 RDS 管理的 skill"

AgentExplorer HTTP API

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

每个 AgentExplorer HTTP 请求都必须包含以下请求头。

兼容 Bash 的请求头片段，适用于 macOS、Linux、WSL 和 Git Bash。

Windows 上请改用下方的 PowerShell 命令形态。

-H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \

-H 'x-acs-version: 2026-03-17'

每个 AgentExplorer HTTP `curl` / `curl.exe` 请求都必须包含 `--connect-timeout 10 --max-time 30`。

### 兼容 Shell 的 curl 用法

运行 AgentExplorer 命令前，先选择当前 shell / 操作系统的命令形态。如果环境是 Windows，使用 [API 形态](#api-形态)中的 Windows PowerShell 形态；shell 特定细节见 [references/curl-shell-compatibility.md](references/curl-shell-compatibility.md)。

### API 形态

#### 兼容 Bash 的示例

兼容 Bash 的示例，适用于 macOS、Linux、WSL 和 Git Bash。

Windows 上请改用下方 PowerShell 命令形态，并替换 endpoint/query 参数。

搜索 skills

curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \

--data-urlencode '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'

列出类目

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'

获取 skill 内容

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'

#### Windows PowerShell 搜索示例

在 Windows 上使用此命令形态，只需按需替换查询参数：

powershell -NoProfile -Command "curl.exe -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' --data-urlencode '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'"

核心工作流

步骤 1：理解用户需求

搜索前，先识别：

1. 领域 —— 相关领域或阿里云产品族，例如 ECS、RDS、OSS、SLS、PAI、测试、部署、数据分析。
2. 具体任务 —— 用户想做什么，例如诊断 ECS 问题、同步文件到 OSS、建一个数据分析项目、审查权限。
3. Skill 可能性 —— 这是否是足够常见的任务，以至于可能已有 Skill 存在。
4. 类目匹配 —— 该领域是否明显映射到已知类目。当用户要求浏览类目或必须确认 categoryCode 时，调用 /openapi/for-agent/categories；否则在初始理解阶段避免类目调用。

用这些理解先选择请求形态，仅在用关键词或语义请求时才形成搜索文本。keyword 同时支持短关键词和完整意图短语。由于 searchMode=semantic 匹配 Skill 描述，有意图时优先使用用户意图，例如 建一个数据分析项目，而不是把每个请求都简化为单个产品词。

搜索前，用搜索的意图分析将这一分析转换为可搜索的意图单元。对于复合请求，每个有意义的需求或支撑需求都必须成为独立的可搜索意图单元并独立搜索。

搜索短语必须面向能力。除非表面措辞已清楚点明能力、产品或服务，否则不应简单复制用户的表面措辞。

如果搜索短语主要是领域特定标签、文档标题、组织特定术语、策略名称或私有 / 内部术语，请在搜索前将其改写为底层能力。

步骤 2：搜索 Skill

根据请求和可用类目上下文，从下方命令形态中选择。对于宽泛的产品族发现，先确认类目上下文再关键词搜索，然后使用类目列表或类目范围搜索。对于无有用类目上下文的任务匹配请求，默认使用语义意图搜索。

• 意图搜索（任务匹配默认）：用用户任务或完整意图短语作为 keyword，searchMode=semantic。
• 关键词搜索：当意图宽泛、嘈杂或已点明产品 / 能力时，用简洁的产品 / 任务关键词配 searchMode=semantic。
• 类目浏览：当用户要求可用类目或必须确认类目代码时，调用 /openapi/for-agent/categories。
• 列出类目内 skills：只用 categoryCode。不要传 keyword 或 searchMode=semantic；此模式支持分页。
• 组合语义搜索：类目选定后，仅当用户要求该类目内最佳匹配时，同时使用 keyword 和 categoryCode 配 searchMode=semantic。

根据用户请求选择一种请求形态：

兼容 Bash 的示例，适用于 macOS、Linux、WSL 和 Git Bash。

Windows 上请改用上方 PowerShell 命令形态，并替换 endpoint/query 参数。

意图或关键词搜索

curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \

--data-urlencode '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'

列出类目内 skills 前先获取所有类目

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'

列出类目内 skills

curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \

--data-urlencode 'categoryCode=<类目代码>' \

--data-urlencode 'maxResults=20' \

-H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \

-H 'x-acs-version: 2026-03-17'

若返回 nextToken，获取下一个类目页

curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \

--data-urlencode 'categoryCode=<类目代码>' \

--data-urlencode 'maxResults=20' \

--data-urlencode 'nextToken=<上一响应中的 next-token>' \

-H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \

-H 'x-acs-version: 2026-03-17'

类目选定后的组合语义搜索

curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \

--data-urlencode 'keyword=<用户意图或关键词>' \

--data-urlencode 'categoryCode=<类目代码>' \

--data-urlencode 'searchMode=semantic' \

--data-urlencode 'maxResults=20' \

-H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \

-H 'x-acs-version: 2026-03-17'

### 步骤 3：迭代直到找到

如果某个可搜索意图单元没有明显覆盖的 Skill，或结果很弱、过于宽泛，或只匹配表面 / 领域特定措辞，请在宣告缺口前自动修改搜索短语并重试：

1. 有用户完整意图短语时先用它
2. 从请求中提取直接的产品 / 任务关键词
3. 在中英文术语间切换（"云服务器" → "ECS"，"对象存储" → "OSS"）
4. 拓宽或简化关键词（去掉限定词："RDS 备份自动化" → "RDS"）
5. 使用 `/openapi/for-agent/categories`，选最佳类目，再用组合搜索重试
6. 尝试同义词或相关词（"实例" → "ECS"，"bucket" → "OSS"）

在至少为该意图单元尝试过一个面向能力的搜索短语之前，不要下"没有专用 Skill 存在"的结论。

重复直到每个可搜索意图单元都有明显覆盖的 Skill、被互补的已选 Skill 覆盖，或确认为已知缺口。如果某意图单元所有尝试都失败，告知用户已尝试过什么。

### 步骤 4：查看 Skill 详情（可选）

可选地获取 skill 内容，以在安装前验证其符合用户意图。如果搜索结果已提供足够信息，可跳过此步骤。

兼容 Bash 的示例，适用于 macOS、Linux、WSL 和 Git Bash。

Windows 上请改用上方 PowerShell 命令形态，并替换 endpoint/query 参数。

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'

### 步骤 5：安装所选 Skill

当用户只要求列出、浏览、比较或检查 Skill 而不安装时，跳过此步骤。当用户请求安装时，为每个所选 Skill 执行安装命令。

方案 A：使用 npx skills add

默认该命令为交互式（会阻塞等待用户输入）。

推荐：使用非交互模式以避免阻塞。

--agent <client> 要安装到的 Agent 客户端（见 references/npx-skills-agents.md）

-g 全局安装（home 目录）；省略则为项目本地安装

-y 跳过确认（需要同时设置 --agent 和 -g/-local）

npx skills add aliyun/alibabacloud-aiops-skills \

--skill <skill-name> \

--full-depth \

--agent qwen-code \

-g -y

方案 B：使用 npx clawhub install（OpenClaw 生态）

npx clawhub install <所选-skill-名称>

安装后验证每个所选 Skill 出现在可用 skills 列表中。

API 参考

完整 HTTP 参数细节和搜索参数规则，见 references/agentexplorer-api.md。

成功验证

每次操作后，通过检查以下内容验证成功：

1. 列出类目：响应包含带类目 code 和 name 字段的 data
2. 搜索 Skills：响应包含有效 skill 对象的 data
3. 获取 Skill 内容：响应包含完整的 skill markdown content
4. 安装所选 Skill：每个所选 Skill 出现在可用 skills 列表中

详细验证步骤见 references/verification-method.md。

搜索策略

1. 搜索的意图分析

选择搜索文本前，将用户请求分析为可搜索的意图单元。可搜索意图单元应描述 Skill 必须提供的能力，而非仅用户的表面措辞。

对每个有意义的需求，识别：

• 动作：需要什么操作，例如查询、生成、诊断、部署、安装、校验、转换
• 对象：操作应用于什么，例如文档、知识库、视频、脚本、数据库、CLI 环境
• 上下文 / 来源：信息或资源来自哪里，例如内部文档、云服务、本地文件、OSS、数据库、运行时环境
• 预期输出：用户期望返回什么，例如带引用的答案、生成的脚本、报告、命令指引、已安装依赖
• 支撑需求：请求是否还需要插件、运行时依赖、环境检查或故障排查

将显式的支撑、阻塞和兜底子句视为可搜索意图，即使它们是条件性的。这包括关于安装、依赖、运行时环境、插件、连接性、校验、故障排查、修复，或执行中可能出现的错误处理的各类要求。不要因为它们是次要业务目标就丢弃这些子句；如果它们可能需要单独的 Skill，请独立搜索。

然后用以下方式形成一个或多个可搜索意图短语：

<动作> + <对象/能力> + <上下文/来源> + <预期输出>

对于复合请求，每个有意义的需求创建一个可搜索意图单元并独立搜索。除非搜索结果明确说明一个 Skill 覆盖整个请求，否则不要假设如此。

单个可搜索意图单元仍可能需要多个互补 Skill。当一个 Skill 覆盖主要动作，而另一个 Skill 是插件、运行时配置、数据访问或校验等支撑需求所必需时，两者都选，并分别说明其角色。

2. 搜索文本选择

• 优先使用意图短语：优先用户自然语言任务或需求，例如"建一个数据分析项目"、"把本地文件同步到 OSS"
• 意图宽泛或嘈杂时使用产品 / 任务关键词：提取简洁的产品和动作术语，例如"ECS 诊断"、"OSS 同步"
• 产品代码作为兜底或细化：ecs、rds、oss、slb、vpc
• 使用中英文变体：例如"云服务器" / "ECS"，"对象存储" / "OSS"
• 仅在具体意图搜索失败后才使用更宽泛的术语：例如"compute"、"storage"、"network"

3. 类目过滤

• 需要时浏览：当用户询问类目或领域应缩小搜索范围时，使用 /openapi/for-agent/categories
• 选择最佳类目：将领域映射到最近的 categoryCode，然后作为 categoryCode 传入
• 与意图组合：对于清晰领域内的明确任务，用任务短语作为 keyword，所选类目作为 categoryCode

4. 结果优化

• 从意图开始：以用户任务描述开始，仅在领域清晰或初始结果过于宽泛时添加类目过滤
• 保持互补 Skill 在一起：如果一个 Skill 处理主任务，另一个处理必需的配置、访问、校验或故障排查，两者都选，而非只选排名最高的主 Skill
• 检查安装量：热门 skill 通常安装量更高
• 阅读描述：将 skill 描述与你的具体用例匹配

5. 无结果时

兼容 Bash 的示例，适用于 macOS、Linux、WSL 和 Git Bash。

Windows 上请改用上方 PowerShell 命令形态，并替换 endpoint/query 参数。

策略 1：尝试完整用户意图

不要只用 "OSS"，试试 "把本地文件同步到 OSS"

策略 2：提取产品 / 任务关键词

不要用 "云服务器故障排查"，试试 "ECS 诊断"

策略 3：尝试中英文变体

不要用 "云服务器"，试试 "ECS" 或 "instance"

策略 4：使用更宽泛的术语

不要用 "RDS 备份自动化"，试试 "RDS" 或 "database"

策略 5：浏览或按类目过滤

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'

curl -sS -G --connect-timeout 10 --max-time 30 'https://agentexplorer.aliyuncs.com/openapi/for-agent/skills' \

--data-urlencode 'keyword=ECS 实例管理' \

--data-urlencode 'categoryCode=<所选类目代码>' \

--data-urlencode 'searchMode=semantic' \

--data-urlencode 'maxResults=20' \

-H 'User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-find-skills' \

-H 'x-acs-version: 2026-03-17'

### 6. 向用户展示结果

呈现搜索结果时，格式化为表格：

找到 N 个 skills：

包含：

- **skillName**：用于安装和详细查询
- **displayName**：用户友好名称
- **description**：简要概述
- **categoryName** + **subCategoryName**：分类
- **installCount**：热度指标

清理

本 Skill 不创建任何资源。无需清理。

最佳实践

1. 选择正确的搜索模式 —— 任务匹配用语义意图或关键词搜索；当用户要求列出类目内所有 Skill 时，用不带 searchMode=semantic 的类目列表
2. 按意图单元搜索 —— 将复合请求拆分为有意义的能力和支撑需求，然后独立搜索每个单元
3. 细化弱结果 —— 如果结果只匹配表面措辞或遗漏某个意图单元，将短语改写为底层能力并在宣告缺口前重试
4. 保持互补 Skill 在一起 —— 当一个覆盖主任务，另一个覆盖必需的配置、访问、校验、故障排查或运行时支撑时，选择多个 Skill
5. 清晰展示结果 —— 使用包含 skillName、显示名称、类目、描述和安装量的表格
6. 仅在被要求时安装 —— 对仅列出、仅浏览或仅比较的请求不要安装
7. 安装前验证 —— 搜索结果不足以确认匹配时，使用 skill 内容端点
8. 安装后验证 —— 确认每个所选 Skill 在安装后可用

常见用例与示例

示例见 references/search-examples.md。

参考文档

故障排查

如果 PowerShell 报告 Invoke-WebRequest 或参数绑定错误，说明命令使用了 curl 别名。改用 curl.exe 重试。

错误：DNS、连接或 TLS 失败

原因：访问 agentexplorer.aliyuncs.com 的网络失败。

解决方案：

1. 重试一次；瞬时网络故障是可能的。
2. 如果在受限的 agent 沙箱中运行，检查代理或网络策略。
3. 除非用户明确要求，否则不要改用 Aliyun CLI 作为变通。

无结果返回

原因：搜索模式、搜索短语或类目代码与用户请求不匹配。

解决方案：

1. 对于语义意图搜索，将短语改写为底层能力，而非重复私有 / 内部措辞
2. 尝试中英文变体、产品代码和简洁的产品 / 任务关键词
3. 对于弱语义结果，用所选 categoryCode 和 searchMode=semantic 重试
4. 对于类目列表，用 /openapi/for-agent/categories 验证 categoryCode，省略 keyword 和 searchMode，并在返回分页时使用 nextToken
5. 仅在对每个可搜索意图单元至少用一个面向能力的短语重试过后，才宣告缺口

注意事项

• 只读操作：本 Skill 只执行查询，不创建任何资源
• 无 CLI 前置要求：发现流程使用 curl；下游所选 Skill 可能有自己的 CLI 或权限要求
• 多语言支持：关键词支持中英文
• 定期更新：Skills 目录会定期更新新 skills
• 社区 skills：部分 skills 可能为社区贡献，请仔细阅读描述