prompts.chat prompt-lookup 技能深度解析：让 Claude Code 自动完成 Prompt 检索、获取与增强

本篇基于 prompts.chat 官方 Claude 插件中的 prompt-lookup 技能定义展开，讲清这个“自动激活技能”的触发条件、三个核心 MCP 工具（search_prompts / get_prompt / improve_prompt）的参数语义与行为细节，并结合 MCP 服务端实现、变量解析逻辑 和 AI 增强管线 的源码，说明每个参数在底层究竟如何被处理。读完后你可以掌握：如何把 prompt 库接入 Claude Code、变量 ${var} / ${var:default} 的填充机制、以及 improve_prompt 的调用约束（鉴权、限流、输出类型）。

1. 技能定位：prompt-lookup 是什么，在插件中扮演什么角色

prompt-lookup 是 prompts.chat 官方 Claude Code 插件中两个“自动激活技能”（Auto-Activating Skills）之一，其完整定义位于 plugins/claude/prompts.chat/skills/prompt-lookup/SKILL.md，并在 skills/index.json 中注册：

{
  "name": "prompt-lookup",
  "description": "Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.",
  "files": ["SKILL.md"]
}

与姊妹技能 skill-lookup（负责发现/安装 Agent Skills）不同，prompt-lookup 的职责边界是单文件 Prompt 的发现、检索与增强（发现、获取、改进）。它的执行底座不是本地代码，而是 prompts.chat 的 MCP Server——插件通过 .mcp.json 声明了一个 HTTP 类型的 MCP 连接：

{
  "prompts.chat": {
    "type": "http",
    "url": "https://prompts.chat/api/mcp"
  }
}

从源码结构看，该端点对应 src/pages/api/mcp.ts，它基于 @modelcontextprotocol/sdk 的 McpServer + StreamableHTTPServerTransport 构建，每次 POST 请求都会带鉴权上下文（authenticatedUser）与可选的 categories / tags / users 查询参数过滤器重新 createServer()。服务端启用由 prompts.config.ts 中的 features.mcp: true 控制，关闭时端点直接返回 404 MCP is not enabled。

2. 触发条件：何时激活 prompt-lookup

技能文件在 “When to Use This Skill” 一节给出了 5 条明确的激活信号。当用户处于以下任一场景时，Agent 应当启用该技能并调用 prompts.chat MCP 工具：

• 索要 Prompt 模板：如 "Find me a code review prompt"；
• 想搜索 Prompt：如 "What prompts are available for writing?"；
• 需要获取某个具体 Prompt：如 "Get prompt XYZ"；
• 希望改进现有 Prompt：如 "Make this prompt better"；
• 提到了 prompts.chat 或 prompt 库（prompt libraries）。

这些触发条件的价值在于“意图前置”：用户不需要记住具体的 MCP 工具名，只要表达出上述任一意图，Agent 就能按技能定义的流程选择正确的工具、参数与结果呈现方式。插件顶层文档 CLAUDE-PLUGIN.md 的 “Skills (Auto-Activating) → Prompt Lookup” 小节也同步描述了这一激活语义，可作为插件级行为佐证。

3. 工具一：search_prompts —— 关键词检索 Prompt

3.1 参数说明（技能文件定义 + 源码实现）

技能文件要求调用 search_prompts 时携带以下参数，src/pages/api/mcp.ts 的 inputSchema（zod 定义）与之完全对应：

参数	必填	类型 / 取值	默认	说明
query	是	string	—	搜索关键词，取自用户请求
limit	否	number，1–50	10	返回条数上限（z.number().min(1).max(50).default(10)）
type	否	TEXT / STRUCTURED / IMAGE / VIDEO / AUDIO	无	按 Prompt 类型过滤
category	否	string（类别 slug）	无	如 "coding"、"writing"
tag	否	string（标签 slug）	无	按标签 slug 过滤

3.2 底层实现：检索是如何执行的

从 search_prompts 处理器 的源码可以看到几个关键行为：

1. 三字段关键词匹配：query 在 title、description、content 三个字段上做大小写不敏感的子串匹配（mode: "insensitive"），任一命中即返回；
2. 可见性过滤：结果恒排除 isUnlisted: true 与已软删除（deletedAt != null）的记录；未鉴权时仅返回公开 Prompt，已鉴权用户额外可见自己创建的私有 Prompt（OR: [{isPrivate: false}, {isPrivate: true, authorId: <me>}]）；
3. 排序与截断：按 createdAt 倒序取前 min(limit, 50) 条；
4. 返回字段：每条结果包含 id、slug、title、description、contentPreview（内容前 300 字符 + 省略号）、type、author（姓名优先、回退用户名）、category、tags、votes、createdAt。

3.3 结果呈现规范

技能文件要求检索结果以“可读格式 + 链接”呈现给用户，必须包含四要素：

• 标题与描述（Title and description）
• 作者名（Author name）
• 分类与标签（Category and tags）
• 指向 Prompt 的链接（Link to the prompt）

