---
title: "Skills 最佳实践"
description: "Gemini CLI Agent Skills 最佳实践：触发清晰、输入输出固定、少依赖、避免硬编码凭据、失败路径明确。"
verifiedAt: "2026-05-09"
---

好的 Skill 应该让 Gemini CLI 更稳定，而不是让系统更难排错。

> [!NOTE]
> Skill 质量主要看触发准确、流程稳定、失败可恢复。不是 `SKILL.md` 越长越好。

## 先为发现设计

Skill 最重要的字段是 `description`。激活前模型只能看到名称和描述，所以描述必须包含任务关键词、触发场景和边界。

弱描述：

```yaml
description: Helps with security.
```

强描述：

```yaml
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 内容分三层：

1. `name` + `description`：常驻，越短越好。
2. `SKILL.md` 正文：激活后加载，只放核心流程。
3. `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/` 才是高风险部分。

## 接下来去哪

<Cards>
  <Card title="激活 Skill" description="继续看 activate_skill、用户确认和目录访问范围。" href="/docs/gemini-cli/official/04-agents-skills/43-activate-skill" />
  <Card title="创建 Skills" description="回看 SKILL.md、scripts、references、assets 的最小结构。" href="/docs/gemini-cli/official/04-agents-skills/41-create-skills" />
  <Card title="Extensions" description="需要分发 Skill 时，继续看 extension 安装和安全审查。" href="/docs/gemini-cli/official/03-tools-mcp/38-extensions" />
</Cards>

## 官方来源

- [Agent Skill best practices](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills-best-practices.md)
