gemini-cli Agent Skills 管理指南：发现层级、斜杠命令与终端工具链

本文围绕 gemini-cli 的 Agent Skills（智能体技能）管理体系展开，系统讲解技能的四层发现机制（内置、扩展、用户、工作区）、会话内 /skills 斜杠命令的完整用法，以及 gemini skills 终端命令族的安装、链接、卸载操作。读完后，你可以掌握技能优先级冲突的裁决规则、技能开发时的本地热链接流程，以及安装远程技能时的同意确认与路径安全机制。

一、Agent Skills 是什么

Agent Skills 为 Gemini CLI 提供"按需注入"的专业能力：每个技能本质上是一个包含 SKILL.md 文件的目录，其中 frontmatter 声明 name 与 description，正文承载核心指令。CLI 在会话中通过技能名称匹配来触发对应技能，从而把特定领域的知识、脚本和资源临时挂载到代理上下文中。

从源码看，技能的加载入口是 skillLoader.ts：它对目标目录执行 SKILL.md 与 */SKILL.md 两种 glob 匹配（自动忽略 node_modules 与 .git），解析 YAML frontmatter 后生成 SkillDefinition 对象，包含 name、description、location（源文件绝对路径）与 body（正文内容）。若 YAML 解析失败（例如 description 中含冒号），会回退到简易的按行解析器；技能名中的 :\/<>*?"| 等非法字符会被统一替换为 -，保证可安全用作目录名。

二、发现层级：四个来源与优先级

Gemini CLI 从多个位置发现技能，按优先级从低到高依次为：

1. 内置技能（Built-in Skills）：随 CLI 发行、始终可用。仓库中当前内置于 builtin 目录，包含 antigravity-support 与 skill-creator 两个技能。
2. 扩展技能（Extension Skills）：随扩展一起打包分发。
3. 用户技能（User Skills）：位于 ~/.gemini/skills/ 或其别名目录 ~/.agents/skills/，对所有项目生效。
4. 工作区技能（Workspace Skills）：位于当前目录下的 .gemini/skills/ 或别名目录 .agents/skills/，仅对当前项目生效。

提示：如果多个技能同名，优先级更高的位置会覆盖低优先级的版本。

上述规则的直接实现是 SkillManager.discoverSkills()，它按"内置 → 扩展 → 用户 → 用户别名 → 工作区 → 工作区别名"的顺序调用 addSkillsWithPrecedence()。该方法以名称为键维护一个 Map，后加载的同名技能直接覆盖前者，并产生两条可观测行为：

• 覆盖内置技能时，通过 debugLogger.warn 记录警告；
• 覆盖非内置技能时，通过 coreEvents 向界面发射 "Skill conflict detected" 警告反馈，告诉用户哪个路径覆盖了哪个路径。

两个值得注意的实现细节：

• 信任目录限制：discoverSkills() 接收 isTrusted 参数，当工作区未被信任时，会跳过工作区技能加载并输出调试日志。这意味着工作区技能只在受信任的项目目录中生效。
• 内置技能标记：内置技能加载后会被打上 isBuiltin 标记，getDisplayableSkills() 会将其从常规 UI 列表中排除，因此 /skills list 默认不显示内置技能，需要显式加上 all 参数。

目录位置常量定义在 storage.ts 的 getUserSkillsDir()、getUserAgentSkillsDir()、getProjectSkillsDir()、getProjectAgentSkillsDir() 中，.agents/skills 作为跨工具的通用别名目录与 .gemini/skills 完全等价。

三、会话内管理：/skills 斜杠命令

在交互式会话中，使用 /skills 命令族管理已发现的技能：

命令	作用
/skills list	列出已发现的技能
/skills list all	额外显示内部内置技能
/skills list nodesc	隐藏描述，仅显示名称
/skills reload（或 /skills refresh）	重新扫描新增或修改的技能，无需重启 CLI
/skills disable <name>	禁用某技能，阻止其被触发
/skills enable <name>	重新启用被禁用的技能
/skills link <path> [--scope user|workspace]	立即链接一个本地开发中的技能

禁用与启用：底层是 settings 中的名单

enable / disable 并非修改技能文件本身，而是维护配置文件中的禁用名单。从源码结构看，config.ts 持有 disabledSkills: string[] 字段，发现技能后调用 skillManager.setDisabledSkills()，后者按小写名称匹配给每个技能打上 disabled 标志；getSkills() 只返回未被禁用的技能，getAllSkills() 则保留全部。/skills reload 时配置会刷新该名单并重新注册技能激活工具（对应 config.test.ts 中 "should refresh disabledSkills and re-register ActivateSkillTool" 的测试场景）。

热重载

修改 SKILL.md 后执行 /skills reload，管理器会清空并重新执行 discoverSkills() 全流程，因此可以立即看到新增技能或修改后的描述，无需重启终端会话。

会话级激活状态

SkillManager 还维护 activeSkillNames 集合（activateSkill / isSkillActive），记录当前会话中已被激活的技能；reset() 会清空这一会话级状态。这对应文档中"每次技能触发都需要用户确认"的同意模型——激活是显式、逐次发生的动作。