这与 MCP 返回结构逐字段对应：title / description / author / category + tags，链接则由 Prompt 的 id 与 slug 拼出（slug 的取法见 getPromptName：优先 slug 字段，其次 slugify(title)，最后回退 id）。

4. 工具二：get_prompt —— 按 ID 获取并填充变量

4.1 参数说明

技能文件定义 get_prompt 接收 id（Prompt ID）一个参数；在 服务端 schema 中还有一个默认关闭的进阶参数：

参数	类型	默认	行为
id	string	必填	要获取的 Prompt ID
fill_variables	boolean	false	true 且 Prompt 含模板变量时，触发交互式变量填充（MCP Elicitation）；false 时返回原始内容 + 变量元数据

4.2 变量语法：${variable} 与 ${variable:default}

技能文件明确了 prompts.chat 的变量约定，其服务端提取逻辑在 extractVariables 中：

// Format: ${variableName} or ${variableName:default}
const regex = /\$\{([a-zA-Z_][a-zA-Z0-9_\s]*?)(?::([^}]*))?\}/g;

• 无默认值的变量是必填项（required）；
• 带默认值的变量是可选的（optional）。

这一必填/可选划分直接体现在 Elicitation 表单的构造中（mcp.ts）：fill_variables: true 时，服务端为每个变量生成一个 string 型表单属性，description 标注 Value for ${name}(default: xxx)，只有 defaultValue 为空的变量名会进入 required 数组。

4.3 交互式填充的运行时行为（源码级细节）

当 fill_variables: true 且检测到变量时，服务端会向客户端发起 elicitation/create（mode: "form"）请求，源码中可见三层防护设计：

1. 10 秒超时：Promise.race 与 10000ms 定时器竞速，防止不支持 Elicitation 的客户端导致请求悬挂；
2. 拒绝回退：用户拒绝填值（action !== "accept"）时，返回原始 Prompt + variablesRequired 元数据，并附消息 "User declined to provide variable values. Returning original prompt."；
3. ReDoS 防护：回填替换前用 /^[a-zA-Z_][a-zA-Z0-9_\s]*$/ 校验变量名，跳过非法键，避免用户输入被拼进 new RegExp(...) 造成灾难性回溯。

替换完成后，返回体同时给出 content（填充后的内容）、originalContent（原文）、variables（用户填的值）与页面链接。若客户端完全不支持 Elicitation，则返回 variablesRequired + "Variables need to be filled manually." 的降级响应；若 fill_variables: false 而 Prompt 含变量，则返回 variables 元数据（name + defaultValue）与提示 hint，建议再次以 fill_variables=true 调用。

4.4 与变量生态的呼应

prompts.chat 对变量语法有一套完整的识别体系：src/lib/variable-detection.ts 的 detectVariables 能识别 [[name]]、{{name}}、[NAME]、{NAME}、<NAME>、%NAME% 等 7 种“类变量”写法，并内置 HTML 标签、语言关键字等误报黑名单，convertAllVariables 可将其统一归一为 ${name} / ${name:default} 形式（变量名小写化、空格转下划线）。这意味着从社区粘贴来的非标准占位符在入库阶段就有机会被规范化，而 get_prompt 的填充逻辑只负责消费这一标准形式。

5. 工具三：improve_prompt —— AI 增强 Prompt

5.1 参数说明

技能文件要求调用 improve_prompt 时传入三个参数，与服务端 schema 定义 一致：

参数	类型	默认	说明
prompt	string，1–10000 字符	必填	待改进的 Prompt 文本
outputType	text / image / video / sound	text	目标内容类型
outputFormat	text / structured_json / structured_yaml	text	期望的响应结构格式

技能文件要求：将增强后的 Prompt 返回给用户（Return the enhanced prompt to the user）。注意鉴权约束：improve_prompt 属于需要 API Key 认证的工具，未认证调用会直接返回 Authentication required. Please provide an API key.（mcp.ts）。

5.2 增强管线：模型、模板与“灵感”机制

improve_prompt 委托给 src/lib/ai/improve-prompt.ts 的 improvePrompt()，完整流程如下：

1. 前置检查：服务端必须配置 OPENAI_API_KEY，否则抛出 "AI features are not configured"；
2. 相似 Prompt 检索（灵感注入）：若 AI 搜索开关开启，对输入 Prompt 生成 embedding，在公开的、已计算 embedding 的 Prompt 中（按 outputType 映射到对应 type 过滤）取 100 条计算余弦相似度，以 0.3 为阈值取 Top 3 作为 “Inspirations”，拼进系统提示词（每条截断 500 字符）；
3. 提示词模板渲染：加载 improve-prompt.prompt.yml，将 {{similarPrompts}} 与 {{typeDefinitions}}（来自 src/data/type-definitions.ts 的 BuiltPrompt / BuiltImagePrompt 等接口定义）插值进 system 消息，{{outputType}} / {{outputFormat}} / {{originalPrompt}} 插值进 user 消息；
4. 模型调用：模型由环境变量 OPENAI_IMPROVE_MODEL 指定（默认 gpt-4o，OPENAI_BASE_URL 可切换兼容端点），temperature: 0.7、max_tokens: 4000（取自模板文件的 modelParameters）；
5. 返回结构：{ original, improved, outputType, outputFormat, inspirations: [{id, slug, title, similarity}], model }，其中 similarity 为四舍五入到整数的百分比。

