Gemini CLI 使用技巧
这篇是我用 Gemini CLI 一段时间之后攒下的技巧和踩坑记录。不是文档搬运——官方文档能查到的我就不重复了——重点是那些实际用起来才发现的点：什么场景它好用、什么场景它会让你抓狂、以及跟 Claude Code 比起来各自的定位。
先说结论：Gemini CLI 我主要拿它干”重调研、重批量”的活，写代码这种需要精细控制的活我还是回到 Claude Code。 下面展开讲为什么。
最好用的场景：批量生成文档
我最喜欢 Gemini CLI 的一个用法，是基于一堆素材批量生成文档。比如用 Slidev 做技术宣讲的 PPT。
我的标准 Prompt 长这样：
帮我基于 /Users/leozhou/git/VISALL/docs/refactor/MCP 下的内容，用 Slidev 这个专门用来用 Markdown 格式生成幻灯片的工具语法写一个对应的 PPT，用 Slidev 的语法美化一下；注意保证单页内容不会过长，避免高度太大显示不完。Slidev 模板地址：https://stackblitz.com/github/slidevjs/new?file=slides.md
为什么这种场景适合 Gemini CLI？因为它的上下文窗口大，一次性吃下一个目录的文档没问题；而且批量生成这种事，不需要多精细的判断，要的是”量大管饱”。这种活 Claude Code 也能干，但没必要用它那更贵的额度。
类似的批量场景我还经常这么干——用一个 write_doc skill，一个一个地给项目生成分析文档：
使用 write_doc 这个 skill，一个一个的给当前项目生成如下几个文档，放入 @docs/analysis 目录下：
VISALL-01-project-overview.md
VISALL-02-quick-start.md
VISALL-03-core-concepts.md
VISALL-04-technical-architecture.md
VISALL-05-component-system.md
VISALL-06-development-guide.md
VISALL-07-build-and-deployment.md“一个一个的”这个措辞很重要——不说清楚，它倾向于一次性全做完，结果每个都浅。让它串行地、深入地做每一个，质量明显更好。这是用 Agent 类工具的一个通用经验：明确告诉它节奏，比让它自己决定节奏要好。
Skill 机制：好用，但坑也多
Gemini CLI 支持 Skill：
- 官方文档：https://geminicli.com/docs/cli/skills/
- Agent Skill 规范：https://agentskills.io/home
一个让我排查了很久的报错
加完 Skill 之后经常报这个错：
Failed to load skills from /Users/leozhou/git/VISALL/.gemini/skills. The directory is not empty but no valid skills were discovered. Please ensure SKILL.md files are present in subdirectories and have valid frontmatter.我在这上面花了不少时间。最后发现两个坑：
SKILL.md的格式必须严格正确。我之前就因为第一行多了个空格，导致整个 skill 识别失败。这种问题报错信息完全不会提示你，只会告诉你”没发现有效的 skill”。- **添加完 skill 之后，必须先退出一次 Gemini CLI，再重新进，才会生效。**它不会热加载。
排查这类问题的 Prompt 我固定下来这么写：
我写了一个 write_doc 的 skill，但是 Gemini CLI 识别不出来，报如下错误：
Failed to load skills from /Users/leozhou/git/VISALL/.gemini/skills. The directory is not empty but
no valid skills were discovered. Please ensure SKILL.md files are present in subdirectories and
have valid frontmatter.
请帮我排查下问题。
如下是 Gemini CLI 的 SKILL 的文档：
https://geminicli.com/docs/cli/skills/
请遵循该文档的规范。把报错原文 + 官方文档链接一起喂给它，比让它自己猜规范高效得多。
并行能力：这是它和 Claude Code 拉开差距的地方
Gemini CLI 真正让我觉得”这个工具有东西”的，是它的并行编排能力。具体有四个层面：
- 工具并行执行——单次交互里，它可以同时调用多个独立工具（同时搜文件、读配置、跑命令），默认并行，效率高很多。
- 专业 Sub-Agents——它内置了一组专家子 Agent，按任务复杂度委派：
codebase_investigator：专门做深度代码库分析和架构调研；generalist：处理批量、重复、高输出的任务；code-reviewer：重大变更后做专业 CodeReview。
- 并行任务编排——通过
dispatching-parallel-agents这类技能，把一个复杂请求拆成多个互不干扰的子任务，分发给并行实例。 - 智能调度策略——它自己当”战略协调员（Strategic Orchestrator）“，通过委派子 Agent 来压缩复杂工作，保证主会话的上下文保持精简。
这一点我体会很深。做大规模代码库调研时，Claude Code 倾向于”自己一条线查到底”，而 Gemini CLI 会派几个 sub-agent 同时挖不同方向，再把结果汇总。**对于”先广后深”的任务，Gemini 这种模式明显更快。**但反过来说，对于需要严格按因果链深挖一个 bug 的任务，这种并行反而会打乱思路——这正是我把写代码的活留给 Claude Code 的原因。
日常高频用的几个命令
这些是几乎每次会话都会用到的：
/mcp —— 看当前配了哪些 MCP
在 ~/.gemini/settings.json 里配置 MCP。输入 /mcp 可以查看当前加载了哪些。
/tools —— 看内置工具
输入 /tools 查看当前可用的内置工具。排查”为什么它没调用某个工具”时，先看这里。
Shell 模式：输入 ! 进入
输入 ! 开头，可以直接执行 shell 脚本，不用退出当前会话。频繁在 Agent 和命令行之间切换时，这个特别省事。
/memory add —— 设置记忆
/memory add XXX 可以添加记忆。比如 /memory add Always respond in Chinese-simplified，让它总是用简体中文回答。/memory show 可以查看已有的记忆。
最终这些都会记录在 ~/.gemini/GEMINI.md 文件里——**所以你也可以直接去编辑那个文件，批量管理记忆。**比一条条 add 效率高。
YOLO 模式：ctrl + y 切换
默认每次操作它都要你确认。ctrl + y 切到 YOLO 模式后，它自己猜完直接执行，不再问。
这个模式要小心。省心是省心了，但意外的高风险操作它也会直接执行。我的做法是：调研、生成文档这类只读/低风险任务开 YOLO；涉及删文件、改配置、发命令到线上的时候，老老实实关掉，让它每步问我。虽然每次它都会提示风险，但提示多了人会麻木，不能依赖提示。
跟 Claude Code 的分工（我现在的用法）
用下来我形成了这么一个分工习惯，不一定对所有人适用，但对我有效：
| 场景 | 我的工具选择 | 原因 |
|---|---|---|
| 批量生成文档 | Gemini CLI | 上下文大，并行 sub-agent 适合批量 |
| 大规模代码库调研 | Gemini CLI | codebase_investigator 广度好 |
| 写/改业务代码 | Claude Code | 精细控制强，单链路深挖更稳 |
| 调试一个具体 bug | Claude Code | 需要严格的因果推理，并行反而添乱 |
| 做技术宣讲材料 | Gemini CLI | Slidev + 大上下文，一气呵成 |
一句话：**Gemini CLI 是”指挥多个工人的包工头”，Claude Code 是”一个很靠谱的老师傅”。**活儿粗、量大、能并行的，交给包工头；活儿细、要稳、一条线到底的，交给老师傅。
后面想继续探索的
- Skill 写多了之后怎么管理、怎么复用，目前还比较散；
dispatching-parallel-agents的拆分粒度怎么定，拆太细会重复劳动，拆太粗又失去并行优势；- MCP 配置在多项目间的复用。
这篇会持续更新，等攒够新的实战经验再补。