context7-auto-research

Context7 自动研究技能

此技能会在检测到与库／框架相关的查询时，自动从 Context7 API 获取最新文档，确保回答使用最新信息，而非可能过时的训练数据。

自动激活触发条件

当用户的消息包含以下内容时，此技能应主动激活：

实现相关

• “如何实现”／“怎么写”／“怎么做”
• “How do I...”／“How to...”／“How can I...”
• “Show me how to...”／“Write code for...”

配置相关

• “配置”／“设置”／“安装”
• “configure”／“setup”／“install”
• “初始化”／“initialize”

文档相关

• “文档”／“参考”／“API”
• “documentation”／“docs”／“reference”
• “查看”／“look up”

库／框架提及

• React、Vue、Angular、Svelte、Solid
• Next.js、Nuxt、Remix、Astro
• Express、Fastify、Koa、Hono
• Prisma、Drizzle、TypeORM
• Supabase、Firebase、Clerk
• Tailwind、shadcn/ui、Radix
• 任何 npm 包或 GitHub 仓库

代码生成请求

• “生成代码”／“写一个”／“创建”
• “generate”／“create”／“build”
• “implement”／“add feature”

研究流程

触发后，请遵循以下工作流：

第 1 步：提取库信息

从用户的查询中识别库／框架：

• 库名称（例如，“react”、“next.js”、“prisma”）
• 版本（如有指定，例如，“React 19”、“Next.js 15”）
• 提及的具体功能／API（例如，“useEffect”、“middleware”、“relations”）

第 2 步：搜索库

使用 Task 工具调用 context7-fetcher 子技能：

Task parameters:
- subagent_type: Bash
- description: "Search Context7 for library"
- prompt: node .claude/skills/context7-auto-research/context7-api.cjs search "<library-name>" "<user-query>"

示例：

Task: Search for Next.js
Prompt: node .claude/skills/context7-auto-research/context7-api.cjs search "next.js" "How to configure middleware in Next.js 15"

响应格式：

{
  "libraries": [
    {
      "id": "/vercel/next.js",
      "name": "Next.js",
      "description": "The React Framework",
      "trustScore": 95,
      "versions": ["v15.1.8", "v14.2.0", "v13.5.0"]
    }
  ]
}

为什么使用 Task 工具？

• 使用 context7-fetcher 子技能中的 context: fork
• 避免在 API 调用中携带对话历史
• 减少 Token 消耗

第 3 步：选择最佳匹配项

根据搜索结果，按以下条件选择库：

1. 名称完全匹配用户的查询
2. 信任度最高（代表质量／受欢迎程度）
3. 如果用户指定了版本，则版本匹配（例如，“Next.js 15” → 优先选择 v15.x）
4. 优先选择官方包，而非社区分支

第 4 步：获取文档

使用 Task 工具调用 context7-fetcher 子技能：

Task parameters:
- subagent_type: Bash
- description: "Fetch documentation from Context7"
- prompt: node .claude/skills/context7-auto-research/context7-api.cjs context "<library-id>" "<specific-query>"

示例：

Task: Fetch Next.js middleware docs
Prompt: node .claude/skills/context7-auto-research/context7-api.cjs context "/vercel/next.js" "middleware configuration"

响应格式：

{
  "results": [
    {
      "title": "Middleware",
      "content": "Middleware allows you to run code before a request is completed...",
      "source": "docs/app/building-your-application/routing/middleware.md",
      "relevance": 0.95
    }
  ]
}

为什么使用 Task 工具？

• API 调用使用独立上下文
• 不会产生对话历史开销
• 执行速度更快

第 5 步：整合到回答中

使用获取的文档来：

1. 使用最新信息准确回答
2. 包含文档中的代码示例
3. 在相关时注明版本
4. 提供有关该功能／API 的背景信息

辅助脚本用法

context7-api.cjs 脚本提供两个命令：

搜索库

node context7-api.cjs search <libraryName> <query>

• 返回匹配的库及其元数据
• 用于初步解析库

获取上下文

node context7-api.cjs context <libraryId> <query>

• 返回相关文档片段
• 选择库后使用

环境设置

该脚本支持两种方式配置 API 密钥：

选项 1：.env 文件（推荐）

在技能目录中创建 .env 文件：

# In .claude/skills/context7-auto-research/.env
CONTEXT7_API_KEY=your_api_key_here

