Skills 最佳实践
Gemini CLI Agent Skills 最佳实践：触发清晰、输入输出固定、少依赖、避免硬编码凭据、失败路径明确。
好的 Skill 应该让 Gemini CLI 更稳定，而不是让系统更难排错。
Skill 质量主要看触发准确、流程稳定、失败可恢复。不是 SKILL.md 越长越好。
先为发现设计
Skill 最重要的字段是 description。激活前模型只能看到名称和描述，所以描述必须包含任务关键词、触发场景和边界。
弱描述：
description: Helps with security.强描述：
description: Audit a local code diff for secrets, unsafe shell commands, dependency risks, and missing tests. Use when the user asks for a security review before release.描述重叠会导致误触发。如果两个 Skill 都写“review code”，模型无法稳定选择；应该拆成 security-review、performance-review、release-qa 这类边界更清楚的能力。
控制上下文层级
把 Skill 内容分三层：
name+description：常驻，越短越好。SKILL.md正文：激活后加载，只放核心流程。references/、assets/、scripts/：需要时再读。
详细规范、长案例、schema 不要塞进 SKILL.md 正文。正文越长，激活成本越高，也越容易和项目 GEMINI.md 打架。
Skill 激活后会把 SKILL.md 正文和目录结构注入会话，并把 Skill 目录加入允许读取的路径。所以最佳实践不是“把所有资料都塞给模型”，而是把常用步骤放正文，把长资料放 references，把确定性处理放 scripts。
自由度匹配任务风险
- 高自由度：写作、总结、探索类任务，用原则和输出格式即可。
- 中自由度：代码迁移、文档标准化，用步骤和伪代码约束。
- 低自由度：发布、删除、批量改文件、调用外部 API，用脚本和少量参数固定。
脆弱任务不要只靠自然语言描述；能写脚本验证的，就把脚本放进 scripts/。
| 任务风险 | Skill 写法 | 验证重点 |
|---|---|---|
| 低风险写作 | 原则 + 输出结构 | 风格和完整性 |
| 中风险代码修改 | 步骤 + 文件边界 | diff 和测试 |
| 高风险发布 | 脚本 + 人工确认 | 回滚和日志 |
| 安全审计 | 固定清单 + 扫描脚本 | 漏检和误报 |
| 外部 API | MCP / Extension 分层 | 凭据和权限 |
实用规则
- 触发场景明确。
- 输入和输出固定。
- 每个 skill 只负责一类任务。
- 不硬编码账号、token、路径。
- 失败时说明怎么恢复。
- 能用本地文件说明的，不依赖模型猜。
- 危险动作保留人工确认。
- 脚本输出要适合模型读取：少噪音、清楚的成功/失败、明确下一步。
- 第三方 Skill 安装前先读
SKILL.md和脚本，不直接信任。
Skill 输出也要可审计。涉及文件修改、发布、下载、网络请求、账号后台和外部 API 的 Skill，至少要说明输入来源、写入位置、回滚方式和失败时留下什么产物。否则它只是一个更难排查的 prompt。
反模式
- 一个 skill 包办所有事。
- 复制一堆泛泛 prompt。
- 不说明什么时候不用。
- 把凭据写进说明。
- 和项目
GEMINI.md规则冲突。 - 在
SKILL.md里塞整本手册，导致每次激活都污染上下文。 - 脚本失败只抛 traceback，没有给可操作原因。
验收方式
一个 Skill 至少做三项验收：触发是否准确，输出是否稳定，失败路径是否可恢复。涉及脚本的 Skill，还要单独运行脚本，确认它不依赖开发者本机私有路径、不打印密钥、不在失败时留下半成品。
最好准备两个反例 prompt：一个不该触发 Skill，一个应该触发但参数缺失。前者验证边界，后者验证失败路径。如果两种情况都能处理，Skill 才适合给团队使用。
第三方 Skill 还要额外看脚本权限、网络请求、安装后目录访问范围和是否试图读取用户 home 目录。只读完 SKILL.md 不够，scripts/ 才是高风险部分。
接下来去哪
激活 Skill
继续看 activate_skill、用户确认和目录访问范围。
创建 Skills
回看 SKILL.md、scripts、references、assets 的最小结构。
Extensions
需要分发 Skill 时，继续看 extension 安装和安全审查。