
Gemini CLI 自定义Skill编写教程:附3个可复用模板
核心答案:Gemini CLI 的自定义 Skill 就是在一个目录里放一个 SKILL.md,头部用 YAML 写 name 和 description,正文写操作指引,模型碰到匹配任务时按需加载。建目录、写文件、reload 三步就能被识别。本文按官方文档整理 SKILL.md 规范、4 层发现目录和三套可复制模板。
想直接抄模板,跳到「3 个可复用 SKILL.md 模板」。技能不触发,先看「验证与调试」。
Gemini CLI 的 Skill 是什么
Gemini CLI 是谷歌开源的终端 AI 助手,基于 Agent Skills 开放标准 实现 Skill 机制。一个 Skill 是自包含目录,把指令、脚本、参考资料打包成能力包。
和 GEMINI.md 常驻上下文不同,Skill 随需加载:会话启动只注入 name 和 description,模型判断任务匹配后调用激活工具、弹确认框,你同意后 SKILL.md 正文和目录才进上下文。官方把加载分三级:元数据常驻约 100 词;正文触发后加载,建议 5000 词内;资源按需读取。

自定义 Skill 放哪里:4 层发现目录
官方定义 4 层发现目录,优先级从低到高:
- 内置技能:随 CLI 自带的基础能力。
- 扩展技能:装在扩展里的技能。
- 用户技能:~/.gemini/skills/,别名 ~/.agents/skills/,全局生效。
- 工作区技能:.gemini/skills/,别名 .agents/skills/,跟项目走,可提交 Git 共享。
同名技能取高优先级层;同一层内 .agents/skills/ 别名优先。别名机制让同一套技能兼容 Claude Code、Codex 等 Agent Skills 标准工具。日常开发放工作区,个人习惯放用户层。

SKILL.md 怎么写:frontmatter 与正文规范
SKILL.md 是唯一必填文件。头部是 YAML frontmatter,两个字段缺一不可:name 是技能唯一标识,建议和目录名一致;description 是触发关键,官方标注 CRITICAL,要写清楚处理什么任务、什么关键词触发。写得太含糊是技能不触发的最常见原因。
正文用 Markdown 写操作指引。官方推荐结构(Creating Agent Skills):
my-skill/
├── SKILL.md (必填)指令与元数据
├── scripts/ (可选)可执行脚本
├── references/ (可选)静态参考文档
└── assets/ (可选)模板等资源
脚本用于确定性任务,references 放详细资料,assets 放模板。别在技能里硬编码 API Key,装第三方技能前先看 SKILL.md 和脚本。

Gemini CLI 自定义 Skill 编写步骤
两条路二选一。
路径一:让 skill-creator 生成。内置元技能,直接对话:Create a new skill called 'code-reviewer' that analyzes local files for common errors and style violations。它会生成目录、带 name 和 description 的 SKILL.md 和三个标准资源目录。
路径二:手动建。mkdir -p .gemini/skills/code-reviewer/scripts 建目录,写 SKILL.md,放脚本,/skills reload 刷新。Windows 用 New-Item -ItemType Directory -Force -Path 建。
验证:新开会话说一句命中 description 的话,比如 Can you review index.js,模型请求激活权限,同意后执行脚本。跑 /skills 看是否被识别。
3 个可复用 SKILL.md 模板
模板一:code-review 代码审查,带 Node 脚本。
.gemini/skills/code-review/
├── SKILL.md
└── scripts/
└── review.js
---
name: code-review
description: 检查代码变更的正确性、安全性和风格问题。用户要求 review 代码或 PR 时使用。
---
# Code Review Instructions
你是一位资深软件工程师,负责代码质量。技能激活后必须:
1. 分析:检查逻辑错误、安全漏洞和风格问题。
2. 执行:用 scripts/review.js 做一次自动化检查。
3. 反馈:区分严重问题和轻微改进点,给出可执行建议。
const file = process.argv[2];
if (!file) {
console.error('Usage: node review.js <file>');
process.exit(1);
}
console.log(`Reviewing ${file}...`);
setTimeout(() => {
console.log(`Result: Success (No major issues found in ${file})`);
}, 500);
模板二:commit-message 提交信息规范,规范放 references。
.gemini/skills/commit-message/
├── SKILL.md
└── references/
└── convention.md
---
name: commit-message
description: 按团队规范生成 git 提交信息。用户要求写 commit message、提交信息或 commit 时使用。
---
# Commit Message Instructions
技能激活后,先读 references/convention.md 里的规范,再按格式生成提交信息:类型、范围、主题、正文写法都要符合规范,主题不超过 50 个字符,禁止口语化表达。
模板三:release-notes 发布说明生成,模板放 assets。
.gemini/skills/release-notes/
├── SKILL.md
└── assets/
└── template.md
---
name: release-notes
description: 根据 git 变更记录生成发布说明。用户要求写 release notes、发布说明或 changelog 时使用。
---
# Release Notes Instructions
技能激活后,用 assets/template.md 的模板组织发布说明,按新增、修复、优化、破坏性变更分组,每条写明影响和迁移方式,用户确认后再输出。
三个模板覆盖三种形态:带脚本的(确定性任务)、带参考文档的(规范约束)、带模板的(产出格式约束)。技能里接外部工具走 MCP,见《Gemini CLI MCP 配置指南》。
验证与调试:/skills 与 gemini skills 命令
会话内:/skills list [all] [nodesc] 列出技能;/skills enable、disable 控制启停,默认 user 范围,加 --scope workspace 管项目;/skills reload 重新扫描。
终端:gemini skills list --all;gemini skills install 从 Git 仓库或本地目录装,--consent 跳过确认;gemini skills uninstall 卸载;gemini skills link . 链接本地目录测试。
不触发按顺序排查:description 太泛、改完没 reload、激活确认框没同意。限流类报错看《Gemini CLI 429 报错解决》。全局配置改哪里看《Gemini CLI settings.json 配置》,登录和国内网络看《Gemini CLI 国内使用指南》。
常见问题
Gemini CLI 自定义 Skill 放在哪个目录?
答:全局放 ~/.gemini/skills/,项目级放 .gemini/skills/,也可以用 .agents/skills/ 别名。放这两个位置之外,模型扫描不到。
SKILL.md 的 name 和 description 必须写吗?
答:必须。frontmatter 里 name 和 description 缺一不可,description 还是技能触发机制的核心,写不清楚模型就不会激活它。
Gemini CLI 装了 Skill 为什么不触发?
答:三个常见原因:description 写得太泛,模型判断不出匹配时机;改完 SKILL.md 没 reload,还在用旧缓存;激活时确认框没同意。按这个顺序排查即可。
gemini skills install 和 /skills link 有什么区别?
答:install 是从 Git 仓库或本地目录安装技能,uninstall 对应卸载;link 是把本地开发目录链接进技能目录,适合边写边测。enable 和 disable 只控制启停,不卸载。
自定义 Skill 里能放脚本和文件吗?
答:能。scripts 放可执行脚本,references 放参考文档,assets 放模板,技能激活后整个目录都对模型开放。官方建议把详细资料挪进 references,SKILL.md 正文保持精简。
Gemini CLI 的 Skill 和 Claude Code 的 Skill 通用吗?
答:都基于 Agent Skills 开放标准,SKILL.md 的结构和 frontmatter 一致,技能目录可以直接复用,用 .agents/skills/ 别名可以跨工具共享同一套技能。

京ICP备2024094994号-29