企业官网建设流程全解析

Klavis Context7 文档检索 Skill 深度解析：让 AI 编码助手自动获取最新库文档

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis

在 AI 编码助手中，"训练数据过期导致 API 幻觉"是最常见的问题之一。Klavis 仓库内的 Context7 插件（位于mcp_servers/context7/plugins/claude/context7/）为此设计了一个名为documentation-lookup的 Skill：当用户询问库、框架或需要代码示例时，该 Skill 自动触发，引导 Agent 调用 Context7 MCP 工具的resolve-library-id与query-docs，从实时文档源获取当前准确的资料，而不是依赖模型记忆。读完本文，你将掌握该 Skill 的触发条件、四步文档获取工作流、参数传递细节、版本固定（version pinning）策略，以及它在 MCP 服务端源码中的真实工具注册实现。

一、documentation-lookup Skill 是什么

documentation-lookup是 Context7 Claude Code 插件中的一个 Skill 文件，位于 SKILL.md。它是纯 Markdown 描述的提示词模板，通过 YAML frontmatter 声明元信息：

--- name: documentation-lookup description: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc. ---

• name：Skill 的标识名，即documentation-lookup；
• description：描述该 Skill 的激活场景，客户端（Claude Code 等）依据这段描述判断何时自动启用该 Skill。

Skill 的核心指令只有一句话："当用户询问库、框架或需要代码示例时，使用 Context7 获取当前文档，而不是依赖训练数据（use Context7 to fetch current documentation instead of relying on training data）。"

Context7 插件在 README 中将其定位为四大组件之一：MCP Server 提供工具、Skills 负责在用户询问库时自动触发文档检索、Agents 提供独立的docs-researcher子代理、Commands 提供手动查询入口/context7:docs。

二、Skill 的触发条件

SKILL.md 明确列出了四类激活场景，用户出现以下任一情况时即应启用该 Skill：

这一设计让文档检索"无感"触发——用户不需要在提示词中显式写 "use context7"。这一点在 Claude Code 集成文档 中也有印证：插件安装后，Skill 会自动识别"何时需要文档"，用户可直接问"How do I set up authentication in Next.js 15?"这类问题。

三、四步文档获取工作流（核心）

这是 SKILL.md 的核心内容，规定了 Agent 从用户问题到最终回答必须走完的四步：

Step 1：解析库 ID（resolve-library-id）

调用resolve-library-id工具，传入两个参数：

• libraryName：从用户问题中提取的库名；
• query：用户的完整问题原文（文档明确指出这能提升相关性排序）。

Step 2：选择最佳匹配

从解析结果中依据三条标准挑选目标库：

1. 与用户所问名称完全匹配或最接近；
2. 更高的 benchmark score 代表更好的文档质量；
3. 如果用户提及版本（如 "React 19"），优先选择版本专属 ID。

Step 3：获取文档（query-docs）

调用query-docs工具，传入：

• libraryId：选定的 Context7 库 ID（格式如/vercel/next.js）；
• query：用户的具体问题。

Step 4：使用文档

将取回的文档融入回答：

• 使用当前、准确的信息回答用户问题；
• 附上文档中的相关代码示例；
• 在相关时注明库的版本。

这套流程在插件的 docs-researcher 代理定义 中被原样复用并进一步细化（增加"识别库名""返回聚焦回答"等步骤），说明四步工作流是整个插件的统一检索协议。

四、源码级印证：两个工具在 MCP 服务端如何注册

上述两个工具并非 Skill 自行实现，而是由 Context7 MCP Server 注册的真实 MCP 工具。在 MCP 服务端入口 中可以看到它们的完整注册逻辑，与 SKILL.md 描述的参数一一对应：

resolve-library-id 的输入与返回

