Repomix Explorer Skill 使用指南:让 AI 助手打包、检索并洞察代码库

原创2026-09-11 15:15:201,998 阅读
文章标签:开发工具CLIMCP 服务AI 应用

Repomix Explorer Skill 使用指南:让 AI 助手打包、检索并洞察代码库

本文面向 Claude Code、Codex、Cursor、OpenClaw、Hermes Agent 等 AI 编码助手的使用者,讲解如何在当前 Repomix 仓库中安装并运用 Repomix Explorer 这个即用型 Agent Skill。读完本文,你将掌握三种安装方式(Claude Code 插件、Skills CLI、Hermes 原生命令)、自然语言驱动的远程/本地代码库分析流程,以及背后 Repomix CLI 打包、grep 检索与洞察输出的完整工作原理。

什么是 Repomix Explorer Skill

Repomix 仓库内置了一个开箱即用的 Agent Skill —— Repomix Explorer。它的作用很简单:让 AI 编码助手借助 Repomix CLI,把一段代码库(远程或本地)打包成单个 AI 友好文件,再通过读取与模式搜索(grep)分析这份输出,最终给出结构、指标与可执行的建议。

该 Skill 面向 Claude Code 以及所有兼容 Agent Skills 格式的 AI 助手。它的实体定义位于仓库的 skills/repomix-explorer/SKILL.md,其中明确规定了触发与不触发场景:

应该触发的场景:

  • 结构/概览类请求:"analyze this repo"、"what's the structure"、"what's in vercel/next.js"
  • 跨文件的模式发现:"find all auth code"、"where are the API endpoints"、"show me all React components"
  • 指标统计:"how many files/tokens"、"largest files"、"TypeScript vs JavaScript ratio"
  • 远程仓库:任意 github.com URL 或用户想探索的 "owner/repo" 简写

不应该触发的场景:

  • 对当前项目做编辑、重构或写代码
  • 读取或搜索本地项目中已知的具体文件(这种情况应直接用 Read 或 grep)
  • 本地项目中用一次 grep 就能回答的单个符号查询
  • Git 操作、运行测试、构建或安装

一句话概括定位:它面向"对陌生或大型仓库的高层理解",而不是"对已知文件的定点修改"。

快速安装

1. Claude Code:安装官方插件

如果使用 Claude Code,直接安装官方 Repomix Explorer 插件:

/plugin marketplace add yamadashy/repomix
/plugin install repomix-explorer@repomix

安装后,Claude Code 会提供带命名空间的命令,例如 /repomix-explorer:explore-local 与 /repomix-explorer:explore-remote。完整的配置说明见 Claude Code 插件指南。

2. Codex、Cursor、OpenClaw 等:Skills CLI 安装独立 Skill

对于 Codex、Cursor、OpenClaw 及其他兼容 Agent Skills 格式的助手,使用 Skills CLI 安装独立 Skill:

npx skills add yamadashy/repomix --skill repomix-explorer

如果要指定目标助手,传入 --agent 参数:

npx skills add yamadashy/repomix --skill repomix-explorer --agent codex
npx skills add yamadashy/repomix --skill repomix-explorer --agent openclaw

3. Hermes Agent:单文件安装

对于 Hermes Agent,使用其原生 skills 命令安装单文件 Skill:

hermes skills install https://raw.githubusercontent.com/yamadashy/repomix/main/skills/repomix-explorer/SKILL.md

如果你主要用 Hermes Agent 做仓库分析,MCP Server 指南 也值得关注——它会直接把 Repomix 以 MCP Server 形式运行,是另一种集成方式。

安装后如何使用:自然语言分析代码库

安装完成后,你可以直接用自然语言向 AI 助手下达分析指令。

分析远程仓库:

"What's the structure of this repo?
https://github.com/facebook/react"

探索本地代码库:

"What's in this project?
~/projects/my-app"

这不只对"看懂别人的代码"有用——当你希望参照自己其他仓库的实现来开发功能时同样高效:让 AI 分析你的另一个项目,再对照它的模式落地到当前代码。

工作原理:三步走的核心工作流

Repomix Explorer Skill 引导 AI 助手完成一条完整链路:

  1. 运行 repomix 命令 —— 把仓库打包成 AI 友好格式(XML 等)
  2. 分析输出文件 —— 用 grep 模式搜索定位相关代码
  3. 提供洞察 —— 汇报结构、指标与可操作建议

细化到 Skill 内部(见 skills/repomix-explorer/SKILL.md),实际执行的是四步工作流:

步骤 动作 关键点
Step 1 打包仓库 远程仓库 --remote;本地目录直接给路径;远程输出一律写 /tmp,避免污染当前项目目录
Step 2 检查命令输出 记录 Files processed、Total characters、Total tokens、输出文件位置
Step 3 分析输出文件 先看文件树与指标摘要,再用 grep 做模式搜索
Step 4 提供洞察 汇报指标、描述结构、高亮发现、给出下一步建议

Repomix 命令与核心参数详解

命令基本形态

# 远程仓库(输出到 /tmp 避免污染当前项目)
npx repomix@latest --remote <repo> --output /tmp/<repo-name>-analysis.xml

# 本地目录
npx repomix@latest [directory] [options]

常用参数一览

参数 作用 默认值 / 说明
--style <format> 输出格式:xml / markdown / json / plain 默认 xml,推荐优先使用
--compress 启用 Tree-sitter 压缩,约减少 70% token 大仓库(>10 万行)务必使用
--include <patterns> 只包含匹配的 glob 模式,如 "src/**/*.ts,**/*.md" 可多模式逗号分隔
--ignore <patterns> 额外排除模式 如 "*.test.js,docs/**"
--output <path> 自定义输出路径 默认 repomix-output.xml
--remote-branch <name> 指定远程仓库的分支、标签或 commit 默认远程仓库默认分支

实际命令示例

# 基本远程打包(输出到 /tmp)
npx repomix@latest --remote yamadashy/repomix --output /tmp/repomix-analysis.xml

# 基本本地打包
npx repomix@latest

# 打包指定目录
npx repomix@latest ./src

# 大仓库开启压缩(输出到 /tmp)
npx repomix@latest --remote facebook/react --compress --output /tmp/react-analysis.xml

# 只包含特定文件类型
npx repomix@latest --include "**/*.{ts,tsx,js,jsx}"

这些参数与仓库 CLI 的完整定义一一对应,可对照 src/cli/cliRun.ts 中的 Repomix Output Options、File Selection Options 与 Remote Repository Options 分组核实。例如 --style 支持 xml, markdown, json, plain 四种取值,--remote 支持 GitHub URL 或 user/repo 简写,--remote-branch 可指定分支、标签或 commit。

命令运行后的输出信息

repomix 打包完成后会在控制台显示四类信息,AI 助手应记录它们并用于后续洞察:

  • Files processed —— 纳入打包的文件数
  • Total characters —— 内容总字符数
  • Total tokens —— 预估 AI token 数
  • Output file location —— 输出文件保存位置(默认 ./repomix-output.xml)

高效分析技巧:grep 优先,按需读取

Skill 内置了一条明确的最佳实践:大文件优先用 grep 模式搜索,而不是整文件读取。

结构概览先行

  1. 搜索输出文件中的文件树(file tree)区块,通常靠近文件开头
  2. 检查 metrics 摘要获取整体统计

常用 grep 模式

# 函数与类
grep -iE "export.*function|export.*class|function |class " file.xml

# 导入与依赖
grep -iE "import.*from|require\(" file.xml

# 配置
grep -iE "config|Config|configuration" file.xml

# 认证/授权
grep -iE "auth|login|password|token|jwt" file.xml

# API 端点
grep -iE "router|route|endpoint|api" file.xml

# 数据库/模型
grep -iE "model|schema|database|query" file.xml

# 错误处理
grep -iE "error|exception|try.*catch" file.xml

带上下文的搜索与分段读取

# 带上下文搜索
grep -iE -A 5 -B 5 "authentication|auth" repomix-output.xml

# 读取具体区块
# 大输出文件用 offset/limit 分段读;小文件可整体读

输出格式选型建议

格式 特点 适用场景
XML(默认) 结构化最强、文件边界清晰 结构化分析,无特殊需求时首选
Plain 更易 grep,但结构弱 纯文本检索
Markdown 人类可读性好 文档化产出
JSON 机器可读 程序化分析

文件管理

  • 默认输出 ./repomix-output.xml
  • 用 --output 指定自定义路径,分析多个仓库时避免互相覆盖
  • 大文件分析结束后建议清理:rm repomix-output.xml(空间充足也可保留备用)

Skill 内置内容拆解

Repomix Explorer Skill 的 SKILL.md 本身就是一个高质量 Agent Skill 模板,包含四个核心模块:

  • 用户意图识别(User Intent Examples) —— 覆盖远程仓库、本地仓库、模式发现、指标统计四大类提问方式,帮助 AI 从自然语言中准确判断"用户想要什么分析"
  • Repomix 命令指南(Responsibilities / Workflow) —— 知道何时用 --remote、何时直接打包目录、何时加 --compress、何时用 --include 收窄范围(如仓库超过 10 万行时优先压缩)
  • 分析工作流(Workflow) —— 打包 → 检查输出 → grep 定位 → 阅读 → 汇报的结构化方法
  • 最佳实践(Best Practices) —— 效率优先原则:先 grep 再整读、自定义输出路径防覆盖、按需清理大文件、信任 Repomix 内置安全检查(自动排除敏感文件)

此外 SKILL.md 还附带了错误处理与自检清单(Self-Verification Checklist),包括:命令是否成功运行?是否记录了输出指标?是否在整读大区块前先用了 grep?洞察是否基于输出中的真实数据?是否给出了文件路径与行号引用?是否提示了下一步探索方向?是否提及输出文件位置与清理建议?——这些约束保证了 AI 的分析结果可追溯、可验证。

延伸:用 --skill-generate 从任意代码库生成自己的 Skill

理解了 Repomix Explorer 之后,值得了解它的"反向能力":Repomix 本身可以从任意代码库自动生成 Agent Skill,这正是 Agent Skills 生成指南 的主题。

CLI 侧提供了三个相关参数(见 src/cli/cliRun.ts):

  • --skill-generate [name] —— 以 Claude Agent Skills 格式输出到 .claude/skills/<name>/ 目录,省略 name 时自动生成
  • --skill-project-name <name> —— 覆盖生成的 Skill 描述中的项目名
  • --skill-output <path> —— 直接指定 Skill 输出目录,跳过交互式位置询问

从源码看,生成流程由 src/core/skill/packSkill.ts 驱动,分三步:先生成 Skill 引用文件(summary、structure、files、tech-stacks),再基于 files 区块计算精确 token 数,最后渲染 SKILL.md。输出目录结构由 src/core/skill/writeSkillOutput.ts 保证:

<skillDir>/
├── SKILL.md
└── references/
    ├── summary.md              # 用途、格式说明与统计
    ├── project-structure.md    # 带行数的目录树
    ├── files.md                # 全部文件内容
    └── tech-stacks.md          # 检测到技术栈时生成

SKILL.md 的渲染模板在 src/core/skill/skillStyle.ts,遵循 Agent Skills 的渐进式披露(progressive disclosure)最佳实践:入口只放元数据与用法指引,正文内容全部放在 references/ 下,供 AI 按需检索。Skill 名称的规范化(转 kebab-case、最长 64 字符、拒绝路径穿越)由 src/core/skill/skillUtils.ts 的 validateSkillName 完成;远程场景下默认名形如 repomix-reference-<repo-name>。

这条能力同样暴露在 MCP Server 中:generate_skill 工具(见 src/mcp/tools/generateSkillTool.ts)接收目录、skillName、compress、includePatterns、ignorePatterns 等参数,直接在 <project>/.claude/skills/<name>/ 下生成项目级 Skill,与团队通过版本控制共享。

相关资源

若想查看 CLI 的全部可用选项,可随时运行 npx repomix@latest --help。

登录后查看全文
repomix