🚀 AI Agent Skills 完全教程：为 16+ AI 工具构建自定义技能

想象一下，编写一套指令一次，就能在 Claude Code、Cursor、OpenAI Codex、Gemini CLI、VS Code 等十多个 AI 工具中通用。这正是Agent Skills（代理技能）所能提供的——它们正迅速成为 AI 辅助开发的”npm 包”。

由 Anthropic 于 2025 年 12 月 18 日发布，Agent Skills 是一个开放标准，允许你将专业知识、工作流和自动化打包成可移植的目录，任何兼容的 AI 工具都可以加载和执行。截至 2026 年 3 月，已有16+ 主流 AI 工具采用了这一标准——从编码助手到自主代理。

这不是锁定在单一供应商的专有功能。这是整个行业在如何定制和扩展 AI 工具方面的转变。可以这样理解：如果 AI 编码助手是新的 IDE，那么 Agent Skills 就是扩展市场——只不过一个扩展可以在任何地方使用。

📚 你将学到什么

• 什么是 Agent Skills 以及为什么它们作为开放标准很重要
• 支持 skills 的 16+ 工具完整列表
• SKILL.md 规范——每个字段、每个选项
• 如何从零开始创建你的第一个技能，逐步指导
• Claude Code 的高级技能功能——捆绑技能、位置、子代理
• skills 如何在 Cursor、Codex、Gemini CLI 和 VS Code 中工作
• 5 个实用的技能配方，今天就可以复制使用
• 使用 skills.sh 进行技能管理——”代理的 npm”
• 安全风险：发现的 341 个恶意技能以及如何保护自己

🤖 什么是 Agent Skills？

Agent Skills 是“一种简单、开放的格式，用于赋予代理新的能力和专业知识”。这是 agentskills.io 的官方描述，完美地捕捉了这个概念。

在最基本的层面上，技能只是一个包含 SKILL.md 文件的目录。该 Markdown 文件告诉 AI 代理技能的作用、如何使用它以及要遵循什么规则。它可以可选地包括脚本、参考文档和静态资源。

💡 核心理念：一次编写，处处可用

在 Agent Skills 之前，定制 AI 工具意味着编写特定于工具的配置。你的 Cursor 规则在 Claude Code 中不起作用。你的 Codex 设置无法转移到 Gemini CLI。每个工具都有自己的格式、自己的约定、自己的限制。

Agent Skills 改变了这一点。一个技能目录，一个 SKILL.md 文件，它可以在支持该标准的每个工具中工作。截至 2026 年 3 月，这意味着 16+ 工具并且还在增长。

🔄 渐进式披露

规范中最聪明的设计决策之一是渐进式披露。当 AI 代理启动时，它不会读取每个技能的完整内容。它只从 YAML frontmatter 加载 name 和 description。

代理扫描这些简短描述以了解可用技能。只有当实际需要技能时——无论是用户触发还是代理匹配——它才会加载完整的 SKILL.md 内容、脚本和参考。

这意味着你可以安装数十甚至数百个技能而没有任何性能损失。代理在启动时保持快速，只在需要时加载所需内容。

📁 目录结构

每个技能都遵循此结构：

my-skill/
├── SKILL.md          # 必需 — 技能定义
├── scripts/          # 可选 — 可执行脚本
├── references/       # 可选 — 文档、示例
└── assets/           # 可选 — 图片、模板、配置

SKILL.md 文件是唯一的必需组件。其他一切都是可选的，按需加载。这使简单的技能保持简单——只需一个 Markdown 文件即可开始。

🛠️ 哪些工具支持 Agent Skills？

Agent Skills 的采用速度令人瞩目。在 2025 年 12 月公告后的三个月内，16+ 主流 AI 工具添加了支持。以下是 agentskills.io 上列出的完整列表：

这不仅仅是 Anthropic 的生态系统。当 Google 的 Gemini CLI、OpenAI 的 Codex、JetBrains 的 Junie 和 GitHub Copilot 都采用相同标准时，你就知道它已经成为真正的标准。Agent Skills 对于 AI 工具就像 package.json 对于 Node.js——每个人都同意的通用格式。

📝 SKILL.md 格式：规范深入