server.registerTool( "resolve-library-id", { title: "Resolve Context7 Library ID", inputSchema: { query: z.string().describe( "The user's original question or task. This is used to rank library results by relevance ..."), libraryName: z.string().describe( "Library name to search for and retrieve a Context7-compatible library ID."), }, ...

要点（依据源码描述，可直接用于指导实践）：

• 前置约束：工具描述明确要求"除非用户直接提供了/org/project或/org/project/version格式的库 ID，否则必须先调用resolve-library-id再调用query-docs"；
• 调用上限：工具描述中写入 "Do not call this tool more than 3 times per question"，即每个问题最多调用 3 次，超出后应使用已有最佳结果——这是对 Agent 行为的硬约束；
• 返回字段：每条结果包含 Library ID（/org/project格式）、Name、Description、Code Snippets（可用代码示例数）、Source Reputation（High/Medium/Low/Unknown）、Benchmark Score（100 为最高分）、以及可用 Versions 列表；
• 版本提示：当结果包含 Versions 且用户在问题中给出了版本时，应使用/org/project/version形式的 ID；
• 该工具带readOnlyHint: true注解，表明只读、无副作用。

query-docs 的输入与约束

inputSchema: { libraryId: z.string().describe( "Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') ..."), query: z.string().describe( "The question or task you need help with. Be specific and include relevant details. Good: 'How to set up authentication with JWT in Express.js' ... Bad: 'auth' or 'hooks' ..."), }

源码中对query参数的描述与 SKILL.md "Be specific" 的准则相互印证：好的 query 是"How to set up authentication with JWT in Express.js"，坏的 query 是孤立的"auth"或"hooks"。两个工具的 description 中同时强调：query 中不得包含 API 密钥、密码、凭据或个人数据等敏感信息。

底层请求目标

服务端所有检索请求最终指向 Context7 的 API 基址，定义在 constants.ts：

const CONTEXT7_BASE_URL = "https://context7.com"; const MCP_RESOURCE_URL = "https://mcp.context7.com"; export const CONTEXT7_API_BASE_URL = process.env.CONTEXT7_API_URL || `${CONTEXT7_BASE_URL}/api`;

CONTEXT7_API_URL、RESOURCE_URL、AUTH_SERVER_URL均支持环境变量覆盖，说明 Skill 所依赖的文档服务是远端服务，本地 MCP Server 只是协议桥接层。

五、行为准则：让检索更准的三个 Guidelines

SKILL.md 的 Guidelines 部分给出三条可操作的检索准则，其依据均可在源码中找到对应：

1. Be specific（具体化）：把用户完整问题作为 query 传入。对应query-docs工具描述中"Good/Bad"示例的对比，越具体召回越准；
2. Version awareness（版本感知）：用户提到版本（"Next.js 15"、"React 19"）时，优先使用解析步骤返回的版本专属库 ID。库 ID 的版本格式为/org/project/version，例如/vercel/next.js/v15.1.8、/supabase/supabase/v2.45.0（示例见 插件 README 的 "Version Pinning" 一节）。resolve-library-id返回的 Versions 列表可帮助挑出与项目一致的版本；
3. Prefer official sources（优先官方源）：多个匹配时，优先官方/主包而非社区 fork。这与工具描述中的 Source Reputation（High/Medium 更权威）排序维度一致。

六、Skill 的插件生态位：与 Agent、Command 的分工

documentation-lookupSkill 不是孤立存在的。Context7 插件（README）为"查文档"这一目标提供了三种互补入口，理解它们能避免重复造轮子：

Command 定义中还给出了带版本固定的完整示例：

/context7:docs /vercel/next.js/v15.1.8 middleware /context7:docs /facebook/react/v19.0.0 use hook

其工作机制（来自 commands/docs.md）：库名以/开头时直接作为 Context7 ID 使用；否则先经resolve-library-id匹配，再经query-docs取回文档。

七、安装与运行方式

Skill 随 Context7 插件整体分发，按 插件 README 在 Claude Code 中安装：

claude plugin marketplace add upstash/context7 claude plugin install context7-plugin@context7-marketplace

安装后 Skill、Agent、Command 一并生效。若只关注 Skill 本身，Context7 CLI 也提供了独立的 skills 安装机制（见 docs/skills.mdx）：

ctx7 skills install <project> <skill> --claude # 安装到 .claude/skills/ ctx7 skills list --claude # 查看已安装

Skill 依赖的 MCP Server 有两种接入方式（见 docs/clients/claude-code.mdx）：

# 远程托管 Server（推荐，无本地依赖） claude mcp add --header "CONTEXT7_API_KEY: YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp # 本地 Server（需 Node.js 18+，包版本见 server.json：@upstash/context7-mcp 2.0.2） claude mcp add context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY

接入后可用/mcp或claude mcp list验证连接状态。从 server.json 可见，CONTEXT7_API_KEY为可选（isRequired: false）的密钥型环境变量，未配置时走匿名访问端点，配置后走带鉴权的端点。

八、小结

documentation-lookupSkill 用一份简短的 Markdown 定义了 AI 编码助手"查文档"的标准作业程序：四类触发条件 + 四步工具调用流程 + 三条行为准则。它的价值在于把"何时查、查哪个库、怎么传参、版本怎么选"这些决策固化成 Agent 可遵循的确定性流程，且每个环节都能在 MCP 服务端源码 的工具注册描述中找到对应约束（3 次调用上限、版本 ID 格式、官方源优先）。在 Klavis 这类聚合大量 MCP Server 的仓库中，这种"Skill 驱动工具编排"的模式是 AI Agent 可靠使用外部工具服务的典型范例。

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis