Context7 CLI skills 子命令详解：AI 编码技能的安装、搜索、推荐与 AI 生成

Context7 CLI（ctx7）除了拉取最新的库文档之外，还内置了一组 skills 子命令，用于从 Context7 注册表或任意 GitHub 仓库中发现、安装、推荐和生成 AI 编码技能（Skills）。本文基于仓库内的官方参考文档 skills.md 和 CLI 源码 skill.ts 展开，覆盖 install、search、suggest、generate、list、remove、info 全部子命令的用法与标志位，并结合源码剖析技能解析、提示注入防护、符号链接安装机制与配额控制等底层实现。读完本文，你可以熟练使用 ctx7 skills 管理面向 Claude Code、Cursor、Amp、Codex 等编码代理的技能库，并理解其内部工作流程。

需要先说明一个仓库当前代码中的事实：skill.ts 顶部定义了弃用警告 SKILL_HUB_DEPRECATION_WARNING = "Warning: Skill commands are deprecated and will stop working in the next major release."，且该命令树注册为 hidden。也就是说，ctx7 skills ... 目前处于兼容窗口期，仍可使用，但将在下一个大版本停止工作。文中所有用法以当前仓库代码为准。

Skill 是什么

Skill 是一组 Markdown 文件，用来教会 AI 编码代理针对特定库或任务的最佳实践、模式和流程。每个技能通常是一个目录，核心是 SKILL.md——本仓库自身就内置了多个技能作为范例，如 context7-cli、context7-mcp 等。技能安装到编码代理约定的目录后，代理在会话中会自动加载它们，从而获得关于特定技术栈的"领域专家"能力。

skills 命令家族一览（均来自 skill.ts 的命令注册代码）：

ctx7 skills install /owner/repo        # 从仓库安装（别名: si, i, add）
ctx7 skills search <keywords>          # 搜索注册表（别名: ss, s）
ctx7 skills suggest                    # 基于项目依赖推荐（别名: ssg）
ctx7 skills generate                   # AI 生成自定义技能（别名: gen, g，需登录）
ctx7 skills list                        # 查看已安装技能（别名: ls，支持 --json）
ctx7 skills remove <name>              # 卸载技能（别名: rm, delete）
ctx7 skills info /owner/repo           # 预览仓库中的技能

Install：从 GitHub 仓库安装技能

仓库格式固定为 /owner/repo（源码 parse-input.ts 也接受完整 GitHub URL）。三种基本用法：

ctx7 skills install /anthropics/skills           # 交互式——从列表中选择
ctx7 skills install /anthropics/skills pdf        # 按名称安装指定技能
ctx7 skills install /anthropics/skills --all     # 不提示，全部安装

安装流程的源码行为（skill.ts installCommand）比文档描述更细致：

1. 两级解析：先调用 getSkill/listProjectSkills 从 Context7 注册表拉取；如果注册表里没有结果，自动降级为从 GitHub 直接抓取（getSkillFromGitHub/listSkillsFromGitHub），因此未索引的公开仓库同样可以安装。
2. 提示注入防护：注册表在索引时会做安全检查。若某个技能命中 prompt_injection_detected，CLI 会直接拒绝安装并提示"contains potentially malicious content"；批量拉取时，被拦截的技能以 blockedSkillsCount 汇总提示"X skill(s) blocked due to prompt injection and not shown"。
3. 交互式选择：不指定技能名且未加 --all 时，CLI 渲染一个带悬停预览的复选框列表，每个条目展示 Popularity（安装量区间）、Trust（信任分，trustScore 保留一位小数）、描述以及可点击的终端超链接（OSC 8）。列表按 installCount 降序排列——从源码排序逻辑 (b.installCount ?? 0) - (a.installCount ?? 0) 可以看出，安装量最高的技能排最前。
4. 选择安装目标：确认技能后，promptForInstallTargets 会询问写入哪些代理目录、项目级还是全局（除非已通过 IDE 标志显式指定）。

指向特定 IDE 与全局安装

ctx7 skills install /anthropics/skills pdf --claude     # 仅 Claude Code
ctx7 skills install /anthropics/skills pdf --cursor     # 仅 Cursor
ctx7 skills install /anthropics/skills pdf --universal  # 通用目录 .agents/skills/
ctx7 skills install /anthropics/skills --all --global   # 全部技能，全局安装

安装后的落盘方式值得注意（installer.ts）：

