skill-fetch

Skill Fetch

并行搜索、评分并安装来自多个注册表的 Agent 技能。

适用场景

• skill-eval 钩子输出“MISSING EXTERNAL SKILL”
• 当前任务需要本地未提供的领域专业知识
• 用户要求“获取技能”“搜索技能”或“安装技能”

关键规则

1. 决定之前绝不使用 skillsmp_get_skill_content 预览——搜索描述已足够。仅在安装失败时将其用作后备方案。
2. 首轮有结果就停止，只有零结果时才继续（最多 5 轮）——任何一轮有 ≥1 个结果，都应进入分析。
3. 只有用户可以决定跳过——LLM 绝不能自行跳过安装。
4. 始终使用纯文本交互——不要使用 AskUserQuestion。输出分析并等待用户以数字或命令回复。
5. 每页最多显示 5 个结果——提供完整分析（内容、优点、缺点、仓库 URL），以便用户做出明智选择。

平台兼容性

此技能适用于 6 种以上 AI 编码 Agent（Claude Code、Cursor、Codex、Gemini CLI、Windsurf、Amp）。工具名称会自动适配。完整映射表请参阅 references/platform-adapters.md。

流程

步骤 0：SkillsMP MCP 自检（仅限 Claude Code）

搜索之前，请确认 SkillsMP MCP 服务可用：

1. 首先，尝试加载延迟加载的工具：运行 ToolSearch("skillsmp")，加载任何延迟加载的 SkillsMP MCP 工具。在 Claude Code 中，MCP 工具通常会延迟加载（请求前不会加载），名称带有命名空间，例如 mcp__skillsmp__skillsmp_search。ToolSearch 调用会解析这些工具。
2. ToolSearch 之后，检查是否有任何 skillsmp_* 或 mcp__skillsmp__* 工具可用
3. 如果可用 → 继续步骤 1
4. 如果仍不可用 → 运行：claude mcp add --scope user skillsmp -- npx -y skillsmp-mcp-server
5. 告知用户：“SkillsMP MCP 服务已注册。重启会话后即可使用。现在将继续使用其余 7 个来源进行搜索。”
6. 继续步骤 1（本次会话将跳过 SkillsMP 来源，但之后的会话中可用）

工具名称说明：SkillsMP 工具可能带有 MCP 命名空间前缀，例如 mcp__skillsmp__skillsmp_search，而不是 skillsmp_search。两种形式都可用——使用当前可用的形式即可。

非 Claude Code Agent：跳过此步骤。SkillsMP 工具仅适用于 Claude Code。

步骤 0.5：加载 API 密钥（必须——在步骤 2 之前执行）

来源 8–9 需要 API 密钥。读取配置文件以确认密钥是否可用：

1. 现在读取 ~/.claude/skills/.fetch-config.json——未读取文件前，不要假定密钥不存在
2. 预期格式：

   {
     "SKILLHUB_API_KEY": "sk-sh-...",
     "SKILLS_DIRECTORY_API_KEY": "sk_live_..."
   }
   

3. 记录结果——设置两个标志，以便在步骤 2b 中使用：
   • HAS_SKILLHUB_KEY：true/false
   • HAS_SKILLS_DIR_KEY：true/false
4. 如果配置文件不存在 → 两个标志都设为 false，并告知用户可以创建该文件
5. 如果配置文件存在但缺少某个特定密钥 → 对应标志设为 false

⚠️ 常见失败模式：LLM 跳过读取配置文件，直接假定“没有密钥”。即使已配置密钥，这也会导致错误跳过来源 8–9。务必先读取文件。

步骤 1：确定搜索关键词和来源

**URL 模式：**如果 $ARGUMENTS 是 URL（以 https://github.com/... 或任意 https:// 开头），直接跳到步骤 3 的安装流程。

搜索模式：

• 有 $ARGUMENTS：直接将其用作搜索词
• 没有搜索词（自动触发）：优先使用钩子输出中的 Suggested search terms，否则从任务上下文中提取 2–3 个查询词

步骤 2：并行搜索——全部 9 个来源（必需）

⚠️ 必须：你必须调用全部 9 个来源。只有在全部 9 个来源均已返回结果或失败后，才能继续评分。

⚠️ 常见失败模式：LLM 调用来源 1-2（SkillsMP）并获得结果后，就跳过来源 3-9。这是错误的。仅有 SkillsMP 的结果并不充分——GitHub、ClawhHub、skills.sh 和 PolySkill 中包含 SkillsMP 未收录的不同技能。