四、终端工具：gemini skills 命令族

gemini skills（别名 gemini skill）在系统 shell 中提供全套管理工具，其命令注册表见 skills.tsx，共六个子命令：list、enable、disable、install、link、uninstall。

4.1 列出技能：gemini skills list [--all]

list.ts 会加载工作区设置与完整 CLI 配置并触发扩展加载和技能发现，然后输出每个技能的名称、启用状态（[Enabled] / [Disabled]）、内置标记（[Built-in]）、描述与磁盘位置。不加 --all 时自动过滤内置技能，输出按"非内置在前、名称字母序"排序。

4.2 安装技能：gemini skills install

从远程仓库或本地 .skill 包安装技能：

# 从 git 仓库安装（默认安装到用户级 ~/.gemini/skills/）
gemini skills install https://github.com/user/my-awesome-skill

# 仅安装到当前项目（.gemini/skills/）
gemini skills install https://github.com/user/my-awesome-skill --scope workspace

# 安装仓库子目录中的技能
gemini skills install https://github.com/user/repo --path skills/my-skill

install 子命令的完整参数（见 install.ts）：

• source（必填）：git 仓库 URL（http://、https://、git@ 开头）或本地路径；
• --scope：user（默认）或 workspace，决定目标目录是 ~/.gemini/skills/ 还是项目内 .gemini/skills/；
• --path：仅对 git 源有效，指定仓库内的子路径；
• --consent：跳过确认提示，直接确认安装（适用于脚本化场景）。

核心安装逻辑在 skillUtils.ts 的 installSkill() 中，流程为：

1. git URL 源先克隆到 gemini-skill-* 前缀的临时目录；以 .skill 结尾的本地源则用 extract-zip 解压到临时目录；
2. 若有 --path，在临时目录内解析子路径，并做目录穿越（path traversal）安全检查；
3. 用 loadSkillsFromDir() 在源中搜索有效技能，找不到 SKILL.md 会明确报错 "Ensure a SKILL.md file exists with valid frontmatter"；
4. 调用同意回调展示将要安装的技能清单，用户拒绝则中止；
5. 逐个复制技能目录到目标位置（同名已存在时先删除再覆盖），结束后清理临时目录。

4.3 开发链接：gemini skills link

技能开发时使用 link 创建指向本地目录的符号链接，源目录的修改可即时生效：

gemini skills link ./path/to/my-skill            # 默认 user 级
gemini skills link ./path/to/my-skill --scope workspace  # 仅当前项目

link 同样支持 --consent 参数。实现上（linkSkill()）会先对源内技能做重名冲突检查（同一目录树内出现两个同名技能直接报错并列出两处路径），确认同意后在目标技能目录创建符号链接——在 Windows 上使用 junction 而非普通目录链接，以避免提权或开发者模式要求。

4.4 卸载技能：gemini skills uninstall

彻底移除已安装或已链接的技能（删除整个技能目录）：

gemini skills uninstall my-skill                 # 默认从 user 级移除
gemini skills uninstall my-skill --scope workspace

uninstallSkill() 先在目标目录中发现技能并匹配名称；若元数据缺失或损坏，会回退到"目录名匹配"路径并删除对应目录（保持向后兼容），同时用 path.relative 校验目标始终位于技能根目录之内。

4.5 终端中的启用/禁用

与斜杠命令对应，gemini skills enable <name> / gemini skills disable <name> 操作设置文件中的禁用名单。反馈信息会指明变更写入了哪个作用域的设置（见 enable.ts 与 skillUtils.ts 的 renderSkillActionFeedback()），当两个作用域的设置都受影响时会同时列出。

五、安全与同意机制

Agent Skills 可以执行脚本并访问文件，gemini-cli 设置了两道确认关卡：

1. 安装同意（Installation consent）：从远程 URL 或本地路径安装/链接技能前，skillsConsentString() 会生成包含技能清单、来源与目标目录的确认文本，由 requestConsentNonInteractive() 请求用户确认；只有显式传入 --consent 才会跳过。
2. 激活同意（Activation consent）：每次会话中技能被触发时，代理必须先请求权限才能激活它并访问其资源。

在代码层面，安全约束还包括：

• 路径穿越防护：安装时 --path 子路径与解压后的源路径都经过 isPathTraversal() 检查，禁止 .. 或绝对路径逃逸出临时目录；技能名解析后也要落在目标目录内；
• 重名冲突拒绝：链接操作发现源内重名技能时直接失败，避免歧义覆盖；
• 信任目录门控：工作区技能在未信任的目录中不会被发现（见前文 isTrusted 分支）。

六、延伸阅读

围绕本文的管理视角，以下文档可进一步深入：

• Agent Skills 入门教程：创建第一个技能的完整演练；
• 编写 Agent Skills：打包脚本与资源的详细指南；
• 技能最佳实践：构建可靠技能包的策略；
• 扩展指南：理解扩展技能这一发现层级的载体。