创建 Skills
Gemini CLI 创建 Agent Skill 的判断标准：什么时候应该沉淀、结构如何保持小、如何避免把一次性任务过度工程化。
创建 Skill 的前提不是“这个功能很酷”，而是“这个任务会重复出现，而且每次都需要同一套步骤和约束”。
先跑通流程，再沉淀 Skill。没验证过的流程写进 Skill，只会把一次性混乱变成长期混乱。
创建前检查
| 问题 | 如果答案是 no |
|---|---|
| 这个任务会重复吗 | 不要建 skill |
| 流程已经跑通过吗 | 先手工跑一次 |
| 输入输出能固定吗 | 先整理契约 |
| 风险边界清楚吗 | 先补安全说明 |
| 比 custom command 更复杂吗 | 简单任务用 custom command |
推荐目录
SKILL.md 是唯一必需文件，但真实 Skill 通常需要把确定性部分拆出来：
my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/scripts/放可重复执行的检查、转换、采集脚本。references/放长规范、schema、API 说明、示例报告。assets/放模板、样例文件、非执行资源。
Skill 激活后，模型会获得整个目录的读取权限。目录里不要放凭据、客户原始数据或本机专属路径。
官方发现层级包括 built-in、extension、user 和 workspace。个人长期能力放 ~/.gemini/skills/ 或 ~/.agents/skills/；项目共享能力放 .gemini/skills/ 或 .agents/skills/。团队教程里要明确 scope，否则读者可能把个人 Skill 误提交到项目仓库。
SKILL.md 最小结构
SKILL.md 使用 YAML frontmatter。name 要和目录名一致，description 是触发器，必须写“什么时候用”，而不是泛泛描述能力。
---
name: code-reviewer
description: Review local code changes for correctness, security, and style. Use when the user asks to review a diff or PR.
---
# Code Reviewer
1. Inspect the changed files.
2. Run the bundled deterministic checks when available.
3. Report bugs first, then risks, then missing tests.一个好的 description 应该包含触发词、任务边界和不该触发的边界。模型在激活前只看得到这段元数据。
官方也提供校验和打包脚本思路：先 validate，再 package。实际团队不一定直接使用官方脚本，但必须保留同等验收：frontmatter 可解析、name 与目录一致、description 能触发正确任务、目录里没有凭据和本机路径。
Skill 应该小
一个 skill 只解决一类任务。不要把“写文章、发站点、配图、SEO、GitHub 发布”塞进一个 skill。复杂流程交给工作流编排。
Skill 和 command 的取舍
| 情况 | 建议 |
|---|---|
| 只需要一条固定 prompt | Custom command |
| 需要脚本、模板、参考资料 | Skill |
| 需要外部 API 或服务 | MCP / Extension |
| 需要多个阶段和人工验收 | 工作流 + Skill |
| 还没复用超过 3 次 | 先不要建 Skill |
Skill 的价值在于按需加载完整能力包。越是低风险、短流程、单输入输出的任务，越应该先用 command 或普通文档，不要过度工程化。
创建方式
最快方式是让 Gemini CLI 使用内置 skill-creator 生成骨架。手工创建时，把 Skill 放到 .gemini/skills/<name>/ 或 .agents/skills/<name>/。如果是团队共享，放工作区目录并进入版本管理；如果只是个人能力，放 ~/.gemini/skills/ 或 ~/.agents/skills/。
本地开发独立 Skill 仓库时，用 gemini skills link . 链接测试。要分发给别人，可以作为 extension、单独 Git 仓库，或工作区内共享目录。
安装第三方 Skill 时不要直接跳过 consent。终端安装命令可能提供 --consent 这类跳过确认的选项，它适合自动化受控环境，不适合普通教程默认使用。
验收方式
创建后重启或执行 /skills reload，再运行 /skills list 检查是否被发现。触发测试要覆盖两类输入：一个应该激活 Skill，一个不应该激活 Skill。能区分这两类，说明 description 才算写对。
接下来去哪
Skills 最佳实践
继续看 description、上下文层级、脚本和失败路径怎么设计。
激活 Skill
创建后要验证触发是否准确，继续看激活流程。
Skill 安全
第三方 Skill 安装前，要回到 extensions 和安全控制做审查。