prompts.chat skill-lookup 技能详解：通过 MCP 工具搜索、获取并安装 Agent Skills

本篇指南以 prompts.chat 官方 Claude 插件中的 skill-lookup 技能文件 为主体，完整拆解它如何通过 search_skills 与 get_skill 两个 MCP 工具实现"搜索 → 展示 → 获取 → 安装 → 验证"的完整闭环，并结合 MCP 服务端实现 与 多文件技能解析库 讲清每个参数背后的真实行为。读完后，你将掌握如何在 Claude Code 中定位可复用的 Agent Skill、读取其全部文件、并以正确的目录结构安装到工作区。

skill-lookup 是什么

skill-lookup 是 prompts.chat 官方 Claude Code 插件内置的两个自动激活技能（Skills）之一，与负责提示词发现安装的 prompt-lookup 并列，统一登记在 技能索引文件 中。它的职责单一而明确：当用户要求查找技能、浏览技能目录、为 Claude 安装技能，或用可复用的 AI Agent 组件扩展 Claude 能力时，引导 Agent 使用 prompts.chat MCP 工具完成检索与安装。

技能文件采用标准 SKILL.md 格式，frontmatter 中只有三个字段：

---
name: skill-lookup
description: >
  Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools.
  Use when the user asks to find skills, browse skill catalogs, install a skill for Claude,
  or extend Claude's capabilities with reusable AI agent components.
license: MIT
---

name 用于标识技能本身，description 同时承担了"激活条件"的角色——从 index.json 的登记描述可以看到，Claude Code 会依据该描述判断用户意图是否匹配（询问 Agent Skills、想找可复用能力、需要安装技能、提到"skills for Claude"等场景）。这与仓库中 skill-files 工具库 对 frontmatter 的校验逻辑一致：name 必须是小写 kebab-case，description 必填，见 validateSkillFrontmatter 实现。

五步标准工作流

SKILL.md 定义的 Workflow 是整个技能的骨架，共五步：

1. 调用 search_skills 搜索与用户需求匹配的技能；
2. 以标题、描述、作者和文件清单的形式呈现结果；
3. 用户选定技能后，调用 get_skill 获取其全部文件；
4. 将文件保存到 .claude/skills/{slug}/ 并验证 SKILL.md 存在；
5. 确认安装成功，并向用户解释该技能的作用与激活时机。

原文档给出的最小调用示例：

search_skills({"query": "code review", "limit": 5, "category": "coding"})
get_skill({"id": "abc123"})

这两步分别对应"发现"与"落地"阶段：先用关键词 + 过滤条件缩小候选集，再凭 ID 拉取完整内容。下文逐节展开。

search_skills：参数与服务端真实行为

SKILL.md 声明 search_skills 接受四个参数：

参数	说明	约束
query	来自用户请求的搜索关键词	必填
limit	返回结果数量	默认 10，最大 50
category	按分类 slug 过滤（如 coding、automation）	可选
tag	按标签 slug 过滤	可选

SKILL.md 要求搜索结果至少呈现：标题与描述、作者名、文件清单（SKILL.md、参考文档、脚本）、分类与标签、以及指向该技能的链接。这些字段并非空口约定，在服务端实现中逐一对应：mcp.ts 中 search_skills 的注册 里，输入模式通过 Zod 严格约束了 limit 的取值范围（z.number().min(1).max(50).default(10)），返回体为 { query, count, skills: [...] }，每条结果携带 id、slug、title、description、author、category、tags、votes、fileNames、fileCount、createdAt 与 link 字段——正好覆盖 SKILL.md 要求展示的每一项。

从源码结构看，search_skills 的检索逻辑有几个值得注意的实现细节：

• 检索字段：query 会在 title、description 与 content（技能正文/多文件内容）三个字段上做大小写不敏感的子串匹配，即 mode: "insensitive" 的 contains 查询，因此搜索词不需要精确命中标题；
• 过滤条件：结果被硬性限定为 type: "SKILL"、isUnlisted: false、deletedAt: null，即只会返回公开上架且未软删除的技能；
• 可见性：未认证用户只能看到 isPrivate: false 的公开技能；已认证用户额外可见自己创建的私有技能（isPrivate: true && authorId = 当前用户）；
• 排序与截断：按 createdAt 降序排列，取 Math.min(limit, 50) 条。

这些细节意味着：如果你用 category: "coding" 搜索却得到空结果，可以先不带过滤条件重搜以确认技能是否确实公开上架；私有技能在未带 API key 认证时是搜不到的。

get_skill：按 ID 拉取技能的全部文件

get_skill 只接收一个参数 id（技能 ID），返回该技能的元数据与全部文件内容——这正是多文件技能（multi-file skill）与单文件提示词的本质区别。返回内容包含：

• SKILL.md（主指令文件）；
• 参考文档（reference docs）；
• 辅助脚本（scripts）；
• 配置文件。

在服务端 get_skill 实现 中，可以看到返回体的具体字段：id、slug、title、description、author、category、tags、votes、isPrivate、createdAt、updatedAt、files（每项为 { filename, content }）以及 link（私有技能返回 null）。其中可见性过滤与 search_skills 相同：公开技能人人可取，私有技能仅作者本人可取。