让我们深入技术细节。每个技能都以 SKILL.md 文件开始。该文件有两部分：YAML frontmatter 和 Markdown 内容。

YAML Frontmatter

Frontmatter enclosed 在文件顶部的 --- 分隔符中。以下是所有字段：

完整示例

以下是结构良好的 SKILL.md 的样子：

---
name: code-review
description: "执行彻底的代码审查，重点关注安全漏洞、性能问题和对团队编码标准的遵守。输出带有严重级别的结构化反馈。"
license: MIT
compatibility:
  - claude-code
  - cursor
  - codex
metadata:
  author: your-team
  version: 1.0.0
  tags:
    - code-quality
    - security
    - review
allowed-tools:
  - read
  - write
  - exec
---

# 代码审查技能

## 何时激活
当用户要求以下操作时激活此技能：
- 代码审查或 PR 审查
- 代码安全审计
- 性能审查
- 风格/标准合规检查

## 审查流程

### 步骤 1：理解上下文
- 阅读正在审查的文件
- 检查 .codestyle 或 .eslintrc 配置
- 识别语言和框架

### 步骤 2：安全审查
- 检查 SQL 注入漏洞
- 查找 XSS 攻击向量
- 验证输入验证
- 检查身份验证/授权模式

### 步骤 3：性能审查
- 识别 N+1 查询模式
- 检查不必要的重新渲染（React）
- 查找内存泄漏
- 验证 useEffect 钩子中的正确清理

### 步骤 4：输出格式
将反馈构建为：

| 严重性 | 问题 | 文件：行 | 建议 |
|--------|------|----------|------|
| 🔴 严重 | ... | ... | ... |
| 🟡 警告 | ... | ... | ... |
| 🔵 信息 | ... | ... | ... |

描述字段就是一切

description 字段是 frontmatter 中最重要的部分。记住渐进式披露——这是代理在启动时读取的唯一内容。如果你的描述没有清楚地传达技能的作用和何时使用它，代理永远不会激活它。

编写描述就像编写函数文档字符串。具体说明触发条件和输出格式。避免模糊的描述，如”帮助编码”——而是说”执行以结构化严重级别输出为焦点的安全代码审查”。

🔧 创建你的第一个技能：逐步指导

让我们从零开始构建一个真实的技能。我们将创建一个”commit-message”技能，根据暂存的更改生成约定式提交消息。

步骤 1：创建目录

mkdir -p my-project/.claude/skills/commit-message

对于项目特定的技能，.claude/skills/ 目录是常规位置。这使技能与代码一起版本控制。

步骤 2：编写 SKILL.md

创建 .claude/skills/commit-message/SKILL.md：

---
name: commit-message
description: "从暂存的 git 更改生成约定式提交消息。分析差异，对更改进行分类（feat/fix/refactor/docs/test/chore），并编写清晰、描述性的提交消息，遵循约定式提交规范。"
license: MIT
metadata:
  author: your-name
  version: 1.0.0
---

# 提交消息生成器

## 何时激活
当用户要求以下操作时使用此技能：
- 用户要求"提交"或"写提交消息"
- 用户在编辑后说"发生了什么变化"
- 用户要求在 git 仓库中"保存我的工作"

## 流程

### 步骤 1：获取差异
运行 `git diff --staged` 查看已暂存的内容。如果没有暂存内容，运行 `git diff` 并询问用户是否要暂存所有更改。

### 步骤 2：分析更改
对每个更改进行分类：
- **feat**：新功能或能力
- **fix**：错误修复
- **refactor**：代码重构而不改变行为
- **docs**：仅文档
- **test**：添加或更新测试
- **chore**：构建、CI、依赖、配置

### 步骤 3：确定范围
查看哪些文件/目录发生了更改以确定范围：
- `src/auth/*` → 范围是 `auth`
- `tests/*` → 范围是 `tests`
- 多个目录 → 省略范围或使用主要目录

### 步骤 4：编写消息
格式：`type(scope): 简短描述`

规则：
- 冒号后首字母小写
- 末尾没有句号
- 主题行最多 72 个字符
- 使用祈使语气（"add" 而不是"added"）