⚠️ 执行顺序：继续到步骤 2.5 之前，必须完成步骤 2a 和步骤 2b。仅完成步骤 2a 并不足够。

步骤 2a：调用 SkillsMP 来源（1-2）

#	来源	工具调用	后备方案
1	SkillsMP AI	skillsmp_ai_search × 3 个查询变体（并行）	MCP 不可用时跳过
2	SkillsMP 关键词	skillsmp_search(query)	MCP 不可用时跳过

步骤 2b：调用非 SkillsMP 来源（3-9）——不得跳过

⚠️ 即使步骤 2a 已返回结果，也必须调用这些来源。这些来源包含 SkillsMP 未收录的技能。

#	来源	工具调用	后备方案
3	GitHub 仓库	gh search repos "{query}" --json name,description,url,stargazersCount,updatedAt --limit 5 --sort stars（不要追加 "skill SKILL.md"）	gh search code "{query}" --filename SKILL.md --limit 5
4	Anthropic Skills	gh search code "{query}" --repo anthropics/skills --filename SKILL.md --limit 5	gh api 树回退方案
5	ClawhHub	npx -y clawhub search "{query}"	失败时跳过
6	skills.sh	WebFetch("https://skills.sh/api/search?q={query}&limit=5")	通过 Bash 执行 curl -s
7	PolySkill	npx -y @polyskill/cli search "{single_keyword}" --limit 5（从查询中提取最具体的单个关键词——多词查询会返回 0 个结果）	失败时跳过（无 REST API）
8	SkillHub	如果 HAS_SKILLHUB_KEY = true（来自步骤 0.5）：bash {SKILL_BASE_DIR}/scripts/fetch-skillhub.sh "{query}"。如果为 false：npx -y @skill-hub/cli search "{query}" --limit 5（超时：10000）	失败时使用 CLI 后备方案
9	Skills Directory	如果 HAS_SKILLS_DIR_KEY = true（来自步骤 0.5）：bash {SKILL_BASE_DIR}/scripts/fetch-skills-directory.sh "{query}"。如果为 false：跳过。绝不要直接使用 curl 或 WebFetch。	仅当步骤 0.5 确认密钥不存在时才跳过

**⚠️ 来源 8-9 需要先执行步骤 0.5。**如果跳过了步骤 0.5，请立即返回并读取 ~/.claude/skills/.fetch-config.json，然后再将来源 8-9 标记为跳过。{SKILL_BASE_DIR} = 此技能的基础目录（技能加载时显示在顶部）。

有关详细参数、响应格式、查询变体示例和 curl 后备命令，请参阅 references/search-sources.md。

⚠️ 搜索后检查清单（继续到步骤 2.5 之前必须完成）：

评分前，输出此检查清单，并注明每个来源的实际状态：

Step 0.5 config: HAS_SKILLHUB_KEY={true/false} HAS_SKILLS_DIR_KEY={true/false}
Sources queried: [1] SkillsMP AI ✅ [2] SkillsMP KW ✅ [3] GitHub ✅/❌ [4] Anthropic ✅/❌ [5] ClawhHub ✅/❌ [6] skills.sh ✅/❌ [7] PolySkill ✅/❌ [8] SkillHub ✅/❌ [9] Skills Dir ✅/❌

验证规则——继续之前返回并修正：

• 如果来源 3-7 全部为 ❌ → 立即重新执行来源 3-7
• 如果 HAS_SKILLHUB_KEY=true 但 [8] 为 ❌ → 立即执行 bash {SKILL_BASE_DIR}/scripts/fetch-skillhub.sh
• 如果 HAS_SKILLS_DIR_KEY=true 但 [9] 为 ❌ → 立即执行 bash {SKILL_BASE_DIR}/scripts/fetch-skills-directory.sh
• 如果从未执行步骤 0.5（上方没有配置行）→ 立即读取 ~/.claude/skills/.fetch-config.json，然后重新评估来源 8-9

全部来源均已返回后 → 去重（参阅 references/search-sources.md）→ 继续到步骤 2.5。

轮次策略（最多 5 轮）：“≥1 个结果 → 停止”规则适用于轮次，而非单个来源。在单轮内必须查询全部 9 个来源。只有当某一轮的全部 9 个来源均返回 0 个结果时，才使用更宽泛的关键词进入下一轮。如果某一轮中任意来源返回 ≥1 个结果，则继续评分（不要开始新一轮）。

