跳到主要内容

分发即产品:Skills / Plugins / Rules 与两种交付模式

30 秒导读: 前面几章讲的是 Context7 的「引擎」——SDK、MCP 服务器、CLI(见 01/02/03/04)。 这一章讲的是「包装与投放」:仓库里 packages/ 之外那一大堆 .md/.json 文件,它们本身不跑逻辑,而是被投递到各家编码代理里的说明书。它们的唯一使命,是让 Claude Code / Cursor / Codex / Copilot / Gemini 这些 agent 在写代码时默认想到「先去查最新文档」——查的动作,要么落成一条 CLI 命令,要么落成一次 MCP 工具调用。

1. 这是什么(零基础也能懂)​

一句话定义: 这一章的主角是 Context7 的分发物(distribution artifacts)——一批面向 AI 的说明文件,复制到不同编码代理约定的目录里,就能把「用 Context7 查文档」变成那个 agent 的默认习惯。

先破一个误解: 很多人以为 Context7 的产品是 mcp.context7.com 那个后端。其实后端是私有的、不在这个仓库里(README 明说仓库只含 MCP 服务器源码,解析/爬取引擎不公开)。这个开源仓库里真正被当成产品反复打磨的,恰恰是本章这些说明文件。

为什么它们重要 —— 「货架战争」: 模型训练数据会过期,写代码时经常「记错 API」。Context7 要解决这个,但前提是 agent 得先想起来用它。所以真正的产品问题不是「怎么查文档」,而是:

怎么让每一家 agent、在每一次该查文档的时候,都自动触发去查?

答案就是:把「触发说明」做成各家 agent 认得的格式(Claude 认 Skill、Cursor 认 .mdc Rule、大家都认 MCP……),一份份塞进它们的配置目录。谁占住了这块「货架」,谁就赢。

用起来什么样: 用户其实只敲一条命令,剩下的分发全自动完成:

npx ctx7 setup      # 交互式:先问你选哪种模式,再问装到哪个 agent

它会问你两个问题——用哪种交付模式(下一节的两条路线),以及装给哪个 agent——然后把对应的分发物落到该 agent 的正确目录(这一步的执行器是 packages/cli/src/setup/agents.ts,见 03 章)。

一句话直觉: 把这些文件想成塞进各家便利店货架的产品说明卡。产品(查最新文档的能力)是同一个,但每家店(agent)货架规格不同,于是同一句话被翻译成 Skill、Rule、Command、Plugin、MCP 配置等十几种包装,一份份摆进去。

本节不出现底层代码。目标:明白「Context7 的产品 = 让 agent 默认想到去查文档」这件事,是靠一堆分发文件、而不是靠那个后端实现的。

2. 顶层全景(分发物怎么摆放)​

先看这张图怎么读: 从上到下是「一句触发意图」如何被复制成越来越多的包装形态,最终落到各家 agent。左半边是 CLI + Skills 路线,右半边是 MCP 路线(§3 详解)。

                    「该查文档时就去查最新文档」   ← 同一个意图
                                 │
             ┌───────────────────┴───────────────────┐
             │                                         │
      CLI + Skills 路线                            MCP 路线
      (装一个技能/规则,                        (注册一个 MCP 服务器,
       让 agent 去跑 ctx7 命令)                 agent 原生调两个工具)
             │                                         │
   ┌─────────┼──────────┐                   ┌──────────┼───────────┐
   │         │          │                   │          │           │
 skills/   rules/    (无需            skills/       rules/      plugins/
 find-docs context7-  MCP)           context7-mcp  context7-mcp  各家封装
 SKILL.md  cli.md                    SKILL.md      .mdc          (claude/codex/
 context7-                                                        copilot/cursor)
 cli/                                                             + .mcp.json
             └───────────────┬─────────────────────────┘
                             │
                    交付载体(把上面这些打包/投放)
       ┌─────────────┬──────────────┬───────────────┬─────────────┐
   .claude-plugin/  .agents/      gemini-        plugins/         i18n/ + public/
   marketplace.json plugins/      extension.json context7-power   (多语言 README
   (Claude 市场)    marketplace   (Gemini CLI    (Amp「Power」)    + 图标素材)
                    (Codex 市场)   扩展清单)

各类分发物一句话职责:

