Gemini CLI 自定义Skill编写教程:附3个可复用模板封面图
Agent 与 Skills约 7 分钟

Gemini CLI 自定义Skill编写教程:附3个可复用模板

AI 指南··◉ 0 浏览

核心答案: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 词内;资源按需读取。

Gemini CLI 官方 Skills 文档截图

自定义 Skill 放哪里:4 层发现目录

官方定义 4 层发现目录,优先级从低到高:

  1. 内置技能:随 CLI 自带的基础能力。
  2. 扩展技能:装在扩展里的技能。
  3. 用户技能:~/.gemini/skills/,别名 ~/.agents/skills/,全局生效。
  4. 工作区技能:.gemini/skills/,别名 .agents/skills/,跟项目走,可提交 Git 共享。

同名技能取高优先级层;同一层内 .agents/skills/ 别名优先。别名机制让同一套技能兼容 Claude Code、Codex 等 Agent Skills 标准工具。日常开发放工作区,个人习惯放用户层。

Gemini CLI 技能 4 层发现目录示意图

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 和脚本。

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/ 别名可以跨工具共享同一套技能。

评论 (0)

?
0/1

还没有评论,来发第一条吧

网站上的服务均为第三方提供,
请用户注意自行甄别。

北京酷讯互动科技有限公司

备案京ICP备2024094994号-29

© 2026 AI345 · All Rights Reserved

用户服务协议·隐私政策