lishiyu7/search_one_skill / SKILLS/search_one_skill
search-one-skill
VerifiedUse when the user wants to find, search, or discover agent skills matching a task description — dual-source search across GitHub and SkillHub with guided installation
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.6 KB |
| scripts/skill_install.py | script | 8.5 KB |
| scripts/skill_search.py | script | 9.5 KB |
SKILL.md
View on GitHub---
name: search-one-skill
description: Use when the user wants to find, search, or discover agent skills matching a task description — dual-source search across GitHub and SkillHub with guided installation
---
# Skill 搜索与安装工作流
## Overview
双源 skill 发现与安装工作流:同时搜索 GitHub 和 SkillHub,按相关性排序取 TOP 5,用户确认后安装。核心原则:**多关键词覆盖、先搜后装、用户确认、本地检查、翻译优先。**
**语言匹配规则:所有面向用户的输出(推荐表格、提示信息、错误消息、确认语句)必须匹配用户使用的语言。用户说中文则中文输出,用户说英文则英文输出。**
## When to Use
**触发场景:**
- 用户说"帮我找 X 的 skill""搜索/推荐 skill""有什么好用的 skill"
- 用户描述了一个任务,需要匹配合适的 skill
- 用户想发现尚未安装的能力
**不适用场景:**
- 用户已知确切 skill 名称,只想直接使用(非搜索行为)
- 用户在创建/编辑 skill
## 工作流概览(2 步)
1. **Skill 检索**:按用户任务描述,翻译为英文后发散 2-3 组关键词变体,双源搜索(GitHub + SkillHub)匹配的 skill,合并去重取 TOP 5
2. **决策 + 下载安装**:用户确认选择后,按来源执行安装
## 双源架构
| 来源 | 搜索方式 | 安装方式 | 认证 |
| -------- | ---------------------------------- | ------------------------------ | ------------------------------------- |
| GitHub | REST API(`topic:skill` + 关键词) | `git clone`,fallback ZIP 下载 | 匿名(60次/h),建议设 `GITHUB_TOKEN` |
| SkillHub | CLI(`skillhub search`) | CLI(`skillhub install`) | 可选,未登录时静默跳过 |
- 默认**同时搜索两个源**,合并归一化排序,取 TOP 5
- SkillHub 不可用时静默降级为纯 GitHub 搜索
- 支持 `--source github|skillhub|all` 精确控制
---
## Step 1:Skill 检索
### 1.1 判断用户意图
- **描述明确**:直接按描述发起检索
- **描述模糊**(如"找个 skill""推荐个技能"):
- 先检查对话上下文中是否有可推断的需求
- 如有则基于上下文发起检索
- 如无则追问用户想找什么方向的 skill
### 1.2 中文 → 英文翻译 + 关键词发散
用户使用中文描述时,**使用大模型翻译为 2-3 组英文关键词变体**,覆盖不同角度和近义词,避免单关键词遗漏。
**为什么需要多关键词?** GitHub 搜索依赖文本匹配(仓库名、描述、README)。同义词和不同表述方式会命中完全不同的仓库。例如:
- `"resume builder"` 搜不到 `resume-jd-optimizer-cn`(用了 "optimizer" 而非 "builder")
- `"resume optimizer"` 就能搜到
**关键词发散规则:**
1. 将中文描述翻译为 1 组核心英文关键词
2. **至少再发散 1-2 组变体**,考虑:近义词替换(builder → optimizer/ generator / writer)、功能侧重切换(编辑 → 优化 / 匹配 / 评分)、场景补充(通用 → Chinese / ATS / JD-driven)
3. 关键词保持简洁(2-4 个单词),不做长句查询
> 翻译和发散在 Agent 层完成,搜索脚本接收英文关键词作为参数。
### 1.3 Agent 类型识别
调用搜索/安装脚本时需传入当前 Agent 类型(`--agent-type`),用于 SkillHub 的平台过滤(`--platform`)。
按以下优先级识别:
1. **System Prompt**:若运行环境提供 system prompt(如 Catdesk、Hermes 等),从中识别 Agent 框架名
2. **IDENTITY.md**:若运行环境无 system prompt(如 Claude 等),检查本地是否存在 `IDENTITY.md`,从中读取 Agent 框架标识
3. **自行判断**:若以上均无法识别,根据你所在的运行时框架自行判断
> 若确实无法识别,可省略该参数。SkillHub 支持以下 platform:`claude`、`codex`、`cursor`、`gemini-cli`、`windsurf`、`openhands`。不在此列表内的值将被忽略。
### 1.4 调用检索脚本(多关键词)
**对每组关键词变体分别调用搜索脚本:**
```bash
{python} {skill_dir}/scripts/skill_search.py "<关键词变体1>" --agent-type <Agent类型> --limit 5
{python} {skill_dir}/scripts/skill_search.py "<关键词变体2>" --agent-type <Agent类型> --limit 5
{python} {skill_dir}/scripts/skill_search.py "<关键词变体3>" --agent-type <Agent类型> --limit 5
```
> 可并行执行(互不依赖),提升搜索速度。
**合并与去重规则:**
1. 合并所有变体的搜索结果,按 `name` 去重(保留 score 最高的)
2. 按 score 重新降序排列
3. 取 TOP 5 作为最终结果
可选参数:
- `--source github`:仅搜索 GitHub
- `--source skillhub`:仅搜索 SkillHub
- `--source all`:双源搜索(默认)
- `--limit 5`:返回条数(默认 5)
> `{python}` 按本机实际选择:macOS / Linux 通常为 `python3`,Windows 通常为 `python` 或 `py`。下同。
### 1.5 脚本输出
脚本输出 JSON 数组到 stdout,每条结果包含:
```json
{
"name": "skill 名称",
"source": "github | skillhub",
"repo_url": "https://github.com/... (GitHub 源有值,SkillHub 源为 null)",
"description": "技能描述",
"score": 0.92,
"stars": 128 (仅 GitHub 源有值)
}
```
### 1.6 输出规则
- 输出 **TOP 5**:按 score 从高到低推荐,最多 5 个(不足就少输出)
- 0 条结果时告知用户:**"没有找到完全匹配的 skill,建议换个关键词或更简短的描述再试一次。"**
- 展示格式:`# | Skill | 推荐理由`(中文用户)或 `# | Skill | Why Recommended`(英文用户)。仅此三列,**不要自行添加额外信息**
- 推荐理由:结合 description 字段和 stars(GitHub 源)汇总
- **最优推荐**:返回结果的第 1 条即为最优推荐,已由脚本按 score 排序,直接推荐即可。**不要自行重新分析或排序**,不要添加"综合你的需求,我比较推荐 XXX"等自行分析的结论
### 1.7 输出模板
> 严格参照以下格式,将 `{...}` 占位符替换为实际值:
```
为你找到以下相关 skill:
| # | Skill | 推荐理由 |
|---|-------|---------|
| 1 | {name} | {reason} |
| 2 | {name} | {reason} |
最优推荐是 #1 {name}({reason})。你想安装哪一个?告诉我编号或名字就行。
```
**英文模板(用户说英文时使用):**
```
Here are the matching skills I found:
| # | Skill | Why Recommended |
|---|-------|-----------------|
| 1 | {name} | {reason} |
| 2 | {name} | {reason} |
The top recommendation is #1 {name} ({reason}). Which one would you like to install? Tell me the number or name.
```
### 1.8 异常处理
> 脚本执行出错或返回非零退出码时,**禁止**将原始错误信息直接展示给用户,需按以下规则处理:
| 异常场景 | 判别方式 | 处理方式 | 输出示例 |
| -------------------- | ------------------------------------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| GitHub 限流 | stderr 含 `RATE_LIMITED` | 告知用户设置 token | "GitHub API 请求次数已达上限(60次/小时)。设置环境变量 `GITHUB_TOKEN` 可提升至 5000 次/小时,或稍后重试。" |
| 所有源均失败 | 退出码 2 或 stderr 含 `ALL_SOURCES_FAILED` | 告知用户稍后重试 | "搜索服务暂时不可用,请稍后再试。" |
| 返回 0 条结果 | stdout 为 `[]` | 告知用户换描述重试 | "没有找到完全匹配的 skill,建议换个关键词或更简短的描述再试一次。" |
| 脚本执行报错(其他) | 非零退出码 | 翻译为用户友好的中文提示 | "搜索服务遇到了一点问题,建议稍后重试。如持续出现,可反馈给 skill 作者。" |
**英文错误消息(用户说英文时使用):**
| 异常场景 | 英文输出 |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| GitHub 限流 | "GitHub API rate limit reached (60 req/hr anonymous). Set the `GITHUB_TOKEN` environment variable for 5,000 req/hr, or try again later." |
| 所有源均失败 | "Search service is temporarily unavailable. Please try again later." |
| 返回 0 条结果 | "No matching skills found. Try different keywords or a shorter description." |
| 脚本执行报错(其他) | "The search service encountered an issue. Please try again later. If this persists, report it to the skill author." |
### 1.9 GitHub Token 配置
搜索过程中,若遇到 GitHub 限流(退出码 2),**仅在此时**提示用户:
```
GitHub API 请求次数已达上限(匿名 60 次/小时)。
设置环境变量 GITHUB_TOKEN 可提升至 5000 次/小时。
获取方式:GitHub → Settings → Developer settings → Personal access tokens → Generate new token(无需勾选任何权限)。
设置方法:export GITHUB_TOKEN=<你的token>
```
> 日常使用中 60 次/小时足够,仅在触发限流时才提示。**不要主动检查或要求用户预先设置。**
**英文提示(用户说英文时):**
```
GitHub API rate limit reached (60 req/hr anonymous).
Set the GITHUB_TOKEN environment variable for 5,000 req/hr.
How to get one: GitHub → Settings → Developer settings → Personal access tokens → Generate new token (no permissions needed).
How to set: export GITHUB_TOKEN=<your-token>
```
---
## Step 2:决策 + 下载安装
### 2.1 确认用户选择
当用户通过以下方式确认时,进入安装流程:
- **说编号**:如 "1""第一个"(英文: "1" "the first one")
- **说名称**:如 "装 resume-builder"(英文: "install resume-builder")
- **说意图**:如 "安装""装这个""就它了""用这个"(英文: "install" "this one" "let's go with this" "use this")
### 2.2 本地检查
检查 `{skills_dir}/{name}/SKILL.md` 是否存在(`{skills_dir}` 为当前 Agent 的 skills 目录,`{name}` 为用户选择的 skill 名称(即 GitHub 仓库名))。
- **已安装**:告知用户 **"该 skill 已安装,无需重复安装,是否直接运行?"**(英文: **"This skill is already installed. Would you like to run it directly?"**)
- **未安装**:执行安装流程
### 2.3 执行安装
按搜索结果的 `source` 字段选择安装方式:
**GitHub 源**(`source: "github"`):
```bash
{python} {skill_dir}/scripts/skill_install.py <name> --dir <当前Agent的skills目录> --source github --repo-url <repo_url>
```
安装策略:
1. 尝试 `git clone --depth 1 <repo_url> <skills_dir>/<name>`
2. 若 git 不可用,fallback 为 ZIP 下载(GitHub archive API)
3. 安装完成后校验 `SKILL.md` 是否存在,不存在则清理并报错
**SkillHub 源**(`source: "skillhub"`):
```bash
{python} {skill_dir}/scripts/skill_install.py <name> --dir <当前Agent的skills目录> --source skillhub --agent-type <Agent类型>
```
### 2.4 安装结果
| stdout 前缀 | 状态 | Agent 输出 |
| -------------------- | ------------------------------ | -------------------------------------------------------------------- |
| `SUCCESS:` | 安装成功 | "{name} 已安装成功。要用这个来完成你的任务吗?" |
| `ALREADY_INSTALLED:` | 已安装(本地 SKILL.md 已存在) | "该 skill 已安装,无需重复安装,是否直接运行?" |
| `ERROR:` | 安装失败 | "{name} 安装失败,原因:{描述}。建议稍后重试,或换一个 skill 试试。" |
**英文安装结果(用户说英文时):**
| stdout 前缀 | Status | Agent output |
| -------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------- |
| `SUCCESS:` | Installed | "{name} has been installed successfully. Would you like to use it for your task?" |
| `ALREADY_INSTALLED:` | Already installed | "This skill is already installed. Would you like to run it directly?" |
| `ERROR:` | Installation failed | "{name} installation failed: {reason}. Please try again later, or try a different skill." |
---
## 核心工具
| 命令 | 用途 |
| ------------------ | ---------------------------------------------- |
| `skill_search.py` | 双源检索 skill(GitHub API + SkillHub CLI) |
| `skill_install.py` | 双源安装 skill(git clone/ZIP + SkillHub CLI) |
---
## 完整使用示例
**用户**:找个写简历的 skill
**Agent 内部**:翻译+发散为 3 组关键词变体 → `"resume builder"`、`"resume optimizer chinese"`、`"cv generator"`,识别 Agent 类型
**Agent 执行**(并行):
```bash
python3 {skill_dir}/scripts/skill_search.py "resume builder" --agent-type claude
python3 {skill_dir}/scripts/skill_search.py "resume optimizer chinese" --agent-type claude
python3 {skill_dir}/scripts/skill_search.py "cv generator" --agent-type claude
```
合并去重后,按 score 降序取 TOP 5。
**Agent 输出**:
为你找到以下相关 skill:
| # | Skill | 推荐理由 |
| --- | -------------------------- | ---------------------------------------------------------------------------- |
| 1 | resume-jd-optimizer-cn | JD 驱动的中文简历优化,解析岗位 JD、诊断简历缺口、ATS 友好 ⭐135 |
| 2 | resume-builder-skill | 基于工作轨迹智能提取核心能力,一键生成专业简历 ⭐6 |
最优推荐是 #1 resume-jd-optimizer-cn(JD 驱动中文简历优化,⭐135)。你想安装哪一个?告诉我编号或名字就行。
**用户**:1 → Agent 确认本地未安装 → 执行安装
**英文示例:**
**User**: find me a skill for writing resumes
**Agent**: translates + diverges → `"resume builder"`, `"resume optimizer chinese"`, `"cv generator"`; searches in parallel; merges & deduplicates
**Agent outputs**:
Here are the matching skills I found:
| # | Skill | Why Recommended |
| --- | ------------------- | --------------------------------------------------------------------------------- |
| 1 | resume-builder | Smart resume generator with multi-template support, keyword optimization, ATS-friendly ⭐234 |
| 2 | cover-letter-writer | Auto-generates cover letters tailored to job descriptions |
The top recommendation is #1 resume-builder (Smart resume generator, ⭐234). Which one would you like to install? Tell me the number or name.
**User**: 1 → Agent confirms not installed → installs → "resume-builder has been installed successfully. Would you like to use it for your task?"
---
## Common Mistakes
| 错误行为 | 为什么会出现 | 正确做法 |
| ------------------------------ | ---------------------- | ------------------------------------------------------------- |
| 跳过中文→英文翻译 | "脚本应该能处理中文" | GitHub API 对英文最优,**始终翻译为英文关键词**再搜 |
| 只生成一组关键词 | "翻译一个就够了" | **至少生成 2-3 组关键词变体**,覆盖近义词和不同表述角度 |
| 未经确认自动安装 | "最优推荐很明显" | **始终等待用户明确选择**,不自动安装 |
| 未检查本地就安装 | "应该没装过" | 始终先检查 `{skills_dir}/{name}/SKILL.md` 是否存在 |
| 自行重新排序结果 | "我比脚本更懂用户需求" | 脚本已按 score 排序,**信任排序**,不要自行分析 |
| 直接展示原始错误信息 | "用户应该看到完整错误" | 按异常处理表翻译为**用户友好的中文提示** |
| 主动检查/要求设置 GITHUB_TOKEN | "提前配置更好" | **仅在触发限流时**(退出码 2)才提示,日常使用 60 次/小时足够 |
| 安装后不校验 SKILL.md | "clone 成功就行" | GitHub 源安装后**必须校验** SKILL.md 存在性,否则清理并报错 |
## Red Flags - 自查清单
以下想法出现时,**STOP 并回到规则**:
- "这个中文描述够清楚了,不需要翻译" → 翻译为英文再搜
- "翻译一组关键词就够了" → 至少 2-3 组变体,覆盖近义词
- "就装第 1 个吧,不用问了" → 等用户确认
- "SkillHub 挂了,我直接用 GitHub" → 可以,但告知用户
- "这个 skill 肯定没装过" → 先检查本地
- "脚本输出有点奇怪,我重新排个序" → 信任脚本排序
- "我先帮用户检查下 GITHUB_TOKEN" → 仅在限流时提示
- "clone 成功了,应该没问题" → 校验 SKILL.md
---
## 注意事项
1. **多关键词覆盖**:中文→英文翻译后必须发散 2-3 组关键词变体,覆盖近义词和不同角度
2. **本地优先**:安装前须确认本地是否已安装该 skill,避免重复下载
3. **安装确认**:需等用户选择后才安装,**不自动安装**
4. **CN→EN 翻译**:调用搜索脚本前,先由大模型将用户中文描述翻译为英文关键词
5. **GitHub 目录名**:安装到 `{skills_dir}/{仓库名}/`,不做重命名
6. **安装校验**:GitHub 源安装后须校验 SKILL.md 存在性,无效则自动清理
7. **SkillHub 可选**:SkillHub CLI 不可用或未认证时静默跳过,不影响 GitHub 搜索
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |