Agent Skills (代理技能) 完全指南

这份文档整合了 Agent Skills 的核心概念、使用方法、最佳实践以及进阶技巧，旨在帮助你快速理解并掌握如何扩展 AI 智能体的能力。满满干货，值得学习，若有错误地方请各位佬指正。

1. 什么是 Agent Skills？

Agent Skills 是一套开放标准，用于将 AI 指令打包成可复用的“技能包”。
你可以把它想象成给 AI 智能体安装的专业插件或知识模块。通过技能，你可以教会 AI 如何遵循特定的团队规范、使用特定的工具或执行复杂的工作流。

核心运作机制：渐进式披露

为了保持高效，Agent 不会一次性读取所有技能的详情，而是遵循以下步骤：

1. 发现 (Discovery)：对话开始时，AI 只看到所有可用技能的名称和描述。
2. 激活 (Activation)：AI 根据你的请求，评估哪个技能最相关。
3. 执行 (Execution)：一旦匹配成功，AI 会加载该技能的完整指令文件 (SKILL.md) 并严格执行。

---

2. 技能存在哪里？

你可以根据技能的通用性，将其放在不同的位置：

类型	存储路径	适用场景	优先级
项目级技能	<项目根目录>/.agent/skills/	特定项目的代码规范、部署流程、架构约束	高 (覆盖全局)
全局技能	~/.gemini/antigravity/skills/	个人常用的通用工具、编码习惯、快捷指令	低

注：如果项目级技能和全局技能同名，项目级技能优先生效。

---

3. 如何创建一个技能？

创建一个技能非常简单，只需两步：

1. 在技能目录下创建一个文件夹（例如 my-skill）。
2. 在文件夹内创建一个 SKILL.md 文件。

目录结构示例

.agent/skills/
└── my-skill/
    ├── SKILL.md       # 核心指令文件 (必须)
    ├── scripts/       # 辅助脚本 (可选)
    └── resources/     # 模板或资源 (可选)

SKILL.md 文件格式

SKILL.md 由 YAML 元数据 和 Markdown 指令 组成：

---
name: my-skill               # 技能ID (建议使用小写字母和连字符)
description: 详细描述技能的作用。AI 依靠这段文字决定是否使用此技能。(必须)
---

# 技能标题

## 何时使用
描述适用的场景，例如：“当用户要求重构代码时...”

## 执行步骤
1. 第一步...
2. 第二步...

💡 编写技巧：在 description 中使用明确的触发词（如“生成”、“部署”、“审查”），并说明适用场景（“当用户要求…时”），能显著提高 AI 识别的准确率。

---

4. 最佳实践

为了让 AI 更好地使用你的技能，请遵循以下原则：

• 单一职责：一个技能只做一件事。不要创建“万能助手”技能，而是将不同功能拆分为 git-formatter、code-reviewer 等独立技能。
• 指令清晰：使用祈使句（“做这个”，“检查那个”），并提供清晰的验证标准。
• 脚本黑盒化：如果技能需要运行脚本，最好让 AI 通过 --help 了解用法并直接调用脚本，而不是让 AI 去阅读脚本的源代码。
• 版本控制：建议将 .agent/skills 纳入 Git 管理，方便团队共享和迭代。

---

5. 进阶技巧–决策树

此处不赘述决策树，只讲干货，有兴趣的朋友可自行了解。

多技能协作

AI 可以根据任务需求同时激活多个技能。
例如：先激活 code-reviewer 审查代码，通过后再激活 git-commit-formatter 提交代码。

条件执行与决策树

对于复杂任务，可以在技能中定义决策树：

## 部署流程
- 如果是测试环境 (Staging):
  1. 运行单元测试
  2. 执行部署脚本 `./deploy.sh staging`
- 如果是生产环境 (Production):
  1. 再次确认用户意图
  2. 运行全量测试
  3. 执行部署脚本 `./deploy.sh prod`

外部工具集成

技能可以指示 AI 调用命令行工具，如 ESLint, Prettier, TypeScript 编译器等，并根据退出码判断是否继续。

---

6. 常用技能示例

以下是一些常见的技能创意，你可以直接参考实现：

• git-commit-formatter: 自动生成符合 Angular/Conventional Commits 规范的 Git 提交信息。
• code-reviewer: 根据团队的代码风格指南，对 Pull Request 进行自动化审查。
• deploy-assistant: 封装复杂的部署命令，提供傻瓜式的自然语言部署接口。
• component-generator: 快速生成包含测试文件、样式文件和 Storybook 的完整前端组件结构。

---

总结：Agent Skills 是连接人类知识与 AI 能力的桥梁。通过简单的 Markdown 文档，你就可以定制出真正理解你团队规范和工作流的专属 AI 助手。
大白话：skill就是ai的专业技能