分发物路线干什么位置
skills/find-docsCLI+Skills教 agent 用 npx ctx7 命令查文档skills/find-docs/SKILL.md
skills/context7-cliCLI+Skills完整 ctx7 CLI 说明书(文档+技能管理+setup)skills/context7-cli/SKILL.md + references/
skills/context7-mcpMCP教 agent 调 MCP 的两个工具skills/context7-mcp/SKILL.md
rules/context7-cli.mdCLI+Skills贴进 CLAUDE.md / 规则文件的短规则(CLI 版)rules/context7-cli.md
rules/context7-mcp.mdMCP同上,MCP 版rules/context7-mcp.md
plugins/<agent>/context7多为 MCP各家 agent 的整包插件(含 agent/command/skill/MCP 配置)`plugins/claude
plugins/context7-powerMCPAmp 的「Power」封装plugins/context7-power/POWER.md
.claude-plugin/ .agents/ .github/plugin/—各家「插件市场」清单,指向 plugins/仓库根
gemini-extension.jsonMCPGemini CLI 扩展清单(直接内联 MCP 配置)仓库根
i18n/ public/—15 种语言 README + 品牌图标(投放的「门面」)仓库根

主线走一遍(高层): 用户跑 ctx7 setup → 选模式 + 选 agent → agents.ts 把上表对应的文件写到该 agent 的目录 → 之后该 agent 每次遇到库相关问题,就被这些说明触发去查文档。分发物是「静态说明」,setup 命令是「投放机」。

3. 核心:两条交付路线的分工​

整章最该记住的一件事:同一个「查文档」能力,Context7 提供了两种落地方式。它们面向不同能力的 agent,分发物也因此分成两套。

这两条路线在 ctx7 setup 里是显式二选一。README:41-42 把它讲得最白:

  • CLI + Skills — installs a skill that guides your agent to fetch docs using ctx7 CLI commands (no MCP required)
  • MCP — registers a Context7 MCP server so your agent can call documentation tools natively

两条路线对照:

维度CLI + Skills 模式MCP 模式
前提agent 能跑 shell 命令agent 支持 MCP 协议
装什么一个 find-docs 技能 / 一条规则注册 MCP 服务器 + context7-mcp 技能 + 规则
agent 怎么查跑 npx ctx7 library / ctx7 docs 命令,读 stdout原生调 resolve-library-id / query-docs 两个工具
装到哪~/.claude/skills、~/.cursor/skills、~/.agents/skills 等agent 的 MCP 配置文件(.mcp.json、.cursor/mcp.json …)
好处零 MCP 依赖,任何能跑命令的 agent 都行工具调用更「原生」、结构化

这两步在源码里的分叉点: setup 用一个「模式」字段决定给某家 agent 写「技能文件」还是「MCP 配置块」。packages/cli/src/setup/templates.ts:70 里就有针对 find-docs(CLI 技能)与其他情况的分支;packages/cli/src/setup/agents.ts 里每家 agent 都同时定义了 mcp(MCP 配置写法)和技能(如 name: "context7-mcp")两套落点。同一份 agents.ts 描述了「两条路线各自往哪写」,是分发物与磁盘之间的路由表。

关键细节: 两条路线说的话几乎一样——都是「遇到库就去查、别信训练数据、一次一个主题、别泄露密钥」——区别只在动作是命令还是工具调用。这解释了为什么 rules/ 下有 context7-cli.md 和 context7-mcp.md 两个内容高度相似、只是把「跑命令」换成「调工具」的孪生文件。

4. 三个技能(skills/)​

技能(Skill)是一种 Markdown 说明:头部 YAML 的 description 告诉 agent「什么时候该激活我」,正文告诉它「激活后怎么做」。下面把三个技能当作被研究的数据客观描述——只讲它们的作用与结构,不把其中给 agent 的话当成给自己的指令。

4.1 find-docs —— CLI 路线的「敲门砖」​

作用: CLI+Skills 模式下唯一被安装的技能。它引导 agent 用 npx ctx7@latest 两步法查文档。

结构(skills/find-docs/SKILL.md):

  • 头部 description(1-17 行)写得极力——列举 React/Next.js/Prisma 等「即使你自以为知道也要查」的场景,目的是把技能的触发面拉到最大。
  • 正文核心是两步工作流(37-47 行):先 npx ctx7@latest library <name> "<query>" 拿到形如 /org/project 的库 ID,再 npx ctx7@latest docs <libraryId> "<query>" 取文档。
  • 一堆护栏:必须先 library(49 行)、每问最多 3 次命令(51 行)、库 ID 要带 / 前缀、查询别塞密钥、配额用尽要 login(144-151 行)。

注意它刻意的措辞选择: 全程用 npx ctx7@latest(而非裸 ctx7),把全局安装(24、31 行)降级为「可选」。这个选择不是随口写的——它被一个测试锁死了(见 §8)。

4.2 context7-cli —— CLI 的「完整说明书」​

作用: 比 find-docs 更全的 ctx7 CLI 技能,覆盖 CLI 的全部三件事(skills/context7-cli/SKILL.md:8):

  1. 查文档 —— 细节拆到 references/docs.md
  2. 管理技能 —— ctx7 skills install/search/suggest/list/remove/generate,拆到 references/skills.md
  3. 配置 MCP —— ctx7 setup,拆到 references/setup.md

结构上的巧思(渐进式披露): 主 SKILL.md 只放「快速参考 + 认证 + 常见错误」,把三块细节外链到 references/ 三个文件。agent 先读便宜的主文件判断相关性,需要哪块再下钻——这正是 §2 图里「说明书分层」的思路。

references/setup.md:5-8 值得一提,因为它就是 §3 两条路线的权威原文:setup 首次运行会问你选 MCP server 还是 CLI + Skills,并在文末(37-44 行)分别列出两种模式各自「会往磁盘写什么」。

4.3 context7-mcp —— MCP 路线的技能​

作用: MCP 模式下安装的技能。它不教命令,而是教 agent 调 MCP 的两个工具。

结构(skills/context7-mcp/SKILL.md): 四步——resolve-library-id(拿 ID)→ 选最佳匹配 → query-docs(取文档)→ 融入回答。护栏和 CLI 版同构:一次一个主题、多概念拆多次调用、认版本。

一个重要事实: 这份 context7-mcp/SKILL.md 会被原样复制进各家插件——plugins/claude、plugins/cursor、plugins/codex、plugins/copilot 下的 skills/context7-mcp/SKILL.md 与它逐字节相同(实测四份 diff 无差异)。也就是说,它是 MCP 路线的单一事实源,插件只是它的搬运容器。

5. 规则(rules/)—— 贴进 CLAUDE.md / Cursor Rules 的短文本​

作用: 规则(Rule)比技能更轻——它不是独立文件夹,而是**一段可以直接粘进 agent「常驻上下文」**的文字(比如 Claude 的 CLAUDE.md、Cursor 的 Rules)。README:85-99 专门有「Add a Rule」小节教手动添加。

仓库提供两份孪生规则,对应两条路线:

文件面向第一句话(意图)
rules/context7-cli.md能跑命令的 agent「用 ctx7 CLI 查当前文档」
rules/context7-mcp.md支持 MCP 的 agent「用 Context7 MCP 查当前文档」

它们几乎是同一段话的两个版本。 两者开头都是同一句「遇到 library/framework/SDK…就去查,即使你以为知道」,都有同一句「不要用于重构/从零写脚本/调业务逻辑/代码审查/通用编程概念」。唯一实质差异在「怎么查」那步:CLI 版写命令(rules/context7-cli.md:7-9),MCP 版写工具名(rules/context7-mcp.md:7-9 的 resolve-library-id / query-docs)。

Cursor 的规则是特殊格式: plugins/cursor/context7/rules/use-context7.mdc 是 Cursor 专用的 .mdc 格式,头部带 alwaysApply: true(2-4 行)——意思是「每次对话都常驻生效」,不用等触发。它比 rules/ 里那两份更「省」:只说「拿不准库 API 时去查」,细节让 agent 去看 context7-docs-lookup 技能。

6. 插件(plugins/)—— 各家 agent 的整包封装​

作用: 插件(Plugin)是把「MCP 配置 + 技能 + 命令 + 子 agent」打成一整包,让用户在某家 agent 的插件市场里一键装齐。仓库为四家主流 agent 各准备了一包。

四家插件的「零件清单」(注意各家目录约定不同):

Agent插件目录含哪些零件清单文件
Claude Codeplugins/claude/context7/agent + command + skill + MCP.claude-plugin/plugin.json
Codexplugins/codex/context7/skill + MCP(无 agent/command).codex-plugin/plugin.json
Copilotplugins/copilot/context7/agent + command + skill + MCPplugin.json(根级)
Cursorplugins/cursor/context7/agent + rule(.mdc)+ skill + MCP.cursor/plugin.json

三种可复用零件,值得单独看:

  • 子 agent docs-researcher(plugins/claude/context7/agents/docs-researcher.md)—— 一个「轻量文档研究员」子 agent,model: sonnet(4 行),专门在不污染主对话上下文的前提下去查文档、回一个精炼答案。Copilot 版是同一份内容、换成 .agent.md 后缀且去掉 model 字段(plugins/copilot/context7/agents/docs-researcher.agent.md)。

  • 斜杠命令 /context7:docs(plugins/claude/context7/commands/docs.md)—— 头部 argument-hint: <library> [query](3 行),让用户直接敲 /context7:docs react hooks 触发查询。逻辑:库名以 / 开头就当 ID 直接用,否则先 resolve-library-id(29-33 行)。

  • MCP 配置块 —— 各家写法各不相同,这正是「同一产品、多种货架规格」的最好例证:

插件MCP 传输方式关键写法
plugins/claude/.mcp.jsonHTTP"type":"http" + url + CONTEXT7_API_KEY header
plugins/cursor/context7/mcp.jsonHTTP裸 url(无 type)
plugins/context7-power/mcp.jsonHTTP最简:只有 url
gemini-extension.json(根级)stdiocommand:"npx" + @upstash/context7-mcp + --api-key

context7-power —— Amp 的「Power」封装: plugins/context7-power/POWER.md 是给 Amp(它把插件叫「Power」)的一份说明。头部是 YAML frontmatter(name/displayName/keywords…),正文结构和 context7-mcp 技能几乎一样(四步 + 最佳实践),只是术语从「Skill」换成「Power」。同一套话术的又一次换皮。

7. 交付载体:市场清单 / 扩展 / 门面​

上面那些零件要能「被发现、被安装」,还需要一层投放清单。它们本身不含 AI 指令,是纯粹的元数据。

三个「插件市场」清单,各指向对应的 plugins/ 子目录:

清单面向的市场指向
.claude-plugin/marketplace.jsonClaude Code 市场./plugins/claude/context7(version 1.0.2)
.agents/plugins/marketplace.jsonCodex 市场./plugins/codex/context7(带 policy/category)
.github/plugin/marketplace.jsonCopilot CLI 市场./plugins/copilot/context7

Gemini 走「扩展」而非「市场」: gemini-extension.json(仓库根)是 Gemini CLI 的扩展清单,它不指向 plugins/,而是直接内联 MCP 配置(mcpServers.context7 用 stdio 跑 @upstash/context7-mcp)和一个 CONTEXT7_API_KEY 设置项。它是自包含的,setup 里 Gemini 也被当成一等目标(agents.ts:14-21 的 SETUP_AGENT_NAMES 含 gemini: "Gemini CLI")。

门面:多语言 README 与图标:

  • i18n/ 下有 15 种语言的 README(README.zh-CN.md、README.ja.md、README.ar.md…)。这是把「分发即产品」推向全球开发者的门面——同一个「让 agent 查最新文档」的卖点,翻成 15 种语言摆上货架。
  • public/ 下是品牌素材(context7-icon-green.svg、cover.png、icon.png 等),被各家 plugin.json 的 logo/brandColor 字段引用(如 plugins/cursor/context7/.cursor/plugin.json:11 引 context7-icon-green.svg、primaryColor:"#059669")。统一的绿色视觉,是这块货架的「招牌」。

8. 对齐约束:技能内容必须跟 CLI 行为一致​

分发物是静态文本,而 CLI 是会演进的代码。风险是:CLI 改了行为,技能里的说明却没跟着改,agent 就会照着过时说明去敲一条已经失效的命令。仓库用单元测试把两者钉在一起。

测试一:find-docs 技能必须跟 CLI 规则同款(packages/cli/src/__tests__/find-docs-skill-alignment.test.ts)——它直接读磁盘上的 skills/find-docs/SKILL.md 和 rules/context7-cli.md,断言三件事:

断言(测试用例)钉住的约束位置
技能里出现 npx ctx7@latest library/docs,且没有裸 ctx7 library 开头规范调用风格必须是 npx ctx7@latest11-17 行
技能和规则都含 "Next.js" not "nextjs",技能含 library "Next.js"官方库名写法(带标点)两处一致19-26 行
npx ctx7@latest 出现的位置早于 npm install -g全局安装不能被写成首选工作流28-34 行

这解释了 §4.1 的措辞选择: find-docs 全程用 npx ctx7@latest、把全局安装放到后面,不是文笔偏好,而是被这三条断言强制的。改文档时若违反,CI 直接红。

测试二:skills list 的输出契约(packages/cli/src/__tests__/skill-list.test.ts)——它在临时目录里造出 .agents/skills/find-docs 和 .cursor/skills/cursor-helper 两个技能,跑 ctx7 skills list --json,断言输出把它们分别标成 source: "universal" 和 source: "cursor"(47-68 行)。这钉住的是**「技能装在哪个目录 → 归属哪个 agent」的映射**,正是 §2 里各家目录约定的机器化保证。

一句话: 这两个测试让「分发物」和「CLI 实际行为」不能各说各话——文档漂移会被当成 bug 拦下。这是「分发即产品」能长期成立的工程底座。

9. 边界与局限(诚实)​

  • 后端不在本仓库。 这些分发物最终都指向 mcp.context7.com 或 ctx7 CLI,而真正干活的解析/爬取引擎是私有的(README:136 明说)。本章能讲清「怎么投放、投放了什么」,但讲不了「文档质量怎么来的」——那在仓库之外。
  • 分发物是「说明」不是「保证」。 技能/规则只能提高 agent 想起查文档的概率,不能强制。Cursor 的 alwaysApply: true 是最强的一档,但多数技能仍靠 description 里的关键词去「诱发」激活。
  • 孪生文件的维护负担。 CLI 版/MCP 版规则、四份复制的 context7-mcp 技能、五种写法的 MCP 配置——同一句话散落在十几处。§8 的测试只覆盖了 find-docs 与 CLI 规则的对齐,其余副本的一致性没有测试兜底(inferred:仓库里只找到这两个对齐测试)。
  • 各家目录/清单格式必须手工跟上。 每当某家 agent 改了插件目录约定或 MCP 配置 schema,agents.ts 和对应清单都得手动改——这是「占满每一块货架」策略天然的边际成本。

10. 代码地图(导航索引)​

主题文件路径关键符号 / 锚点
两种交付模式的权威说明skills/context7-cli/references/setup.md「MCP server」/「CLI + Skills」(5-8 行、37-44 行)
CLI 敲门砖技能skills/find-docs/SKILL.md两步法 npx ctx7@latest library/docs
CLI 完整说明书skills/context7-cli/SKILL.md + references/{docs,skills,setup}.md「三件事」(8 行)
MCP 技能(单一事实源)skills/context7-mcp/SKILL.mdresolve-library-id / query-docs 四步
孪生规则文本rules/context7-cli.md、rules/context7-mcp.md首句「遇到 library 就去查」+「Do not use for」
Cursor 常驻规则plugins/cursor/context7/rules/use-context7.mdcalwaysApply: true
子 agentplugins/claude/context7/agents/docs-researcher.mdmodel: sonnet
斜杠命令plugins/claude/context7/commands/docs.mdargument-hint: <library> [query]
Amp Power 封装plugins/context7-power/POWER.mdfrontmatter name: "context7"
各家 MCP 配置写法plugins/*/context7/*.mcp.json、gemini-extension.jsonmcpServers.context7(http vs stdio)
三个市场清单.claude-plugin/marketplace.json、.agents/plugins/marketplace.json、.github/plugin/marketplace.jsonplugins[].source
投放执行器(见 03 章)packages/cli/src/setup/agents.tsSETUP_AGENT_NAMES、RuleType、各 agent 的 mcp 块
模式分支packages/cli/src/setup/templates.ts:70skillName !== "find-docs" 分支
对齐约束(技能↔CLI)packages/cli/src/__tests__/find-docs-skill-alignment.test.ts三个 test(...)
目录归属契约packages/cli/src/__tests__/skill-list.test.ts`source: "universal"

与同组其它章的关系: 本章是货架最外层——回指 03 章 的 ctx7 setup/agents.ts(把本章分发物落地的执行器),依赖 02 章 的 resolve-library-id/query-docs(MCP 路线调用的两个工具),复用 04 章 的提示词设计(本章各技能/规则里那套「一次一主题、别信训练数据」话术的同源)。想先理解 Context7 全貌,回 index。