Gemini CLI 的 Skills 系统让你把复杂工作流打包成可复用的"专家角色"：在 .gemini/skills/ 目录下创建包含 SKILL.md 的目录，写清楚触发场景（description 字段），AI 就会在适当时候自动激活并遵循技能中定义的行为步骤。本文以 API 审计技能为例，演示完整的创建和使用流程。

创建你的第一个 Agent Skill

Agent Skills 让你把专业知识封装进可复用的目录——AI 会在合适的时机自动激活它，像切换角色一样运用专业能力。

创建技能目录

以 API 审计技能为例，该技能帮助你验证本地或远程接口是否正常响应。

建立目录结构

macOS/Linux：

mkdir -p .gemini/skills/api-auditor/scripts

Windows PowerShell：

New-Item -ItemType Directory -Force -Path ".gemini\skills\api-auditor\scripts"

创建 SKILL.md 定义文件

在 .gemini/skills/api-auditor/SKILL.md 创建技能定义。这个文件告诉 AI 何时使用技能，以及如何行动：

---
name: api-auditor
description: |
  API 端点审计和测试专家。当用户请求"检查"、"测试"或"审计"某个 URL 或 API 时激活。
---

# API 审计师说明

你是专注于 API 可靠性的 QA 工程师。技能激活时，你必须：

1. **审计**：使用捆绑的 `scripts/audit.js` 工具检查提供的 URL 状态。
2. **报告**：分析输出（状态码、延迟），用简明语言解释任何失败原因。
3. **安全提醒**：如果用户测试的端点不使用 `https://`，提醒可能的安全风险。

description 字段是 AI 决定是否激活技能的唯一依据，要写得清晰、覆盖真实的触发场景。

添加工具脚本

技能可以捆绑辅助脚本。在 .gemini/skills/api-auditor/scripts/audit.js 创建：

// .gemini/skills/api-auditor/scripts/audit.js
const url = process.argv[2];

if (!url) {
  console.error('用法：node audit.js <url>');
  process.exit(1);
}

console.log(`正在审计 ${url}...`);
fetch(url, { method: 'HEAD' })
  .then((r) => console.log(`结果：成功 (状态码 ${r.status})`))
  .catch((e) => console.error(`结果：失败 (${e.message})`));

验证技能被发现

Gemini CLI 会自动扫描 .gemini/skills/ 目录（也支持 .agents/skills/），查看是否找到了你的新技能：

/skills list

你应该在列表中看到 api-auditor。

使用技能

启动新会话，发起一个能触发技能描述的请求：

帮我审计 http://geminicli.com

AI 识别到请求与 api-auditor 的 description 匹配，请求权限激活技能：

（激活 api-auditor 技能后）我将运行审计脚本...

然后 AI 使用 run_shell_command 工具执行你捆绑的 Node 脚本：

node .gemini/skills/api-auditor/scripts/audit.js http://geminicli.com

技能目录的完整结构

.gemini/skills/api-auditor/
├── SKILL.md              # 必须，包含 frontmatter 和行为说明
├── scripts/              # 可选，辅助脚本
│   └── audit.js
└── templates/            # 可选，模板文件（如报告模板）
    └── report.md

安装社区技能

除了自己创建，还可以从 Git 仓库安装社区技能：

# 安装到用户级别（所有项目可用）
gemini skills install https://github.com/user/my-skill.git

# 安装到工作区级别（仅当前项目）
gemini skills install /path/to/skill --scope workspace

更多 Skills 管理命令，参见 Skills 完整参考。

下一步

• 了解 SKILL.md 的高级功能：Skills 参考文档
• 通过 Extensions 分享技能给团队：Extensions 文档

常见问题

Q: AI 如何判断要激活哪个技能？

A: 完全根据 SKILL.md frontmatter 中的 description 字段。AI 将你的请求与所有已知技能的 description 做语义匹配，高相关度的技能会自动激活。所以 description 写得越精准、覆盖真实触发词越多，效果越好。

Q: 一次对话可以激活多个技能吗？

A: 可以，AI 可以根据对话进展在不同阶段激活不同技能。每次激活都会将该技能的完整 SKILL.md 内容注入上下文，注意多技能并发会增加 Token 消耗。

Q: .gemini/skills/ 和 ~/.gemini/skills/ 有什么区别？

A: 前者是工作区级别（只在当前项目生效，通常提交到 git 供团队共享），后者是用户级别（所有项目都能使用，个人私有）。同名技能工作区级别优先级更高。