• 第一个目标目录写入真实文件（installSkillFiles 逐个写入技能包含的每个文件，并做了目录穿越防护——任何解析后跳出技能目录的 file.path 会直接抛错）；
• 其余目标目录则通过 symlinkSkill 创建符号链接指向主目录，避免同一技能多份拷贝，且卸载时只删主目录即可。

此外，--global 会把基础目录从 process.cwd() 切换为主目录（全局模式），权限不足（EACCES/EPERM）时 CLI 会捕获错误并提示用 sudo chown -R $(whoami) 修复对应父目录。install 还支持文档未展开的两个标志：--all-agents（安装到所有受支持的代理位置）和 -y, --yes（跳过确认提示）。

Search：按关键词搜索整个注册表

ctx7 skills search pdf
ctx7 skills search typescript testing
ctx7 skills search react nextjs

搜索跨整个注册表索引的仓库，展示带安装量与信任分的交互列表，选中后直接进入安装流程（选择目标目录 → 下载 → 落盘，与 install 共用同一套逻辑）。结果条目中的 Installs 列使用 formatInstallRange 渲染为区间值，Trust 列低于 0 或无值时显示为 -。搜索结果为空时提示 No skills found matching "<query>"，网络失败时给出连接错误信息。

Suggest：基于项目依赖自动推荐

ctx7 skills suggest           # 扫描当前项目，安装到项目
ctx7 skills suggest --global  # 安装建议到全局
ctx7 skills suggest --claude  # 仅面向 Claude Code

官方文档说明会读取 package.json、requirements.txt、pyproject.toml、Cargo.toml、go.mod、Gemfile。从源码结构看，客户端本地解析实现在 deps.ts 的 detectProjectDependencies，目前确认覆盖三种生态：