模板的 system 指令定义了改进方法论：角色定义、上下文设定、任务澄清、约束补充、输出格式指定，以及“用 ${variable} 语法表达动态部分”等 7 项技术；同时规定绝不改变 Prompt 的根本目的、文本类 Prompt 采用 "Act as a [role]..." 角色扮演格式而媒体类（IMAGE/VIDEO/AUDIO）禁用角色扮演格式，且响应只输出改进后的 Prompt 本体（无解释、无代码围栏）。技能文件要求 Agent “改进时要向用户解释增强了什么”，恰好可以与返回体中的 inspirations（本次参考了哪些相似 Prompt）一并说明。

6. 行为准则（Guidelines）：技能对 Agent 的硬性约束

SKILL.md 末尾的 Guidelines 定义了四条 Agent 行为准则，是使用该技能时必须遵守的工作规范：

1. 先搜索，后原创：Always search before suggesting the user write their own prompt —— 在建议用户自己写 Prompt 之前，必须先调用 search_prompts 确认库里没有现成方案；
2. 可读呈现：搜索结果必须用带链接的可读格式展示；
3. 解释增强点：改进 Prompt 后要向用户说明具体增强了什么；
4. 建议元数据：保存 Prompt 时建议合适的 category 与 tag。

第 4 条指向了技能未直接调用、但同服务可用的写工具 save_prompt（schema：title ≤200 字符、content 必填且支持 ${variable} 语法、tags 最多 10 个且不存在时自动创建、category 传 slug、isPrivate 缺省时取账号的 mcpPromptsPublicByDefault 设置）。写类工具同样要求 API Key，且受更严的限流约束（见下节）。

7. 运行时工程约束：鉴权、限流与协议限制

技能文件聚焦于“如何调用”，而服务端还施加了一批 Skill 文档未展开、但对调用方（Agent）有实际影响的约束，均在 src/pages/api/mcp.ts 与 src/lib/rate-limit.ts 中可验证：

API Key 鉴权：从 PROMPTS_API_KEY（或 PROMPTS-API-KEY）请求头 / api_key 查询参数提取，经格式校验后查库认证，并带 5 分钟 TTL 的进程内缓存（authCache）。search_prompts / get_prompt 匿名可用（仅见公开内容），save_prompt / improve_prompt 及所有 skill 写工具强制认证。

分层限流（滑动窗口，进程内，按 API Key 或 IP 标识）：

限流器	阈值	适用范围
mcpGeneralLimiter	20 次/分钟	所有 MCP POST 请求
mcpToolCallLimiter	10 次/分钟	所有 tools/call
mcpWriteToolLimiter	5 次/分钟	save_prompt、save_skill、add_file_to_skill、update_skill_file、remove_file_from_skill
mcpAiToolLimiter	2 次/分钟	improve_prompt

超限返回 HTTP 429 与 JSON-RPC 错误码 -32000，消息中附带 retryAfterSeconds。源码注释明确说明该限流是按进程实现的，多实例部署下建议换用 Redis 方案——这属于当前实现的适用边界，值得在自行托管时留意。

协议与传输限制：GET 请求返回 405（该服务端为无状态、不支持 SSE 推送），DELETE 返回 204，仅 POST 处理 JSON-RPC；请求体上限 1MB，超出直接销毁连接并返回 413。

8. 延伸：技能之外的等价入口

prompt-lookup 技能是“自然语言触发”路径；同一组 MCP 工具还有两条显式入口，适合需要精确控制参数的场景：

• 斜杠命令 commands/prompts.md：/prompts.chat:prompts <query> [--type TYPE] [--category CATEGORY] [--tag TAG]，支持 get <prompt-id> 获取全文、save（需 API Key）、improve 子命令，其参数语义与本文第 3–5 节完全一致；
• prompt-manager 代理 agents/prompt-manager.md：面向跨步骤的复合工作流（搜索 → 获取 → 填变量 → 保存 → 增强），适合技能触发之外的显式委派。

9. 小结

prompt-lookup 是一份“薄技能、厚后端”的范例：SKILL.md 本体只声明触发条件、三个工具、参数约定与呈现规范（不足百行），而真正的技术含量全部由 prompts.chat 的 MCP Server 承担——三字段不敏感检索与可见性隔离（mcp.ts）、${var} / ${var:default} 变量提取与 Elicitation 填充（mcp.ts、variable-detection.ts）、embedding 灵感注入的 AI 增强管线（improve-prompt.ts）、以及四层滑动窗口限流与 1MB 载荷限制（rate-limit.ts）。理解这一层分工后，你可以既把它当作 Claude Code 中的即用能力，也可以对照源码在自托管部署中调整 features.mcp 开关、OPENAI_IMPROVE_MODEL 模型与限流参数，把 prompt 库能力接入自己的 Agent 工作流。