步骤 2.5：评分与排序

为每个去重后的结果计算质量分数（0-100）。详情请参阅 references/quality-signals.md。

评分公式： 总分 = 相关性(0-40) + 新鲜度(0-25) + 社区(0-20) + 信任度(0-15) + 外部加分(0-5)

补充查询： 对排名前 5 的结果，使用 gh api repos/{owner}/{repo} --jq '{pushed_at,stargazers_count}' 获取更新时间和 GitHub 星标数。对于星标数较高（≥50）且描述完全匹配的结果，跳过查询。最多调用 3 次 gh api。

等级标签： 🟢 85+ 强烈推荐 | 🟢 70-84 推荐 | 🟡 55-69 值得考虑 | 🟡 40-54 勉强可选 | 🔴 <40 不推荐

步骤 3：分析、选择、安装

完整的安装工作流请参阅 references/installation-guide.md。

快速参考 — 流程：

1. 3a. 显示排序后的结果（每页 5 条，包含分数和优缺点）
2. 3b. 等待用户回复（输入编号进行安装，输入 c 查看下一页，输入 skip 结束）
3. 3c. 询问安装位置（G=全局，L=本地）——必须执行
4. 3d. 执行安装（SkillsMP → 信任但验证；GitHub → 获取完整资源包，而不仅是 SKILL.md，然后对每个文件进行安装前扫描）。GitHub URL 请使用 scripts/fetch-skill-bundle.sh。
5. 3e. 安装后验证（文件是否存在、frontmatter、冲突检查、资源包是否完整、对每个已安装文件计算 SHA-256）
6. 3f. 更新 ~/.claude/skills/.fetch-metadata.json
7. 3g. 激活并向用户确认

⚠️ 重要： 从 GitHub 安装时，技能是一个完整目录，而非单个 SKILL.md 文件——还包括 references/、scripts/、assets/、templates/、prompts/、data/ 等。如果某项技能依赖这些文件，只下载 SKILL.md 会导致安装无法正常工作。务必获取完整资源包。

步骤 4：梳理已安装的资源包

已安装的技能是一个目录，而不是单个 SKILL.md。许多技能会将内容拆分到子目录中，例如 references/（文档）、scripts/（辅助工具）、assets/、templates/、prompts/、data/、examples/ 等。如果只阅读 SKILL.md，可能会遗漏技能作者预期你按需加载的指令。

1. 使用 Glob 列出完整的已安装目录树：{install-path}/{skill-name}/**/*。
2. 验证资源包是否完整。 如果 SKILL.md 引用了相对路径（bash scripts/foo.sh、See references/bar.md、Load assets/template.json），而这些文件缺失，则安装不完整——请重新获取 GitHub 完整资源包（参见 references/installation-guide.md §3d）。
3. 直接阅读与当前任务相关的文件（检查前 30 行以判断相关性）。不要只查看 references/——相关文件可能位于 prompts/、templates/ 或其他子目录中。
4. 总结可供后续规划使用的关键信息。

完成后，输出：External skill installed successfully: {skill-name}

完成语句

• 成功：External skill installed successfully: {name}
• 已跳过：External skill fetch: user chose to skip installation.

附加资源

合理化表和危险信号位于 references/interaction-patterns.md。在考虑跳过步骤时，请查阅此文档。

• references/interaction-patterns.md — 输出模板、用户回复处理、安全审查
• references/quality-signals.md — 质量评估维度、查找方法、排序算法
• references/search-sources.md — 特定来源的命令、错误处理、去重规则
• references/platform-adapters.md — 跨平台工具映射、安装路径、回退策略
• references/installation-guide.md — 完整的步骤 3 安装工作流（3a-3g）
• references/local-index.md — 本地技能/插件扫描实现，用于搜索前去重
• scripts/fetch-skillhub.sh — SkillHub API 搜索（从 ~/.claude/skills/.fetch-config.json 读取密钥）
• scripts/fetch-skills-directory.sh — Skills Directory API 搜索（从配置文件读取密钥）
• scripts/fetch-skill-bundle.sh — 从任意 GitHub blob/tree/raw URL 下载完整技能包（SKILL.md + 所有同级文件/子目录），并保留目录结构