# Skills 描述、分层加载与可靠性

> 为模型提供清晰触发条件，用资源分层控制上下文，并按任务风险约束步骤。

- 网址：https://funcoding.ai/agents/gemini-cli/build/skills-design/
- 核实日期：2026-10-08（命令、配置和价格以官方文档为准）
- 官方来源：[Gemini CLI 官方文档：Skill best practices](https://geminicli.com/docs/cli/skills-best-practices)、[Gemini CLI 官方文档：Agent Skills](https://geminicli.com/docs/cli/skills)

---
Skill 的可靠性取决于能否被正确选择，以及激活后能否执行清楚、可验证的步骤。名称好听或指令冗长都不能代替这两点。

## 描述负责发现

启动时主要加载 name 和 description。描述应写明领域、何时使用与具体任务，例如评审性能回归，而不是笼统“帮助开发”。多个 Skill 应有清楚分工，避免描述完全重叠。

官方最佳实践把 description 称为激活前唯一信息，概览同时列 name 与 description；实际编写应同时关注名称和描述，不把全部辨识信息藏在尚未加载的正文中。

## 三层内容

元数据长期在上下文中，正文在激活后加载，资源按需读取。官方给出的约百词元数据、正文少于五千词是编写指导，不是本页声称的解析器硬性限制。

正文保留核心流程，长 schema、实例和背景资料放 references，并明确在什么步骤读取。scripts 负责确定性工作，assets 负责模板。

## 按任务选择约束程度

| 任务特点 | 指令方式 |
| --- | --- |
| 多种合理方案，依赖项目语境 | 给判断标准与目标 |
| 有优先方案但允许调整 | 给带参数的流程或伪代码 |
| 顺序敏感、易出错 | 给明确步骤和少量参数 |

限制越具体越需要维护；环境与接口变化后，要检查脚本和指令是否仍匹配。

## 输出可判断

脚本应提供明确的成功、失败和必要证据，减少无关 traceback。流程要区分“检查没有发现问题”和“检查没有执行成功”，不要统一输出一个成功标记。

## 资源与隐私

不要硬编码 key 或密码。安装第三方 Skill 前同时审阅正文和脚本；目录授权后资源可读取，应保持范围集中。可执行脚本并不因为随 Skill 分发就自动可信。