如果更改复杂，添加正文：
```markdown
feat(auth): 为 Google 登录添加 OAuth2 支持

- 使用 PKCE 实现 Google OAuth2 流程
- 添加令牌刷新逻辑
- 创建新的 GoogleAuthProvider 类
- 使用 Google 按钮更新登录页面
```

### 步骤 5：呈现并确认
显示生成的消息并询问："准备用此消息提交吗？(y/n/edit)"

步骤 3：添加可选脚本

技能可以包括可执行脚本。让我们添加一个验证提交消息的辅助脚本：

mkdir -p .claude/skills/commit-message/scripts

创建 scripts/validate-commit.sh：

#!/bin/bash
# 根据约定式提交格式验证提交消息
MSG="$1"
PATTERN="^(feat|fix|refactor|docs|test|chore|style|perf|ci|build|revert)(\(.+\))?: .{1,72}$"

if echo "$MSG" | head -1 | grep -qP "$PATTERN"; then
  echo "✅ 有效的约定式提交消息"
  exit 0
else
  echo "❌ 格式无效。预期：type(scope): description"
  exit 1
fi

步骤 4：添加参考文档

如果你的技能需要上下文文档，将它们添加到 references/：

mkdir -p .claude/skills/commit-message/references

创建 references/commit-conventions.md，包含你团队的特定约定、好坏提交示例或代理应知道的任何额外上下文。

步骤 5：测试它

在任何支持的工具（Claude Code、Cursor、Codex、Gemini CLI）中打开你的项目，进行一些代码更改。然后询问：”为我的更改写一个提交消息。”

代理应该从其描述中检测到 commit-message 技能，激活它，并遵循你定义的流程。如果它没有激活，检查你的描述——它可能没有清楚地匹配用户的意图。

📦 最终目录结构

.claude/skills/commit-message/
├── SKILL.md
├── scripts/
│   └── validate-commit.sh
└── references/
    └── commit-conventions.md

就是这样。一个目录，一个 SKILL.md 文件，你的 AI 助手现在可以在任何支持 Agent Skills 的工具中生成完美的提交消息。

🔒 安全：供应链风险

随着生态系统的巨大增长，带来了巨大的安全责任。2026 年 2 月，prplbx.com 的安全研究人员发表了研究结果，向 Agent Skills 社区发出了警钟。

发现 341 个恶意技能

截至 2026 年 2 月 3 日，研究人员已在社区中心识别出341 个恶意技能。这些技能包含隐藏的有效负载，从数据泄露到凭据盗窃。攻击面是真实且不断增长的。

这与我们在 npm 包、PyPI 包和 VS Code 扩展中看到的模式相同。只要有一个流行的生态系统且易于发布，不良行为者就会出现。Agent Skills 也不例外——在某些方面风险更高，因为技能可以捆绑以 AI 代理权限运行的可执行脚本。

攻击面

恶意技能可以：

• 执行任意脚本— 技能可以包括代理运行的 scripts/
• 泄露代码— 具有读取权限的技能可以将你的代码发送到外部服务器
• 注入后门— “代码生成”技能可以在你的代码中插入漏洞
• 窃取凭据— 脚本可以读取环境变量、配置文件、SSH 密钥
• 污染模型的上下文— SKILL.md 本身中的微妙提示注入

如何保护自己

底线：像对待第三方 npm 包一样对待第三方技能。安装前审计。限制权限。关注运行的内容。

💡 总结

Agent Skills 代表了我们与 AI 工具交互方式的根本转变。Skills 不是需要不断指导的通用代理，而是创建已经了解你的框架、遵循你的约定并自动应用最佳实践的专业代理。

生态系统已从 Claude Code 特定功能发展到每个主流 AI 编码工具采用的开放标准。在 skills.sh 等注册表上有超过 57,000 个技能，可能有你使用的任何框架、工作流或工具链的技能。如果没有，创建一个就像编写 Markdown 文件一样简单。

从安装两三个与你的主要工作流匹配的技能开始，无论是用于前端工作的 Vercel React 技能、用于后端开发的 Supabase 技能，还是用于纪律开发实践的 Superpowers。一旦你体验到通用代理和技能代理之间的差异，你就再也回不去了。

YUANLEISVIP

收藏 链接