• package.json：合并 dependencies 与 devDependencies，本地过滤掉 @types/ 前缀的包（注释标明完整的 SKIP_SET 在后台）；
• requirements.txt：跳过空行、注释与 - 开头的行，按版本约束符（=<>!~;@\s[ 等）切分出包名；
• pyproject.toml：同时支持 PEP 621 的 [project] dependencies 数组与 Poetry 的 [tool.poetry.dependencies] 段，并排除 python 本身。

其他生态（Rust/Go/Ruby）的文件按文档描述在建议链路中生效——suggest 命令会把本地检测到的依赖列表连同访问令牌一起发送给后台（suggestSkills(deps, accessToken)），由服务端完成匹配。推荐结果列表除了 Popularity/Trust 外还多出一列 Relevant（matchedDep），高亮展示该技能匹配到的具体依赖项。若本地未检测到任何依赖，命令会提示 No dependencies detected 并回退建议 ctx7 skills search <keyword>。值得注意的是，源码中 suggest 会先调用 getValidAccessToken() 获取令牌，即使未登录也会尝试匿名令牌请求。

Generate：AI 生成自定义技能（需要登录）

ctx7 skills generate            # 生成并交互式安装
ctx7 skills generate --claude   # 直接装入 Claude Code
ctx7 skills generate --global   # 装入全局技能目录
ctx7 skills generate -o <dir>   # 指定输出目录（源码支持）

generate 是唯一的强制登录子命令，完整交互流程（源码见 generate.ts generateCommand）：

1. 登录与配额检查：无有效令牌时自动触发 OAuth 登录（performLogin）。随后调用 getSkillQuota 检查周配额，若 quota.remaining < 1 则显示 Weekly skill generation limit reached、已用量（used/limit）、重置日期，免费账户会提示升级 Pro（10 次/周）。官方配额为：免费账户 6 次/周，Pro 账户 10 次/周；后台还可能出现 unlimited 层级。
2. 描述专长：input 提示输入，例如 "OAuth authentication with NextAuth.js"。CLI 会现场给出正反示例——Skill 应编码"最佳实践、约束与决策"，而不是"逐步教程或一次性任务"（如 ✕ "Deploy a Next.js app to Vercel" / ✓ "Best practices and constraints for deploying Next.js apps to Vercel"）。
3. 选择来源：searchLibraries 用描述检索 Context7 库，展示最多前 5 个结果（含来源仓库、Snippets 数量、GitHub 来源的 Star 数），多选确认。若团队空间配置了库过滤策略，会提示结果已按 filter 收窄，并指引到 dashboard 调整。
4. 回答 3 个澄清问题：getSkillQuestions 基于所选库和描述生成带选项的问题（selectOrInput 支持点选推荐项或自由输入），逐题作答并回显。
5. 预览与迭代：generateSkillStructured 流式返回进度事件，终端实时展示正在读取的 Context7 文档片段（最多 3 条、每条截断 400 字符）。生成后预览前 20 行，随后进入循环：Install skill / Edit skill in editor（用 $EDITOR 打开预览文件并同步修改）/ Request changes（输入反馈，连同 previousContent 重新生成）/ Cancel。
6. 落盘：最终把内容写入各目标目录的 <skillName>/SKILL.md，技能名由 libraryName 转小写并清理为 [a-z0-9-] 字符。

List 与 Info：查看已安装与仓库内容

List 展示当前项目或全局范围内已安装的技能：

ctx7 skills list                   # 当前项目（自动检测所有 IDE 目录）
ctx7 skills list --claude          # 仅 Claude Code
ctx7 skills list --global          # 全局技能
ctx7 skills list --global --claude # 全局 Claude Code 技能
ctx7 skills list --json            # JSON 输出（源码支持，便于脚本消费）

无 IDE 标志时，CLI 依次扫描 .agents/skills（Universal）与 VENDOR_SPECIFIC_AGENTS（claude、cursor、antigravity）下的子目录；显式传标志时只扫描对应路径。--json 输出结构为 { skills: [{ name, path, source }] }，source 标识技能来自哪个代理目录，方便脚本化审计。

Info 在不安装的情况下浏览某仓库的全部技能：

ctx7 skills info /anthropics/skills

输出每个技能的名字、描述与 URL，并在末尾附上 Quick commands（Install all / Install one 的现成命令），适合安装前预览仓库里有什么可用。

Remove：卸载技能

ctx7 skills remove pdf             # 从当前项目移除
ctx7 skills remove pdf --claude    # 仅从 Claude Code 移除
ctx7 skills remove pdf --global    # 从全局技能移除

移除前先通过 promptForSingleTarget 确定单个目标（除非显式指定 IDE + 作用域），assertSkillNameInRoot 校验技能名不越过技能根目录（防止 ../../ 类路径注入），然后递归删除该技能目录。目录不存在时报 Skill not found；权限不足时提示 sudo rm -rf "<path>"。

IDE 标志与安装位置

所有 skills 子命令都接受统一的 IDE 目标标志，映射关系由 types.ts 中的 IDE_PATHS/IDE_GLOBAL_PATHS 定义：

标志	目录	服务的代理
--universal	.agents/skills/	Amp、Codex、Gemini CLI、OpenCode、GitHub Copilot 等（读取 .agents/skills/ 标准的代理）
--claude	.claude/skills/	Claude Code
--cursor	.cursor/skills/	Cursor
--antigravity	.agent/skills/	Antigravity

几个源码可确认的细节：

• 不加标志时，CLI 进入交互式多选（promptForInstallTargets），可一次勾选多个代理目录；多目标时首个目录写实体文件、其余符号链接。
• --global 可与任意标志组合，基础目录切换为家目录（~/.claude/skills 等）。
• Universal 定位的默认值：DEFAULT_CONFIG.defaultIde 为 "universal"——从源码结构看，这是 CLI 的默认偏好配置，一次安装即可覆盖所有读取 .agents/skills/ 的代理，这也是源码注释中强调的 "one install covers all of them"。
• 配置载体为 context7.json（仓库根目录即有一份），从 C7Config 类型看它还记录 defaultScope（project/global），用于减少重复提示。

行为验证与延伸阅读

• 技能列表扫描逻辑（只统计子目录与符号链接、--json 输出）有对应测试 skill-list.test.ts，安装与路径处理由 installer.test.ts、remove.test.ts 覆盖，可作为实现行为的权威参照。
• 本仓库的 context7-cli 技能 本身就是一个 Skill 实例，其中 Quick Reference 一节汇总了 docs/skills/setup 三大类命令；配套参考文档还有 docs.md（拉取库文档）与 setup.md（配置 Context7 MCP）。
• 所有 skills 操作都会通过 trackEvent 上报使用事件（如 install、search_query、suggest_install、gen_feedback），便于理解各命令与后台的交互点。

总结：ctx7 skills 子命令族提供了"发现 → 验证 → 安装 → 管理"的完整技能生命周期：用 info/search 预览与检索注册表，用 install 从仓库落盘（注册表优先、GitHub 兜底、注入检测），用 suggest 按项目依赖自动匹配，用 generate 消耗周配额让 AI 基于 Context7 文档定制私有技能，再用 list/remove 做日常维护。结合 IDE 标志与 --global，同一套命令能同时服务于单代理和多代理的工作环境。