当我们在本地开发并调试自定义的大模型 Agent 技能（Skills）时，往往会遇到一个反直觉的阻碍：默认的安装命令居然找不到放在子目录里的代码。
许多开发者习惯性地把一个 GitHub 仓库作为一个独立的 Skill，但随着工具链的膨胀，将几十个细分领域的 Agent 技能强行塞进几十个独立的仓库，不仅维护成本极高，也割裂了代码间的上下文。
如果我们想在一个大仓库（Monorepo）里集中管理所有技能，该如何打破 Gemini CLI 默认只扫描根目录的限制？更关键的是，如何在修改代码后让 Agent 立即感知，而不是每次都走一遍枯燥的重装流程？
为什么默认安装会卡壳？
在默认行为下，当我们运行 gemini skills install https://github.com/... 时，CLI 的扫描器会径直寻找仓库根目录下的 SKILL.md 文件。这就是 Agent 识别元数据的唯一锚点。
如果你的目录结构是像下面这样，将核心逻辑封装在不同语言的模块中，而把具体的 Agent 技能定义收拢在 skills/ 子目录下，默认的安装器就会无功而返。
正如上图所示，当 SKILL.md 隐藏在层级之下时，我们需要更显式地进行路径映射。
对于远端仓库，我们可以通过附加参数精准定位：
gemini skills install https://github.com/org/repo.git --path skills/blogger-agent --consent
但在本地开发时，如果你还在用 install 命令，那就踩进了第二个坑：物理拷贝带来的状态隔离。
拷贝还是映射：Install vs Link
大多数开发者认为 install 是加载代码库的万能解。但对于持续演进的本地项目来说，install 是效率的杀手。
我们需要理解这两条核心命令在操作系统的底层流向：
install是一次性的物理快照：当我们执行gemini skills install . --path skills/blogger-agent时，CLI 会将该目录下的所有文件复制一份，硬编码进其内部的隐藏目录（如~/.gemini/skills/）。这意味着，我们随后在代码编辑器里敲下的每一行修改，Agent 都一无所知。要想生效，只能反复执行重装。link才是本地开发的杠杆：当我们转而使用gemini skills link skills/blogger-agent时，CLI 不再搬运文件，而是建立了一个软链接（Symbolic Link）。这等同于向 Agent 开放了当前开发目录的实时读写权限。
一旦建立了 Link，我们就构建起了一个“修改代码即刻生效”的飞轮。不需要重启 CLI，不需要重新输入授权，我们在 IDE 中保存了最新的 SKILL.md 触发词或工作流，在下一次对话中，Agent 就能直接按照新的逻辑运转。
最佳实践与重载
在实际工程中，我们推荐按以下步骤管理本地 Agent 技能库：
- 集中治理：在项目的
skills/目录下按功能拆分独立的 Agent 子目录，确保每个目录下有独立的SKILL.md。 - 局部链接：在项目根目录执行
gemini skills link skills/<target-skill>，仅挂载当前需要调试的技能。 - 热更新测试：如果在同一个交互会话中修改了技能定义，可以输入内部指令
/skills reload强制 CLI 重新加载内存中的元数据。
Agent 框架的演进，正在把我们从写正则匹配推向写自然语言意图。但在这个过程中，基础设施的工程化管理依然是不变的基石。告别低效的物理拷贝，用符号链接打通开发与执行的壁垒，是我们治理现代 AI 技能链的第一步。
