---
title: "创建 Skills"
description: "Gemini CLI 创建 Agent Skill 的判断标准：什么时候应该沉淀、结构如何保持小、如何避免把一次性任务过度工程化。"
verifiedAt: "2026-05-09"
---

创建 Skill 的前提不是“这个功能很酷”，而是“这个任务会重复出现，而且每次都需要同一套步骤和约束”。

> [!IMPORTANT]
> 先跑通流程，再沉淀 Skill。没验证过的流程写进 Skill，只会把一次性混乱变成长期混乱。

## 创建前检查

| 问题 | 如果答案是 no |
| --- | --- |
| 这个任务会重复吗 | 不要建 skill |
| 流程已经跑通过吗 | 先手工跑一次 |
| 输入输出能固定吗 | 先整理契约 |
| 风险边界清楚吗 | 先补安全说明 |
| 比 custom command 更复杂吗 | 简单任务用 custom command |

## 推荐目录

`SKILL.md` 是唯一必需文件，但真实 Skill 通常需要把确定性部分拆出来：

```text
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` 是触发器，必须写“什么时候用”，而不是泛泛描述能力。

```markdown
---
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` 才算写对。

## 接下来去哪

<Cards>
  <Card title="Skills 最佳实践" description="继续看 description、上下文层级、脚本和失败路径怎么设计。" href="/docs/gemini-cli/official/04-agents-skills/42-skills-best-practices" />
  <Card title="激活 Skill" description="创建后要验证触发是否准确，继续看激活流程。" href="/docs/gemini-cli/official/04-agents-skills/43-activate-skill" />
  <Card title="Skill 安全" description="第三方 Skill 安装前，要回到 extensions 和安全控制做审查。" href="/docs/gemini-cli/official/03-tools-mcp/38-extensions" />
</Cards>

## 官方来源

- [Creating Agent Skills](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/creating-skills.md)