你可以从示例文件复制：

cp .env.example .env
# Then edit .env with your actual API key

选项 2：环境变量

export CONTEXT7_API_KEY="your-api-key"

优先级： 环境变量 > .env 文件

获取 API 密钥： 访问 context7.com/dashboard 注册并获取 API 密钥。

如果未设置，API 将使用公共速率限制（配额较低）。

最佳实践

查询明确度

• 将完整的用户问题作为 query 参数传递，以提高相关性
• 包含具体功能名称（例如，“useEffect cleanup”而不只是“useEffect”）

版本意识

• 用户提及版本时，使用特定版本的库 ID
• 示例：使用 /vercel/next.js/v15.1.8，而不是 /vercel/next.js

错误处理

• 如果库搜索没有结果，请告知用户并建议替代方案
• 如果 API 失败，则回退到训练数据，但需说明信息可能已过时
• 妥善处理速率限制（429 错误）

响应质量

• 不要倾倒整篇文档，而应提取相关部分
• 如需提供完整答案，可结合多个文档片段
• 始终提供实用的代码示例

工作流示例

示例 1：React Hook 问题

用户：“如何在 React 19 中使用 useEffect 获取数据？”

技能操作：

1. 检测触发词：“如何使用” + “useEffect” + “React 19”
2. 搜索：node context7-api.cjs search "react" "useEffect fetch data"
3. 选择：/facebook/react/v19.0.0（匹配版本）
4. 获取：node context7-api.cjs context "/facebook/react/v19.0.0" "useEffect data fetching"
5. 使用当前的 React 19 模式作答（例如，在适用时使用 use() Hook）

示例 2：Next.js 配置

用户：“配置 Next.js 15 的中间件”

技能操作：

1. 检测触发词：“配置” + “Next.js 15” + “中间件”
2. 搜索：node context7-api.cjs search "next.js" "middleware configuration"
3. 选择：/vercel/next.js/v15.1.8
4. 获取：node context7-api.cjs context "/vercel/next.js/v15.1.8" "middleware"
5. 使用 Next.js 15 中间件设置作答

示例 3：Prisma 关系

用户：“展示如何在 Prisma 中定义一对多关系”

技能操作：

1. 检测触发词：“展示如何” + “Prisma”
2. 搜索：node context7-api.cjs search "prisma" "one-to-many relations"
3. 选择：/prisma/prisma（信任评分最高）
4. 获取：node context7-api.cjs context "/prisma/prisma" "one-to-many relations"
5. 使用 Prisma 架构示例作答

架构：上下文分离

为什么拆分为两个技能？

此技能采用两阶段架构：

1. 主技能（context7-auto-research）——需要对话上下文：

   • 检测用户消息中的触发关键词
   • 提取用户查询意图
   • 选择最匹配的库（版本、名称、信任评分）
   • 将文档整合到回复中

2. 子技能（context7-fetcher）——独立上下文（context: fork）：

   • 执行对 Context7 的 API 调用
   • 纯 HTTP 请求，无需对话历史
   • 减少 Token 消耗

优势

方面	主技能	子技能
上下文	完整对话	Fork（独立）
目的	意图分析	API 执行
Token 用量	较高	较低
执行	顺序执行	可并行执行

调用流程

User Query → Main Skill (detect + analyze)
                ↓
           Task Tool → Sub-Skill (API search)
                ↓
           Main Skill (select best match)
                ↓
           Task Tool → Sub-Skill (API fetch docs)
                ↓
           Main Skill (integrate + respond)

与现有技能集成

此技能可与现有的 documentation-lookup 技能互补：

• 自动研究：主动自动激活
• 文档查找：通过 /context7:docs 手动调用

两者可以共存——使用自动研究实现无缝体验，使用文档查找处理明确的查询。

性能注意事项

• 缓存响应：文档变更不频繁
• 并行请求：如果用户询问多个库，可通过多个 Task 调用并行获取
• 超时处理：为 API 调用设置合理的超时时间（5-10s）
• 回退策略：如果 API 不可用，则使用训练数据并附上免责声明
• 上下文效率：子技能使用 Fork 上下文，以尽量减少 Token 消耗

限制

• API 访问需要互联网连接
• 受 Context7 API 速率限制
• 对于非常新或鲜为人知的库，可能没有相关文档
• 文档质量取决于源代码仓库的结构