多文件技能是如何存储在一条记录里的

一个容易忽视的问题是：一个技能包含多个文件，服务端为什么能用单一 content 字段存下它们？答案在 src/lib/skill-files.ts 中——多个文件被序列化进一个文本字段，文件之间用 ASCII 控制字符作为分隔符：

file 1 content
\x1FFILE:filename.ext\x1E
file 2 content
\x1FFILE:another-file.md\x1E
file 3 content

其中 \x1F（ASCII 31，Unit Separator）标记分隔起始、\x1E（ASCII 30，Record Separator）标记结束。源码注释解释得很直接：这两个控制字符不可能出现在正常文本中，因此分隔方案是"注入免疫"（injection-proof）的——文件内容里即使真的写有 \x1FFILE:xxx\x1E 字样也不会造成误切分（正则按已出现的分隔符整体切分）。get_skill 内部正是调用 parseSkillFiles 把存储串还原为 { filename, content }[] 数组后返回给客户端。该库同样提供 serializeSkillFiles 做逆过程：SKILL.md 内容恒置于最前，其余文件依次追加分隔符与内容。相关行为有专项测试覆盖，见 skill-files.test.ts。

安装技能：目录结构与落盘验证

SKILL.md 将安装流程固化为四步：

1. 调用 get_skill 取回全部文件；
2. 创建目录 .claude/skills/{slug}/；
3. 逐个保存文件：SKILL.md → .claude/skills/{slug}/SKILL.md，其余文件 → .claude/skills/{slug}/{filename}（保留原相对路径，如 scripts/helper.py）；
4. 回读 SKILL.md，验证 frontmatter 完好无损。

这里的 {slug} 并非随意命名：get_skill 返回体中的 slug 字段由服务端生成，多文件技能的目录形态（SKILL.md 为主指令 + 参考文档 + 脚本 + 配置文件）与 skill-manager agent 文档 中的 "Skill Structure" 一节完全对应。需要注意的一个细节是：仓库内 skills 命令文档 中 install 子命令说明的落盘位置为 .claude/prompts.chat:skills/{slug}/，而 skill-lookup 技能文件本身要求安装到 .claude/skills/{slug}/，两处路径表述存在差异；若你在自己的项目中复现该流程，建议以你实际启用的 Claude 技能目录约定为准，并在安装后以"SKILL.md 可被回读且 frontmatter 完整"作为统一的成功判据。

第 4 步"回读验证"并非多余仪式。服务端对技能内容的 frontmatter 有一套明确的校验规则（validateSkillFrontmatter）：frontmatter 缺失、name 缺失或为占位值 my-skill-name、name 不符合 kebab-case（正则 ^[a-z][a-z0-9-]*$）、description 缺失都会被判为非法。安装时若传输或落盘过程损坏了 frontmatter，该技能将无法正常激活——回读检查正是针对这一失败模式。

操作准则与生态定位

SKILL.md 最后给出四条 Guidelines，也是这套工作流的行为边界：

• 先搜索，再考虑自建：在建议用户自己编写技能之前，必须先执行搜索；
• 可读地呈现结果：搜索结果需以人类可读格式展示，并带文件数量；
• 安装必须确认：安装后要明确告知保存是否成功；
• 解释能力与激活时机：说明技能做什么、何时被触发。

放在整个插件生态中看，skill-lookup 处于"自动激活层"。按 CLAUDE-PLUGIN.md 的说明，插件分四层：MCP Server（实时访问 prompts.chat API）、Commands（/prompts.chat:skills 斜杠命令）、Agents（skill-manager 管理智能体）与 Skills（自动激活技能）。skill-lookup 与 prompt-lookup 属于最轻量的第四层：不需要用户显式调用命令，只要对话意图匹配 description 即被激活；而涉及创建技能、增删技能文件等写操作（save_skill、add_file_to_skill、update_skill_file、remove_file_from_skill，均需 API key 且不允许删除 SKILL.md）则由 skill-manager agent 承担。

插件的安装方式同样记录在 CLAUDE-PLUGIN.md：先 /plugin marketplace add f/prompts.chat 添加市场，再 /plugin install [e-mail] 安装插件；搜索类工具无需认证，仅在需要保存/创建等写操作时才需提供 API key（环境变量 PROMPTS_API_KEY 或 MCP 连接头 PROMPTS_API_KEY）。

小结

skill-lookup 用一个不到百行的 SKILL.md 定义了一条完整的技能分发链路：以 description 驱动自动激活，以 search_skills（关键词 + category/tag 过滤，服务端大小写不敏感、限 50 条、按创建时间倒序）完成发现，以 get_skill 拉取由控制字符分隔方案安全存储的多文件内容，最后按 .claude/skills/{slug}/ 结构落盘并回读 frontmatter 验证。理解了它的五步工作流与背后的 MCP 工具实现、文件解析与校验逻辑，你就能在自己的 Claude Code 工作区中可靠地发现并安装任意公开 Agent Skill，也为自行编写符合规范的 SKILL.md（kebab-case 名称、必填激活描述、可多文件组织）打下了参照基础。