跳到主要内容

工具支持

Agent Skills 作为开放标准，已被多种 AI 编程工具支持。本章介绍各工具对 Skills 的支持情况和使用方法。

支持工具概览​

Agent Skills 是开放标准，任何 AI 工具都可以实现支持。以下是目前支持该标准的主要工具：

工具支持状态Skills 目录特殊功能
Claude Code✅ 完全支持.claude/skills/子代理、参数化 Skill、钩子
OpenAI Codex✅ 完全支持.codex/skills/$skill-installer、$skill-creator
Trae IDE✅ 完全支持.trae/skills/Skill 创建工具、MCP 集成
Cursor✅ 支持.cursor/skills/Background Agents、MCP 支持
Windsurf✅ 支持.windsurf/skills/Cascade 模式
Gemini CLI✅ 支持.gemini/skills/渐进式披露
GitHub Copilot✅ 支持VS Code 扩展原生集成
跨客户端共享

.agents/skills/ 已成为跨客户端共享 Skills 的通用约定。将 Skill 放在此目录，所有支持该标准的客户端都能发现和使用它。

OpenAI Codex​

OpenAI Codex 是 OpenAI 官方推出的命令行 AI 编程助手，从 2025 年底开始全面支持 Agent Skills。

安装 Skills​

方式一：使用内置 $skill-installer

Codex 内置了 skill 安装器，可以直接在对话中安装：

$skill-installer install the linear skill from the .experimental folder

方式二：使用 Skills.sh CLI（推荐）

Vercel 维护的 skills.sh 是官方推荐的包管理工具：

# 安装 skill 包
npx skills add vercel-labs/agent-skills

# 安装特定 skill
npx skills add vercel-labs/agent-skills --skill frontend-design

# 搜索 skill
npx skills find "react testing"

# 更新所有 skill
npx skills update

方式三：手动创建

mkdir -p .codex/skills/my-skill

目录结构​

Codex 支持多级 Skills 目录，优先级从高到低：

项目根目录/
├── .codex/skills/          # 项目级 Skills（最高优先级）
├── ../.codex/skills/       # 父目录 Skills（嵌套项目）
├── ~/.codex/skills/        # 用户级 Skills
└── /etc/codex/skills/      # 系统级 Skills（最低优先级）

使用 Skills​

隐式调用：根据 description 自动匹配

用户：应用最新的数据库迁移
AI：（自动使用 database-migration skill）

显式调用：使用 $ 前缀强制调用

用户：$legal-templates 起草一份保密协议

交互式浏览：

/skills

创建 Skills​

使用内置的 $skill-creator：

$skill-creator "用于自动重构 React 组件的 Skill"

Codex 会自动创建目录结构、编写 SKILL.md 文件和必要的脚本。

与 MCP 的关系​

Codex 同时支持 Agent Skills 和 MCP（Model Context Protocol）：

  • Agent Skills：基于 Markdown 的指令包，适合封装工作流程和最佳实践
  • MCP：基于 JSON-RPC 的协议，适合实时数据访问和复杂集成

两者可以结合使用：Skills 处理高层工作流程，MCP 处理实时数据需求。

Claude Code​

Claude Code 是 Anthropic 官方的命令行 AI 编程助手，于 2025 年 10 月首次推出 Agent Skills 功能，是 Agent Skills 标准的创始者。

安装 Skills​

方式一：使用 Skills.sh CLI（推荐）

# 安装 skill
npx skills add vercel-labs/agent-skills

# 搜索 skill
npx skills find "database"

# 更新 skill
npx skills update

方式二：自然语言安装

直接告诉 Claude Code 安装 Skill：

帮我安装 skill，项目地址是：https://github.com/anthropics/skills/blob/main/skills/code-reviewer

方式三：手动创建

在项目根目录创建 Skills 目录：

mkdir -p .claude/skills/my-skill

创建 SKILL.md 文件：

touch .claude/skills/my-skill/SKILL.md

方式四：从 GitHub 克隆

cd .claude/skills
git clone https://github.com/anthropics/skills.git temp
mv temp/skills/* .
rm -rf temp

使用 Skills​

安装后，Skills 会根据 description 自动触发：

用户：请审查这段 Python 代码
AI：（自动使用 python-code-reviewer skill）

也可以显式调用：

用户：使用 code-reviewer skill 审查这个文件

管理 Skills​

查看已安装的 Skills：

列出所有已安装的 skills

更新 Skill：

直接编辑 .claude/skills/ 目录下的文件。

删除 Skill：

rm -rf .claude/skills/skill-name

Trae IDE​

Trae IDE 是一款支持 Agent Skills 的集成开发环境，提供了可视化的 Skill 管理功能。

安装 Skills​

方式一：使用 Skill 创建工具

Trae IDE 内置了 Skill 创建工具，可以通过界面引导创建新的 Skill。

方式二：手动创建

mkdir -p .trae/skills/my-skill

创建 SKILL.md 文件并编写内容。

目录结构​

项目根目录/
├── .trae/
│   ├── skills/
│   │   ├── code-reviewer/
│   │   │   └── SKILL.md
│   │   └── test-generator/
│   │       └── SKILL.md
│   └── rules/
│       └── project_rules.md
└── ...

使用 Skills​

在对话中直接描述需求，Trae IDE 会自动匹配并触发相应的 Skill：

用户：帮我审查一下 src/main.py 这个文件
AI：（自动使用 code-reviewer skill）

创建 Skill 的最佳实践​

Trae IDE 提供了 Skill 创建的最佳实践模板：

---
name: "skill-name"
description: "功能描述。Invoke when [触发条件]。"
---

# Skill 标题

[详细指令内容]

注意：description 中建议使用 "Invoke when" 来描述触发条件，这是 Trae IDE 的推荐格式。

Cursor​

Cursor 是一款流行的 AI 编程编辑器，支持 Agent Skills 和 MCP（Model Context Protocol）。

配置 Skills​

Skills 存放在 .cursor/skills/ 目录：

项目根目录/
├── .cursor/
│   ├── skills/
│   │   └── my-skill/
│   │       └── SKILL.md
│   └── rules/
│       └── .cursorrules
└── ...

使用方式​

在 Cursor 的 AI 对话中，Skills 会根据用户输入自动触发。Cursor 还支持：

  • Background Agents：后台代理可以在你工作时异步执行任务
  • MCP 集成：通过 MCP 连接外部工具和服务
  • Auto Mode：自动模式让 AI 自主规划和执行任务

与 MCP 结合​

Cursor 支持通过 MCP 使用 Skills 功能：

// .cursor/mcp.json
{
  "mcpServers": {
    "claude-skills": {
      "command": "npx",
      "args": ["-y", "@k-dense-ai/claude-skills-mcp"]
    }
  }
}

Windsurf​

Windsurf 是 Codeium 推出的 AI 编程工具，支持 Agent Skills 和 Cascade 模式。

目录结构​

项目根目录/
├── .windsurf/
│   └── skills/
│       └── my-skill/
│           └── SKILL.md
└── ...

使用方式​

与 Claude Code 类似，Skills 会根据 description 自动触发。

Cascade 模式​

Windsurf 的 Cascade 模式支持：

  • 智能上下文管理：自动维护对话上下文
  • 多文件编辑：同时处理多个文件
  • Skills 集成：在 Cascade 中使用 Skills 扩展能力

Gemini CLI​

Google 的 Gemini CLI 于 2026 年初正式支持 Agent Skills 标准。

目录结构​

项目根目录/
├── .gemini/
│   └── skills/
│       └── my-skill/
│           └── SKILL.md
└── ...

特点​

  • 与 Google 生态系统深度集成
  • 支持 Gemini 系列模型
  • 兼容标准的 Agent Skills 格式
  • 支持渐进式披露（Progressive Disclosure）模式

GitHub Copilot​

GitHub Copilot 在 VS Code 中通过扩展支持 Agent Skills，提供原生集成体验。

安装与使用​

Copilot 的 Skills 支持内置于 VS Code 扩展中：

  1. 安装 GitHub Copilot 扩展
  2. 在 Chat 面板中使用 / 命令查看可用 Skills
  3. Skills 会根据对话上下文自动触发

特点​

  • 与 VS Code 深度集成
  • 支持自然语言触发 Skills
  • 可通过设置自定义 Skills

OpenCode​

OpenCode 是一款支持 Agent Skills 和 ACP（Agent Connect Protocol）的 AI 编程工具。

目录结构​

项目根目录/
├── .opencode/
│   └── skills/
│       └── my-skill/
│           └── SKILL.md
└── ...

特点​

VS Code 扩展​

多款 VS Code 扩展支持 Agent Skills，为开发者提供多样化选择。

Cline​

Cline 是一款开源的 VS Code AI 编程扩展，支持 Agent Skills。

目录结构：

项目根目录/
├── .cline/
│   └── skills/
│       └── my-skill/
│           └── SKILL.md
└── ...

特点：

  • 支持多种模型（Claude、GPT、Gemini 等）
  • 开源免费
  • 支持 Skills 扩展能力

全局 Skills​

除了项目级别的 Skills，大多数工具还支持全局 Skills，适用于所有项目。

Skills 扫描范围​

大多数本地运行的 Agent 会扫描至少两个范围：

范围路径用途
项目级<project>/.<client>/skills/客户端原生位置
项目级<project>/.agents/skills/跨客户端共享（通用约定）
用户级~/.<client>/skills/客户端原生位置
用户级~/.agents/skills/跨客户端共享（通用约定）

.agents/skills/ 已成为跨客户端 Skill 共享的广泛采用约定。虽然 Agent Skills 规范没有强制要求 Skill 目录的位置，但扫描 .agents/skills/ 意味着其他合规客户端安装的 Skills 会自动对你的客户端可见，反之亦然。

信任考虑​

项目级 Skills 来自正在处理的仓库，可能是不可信的（如新克隆的开源项目）。建议对项目级 Skill 加载进行信任检查——只有用户将项目文件夹标记为受信任时才加载。这可以防止不受信任的仓库静默向 Agent 上下文中注入指令。

信任机制实现建议：

场景建议处理
打开新项目提示用户确认是否信任项目级 Skills
用户拒绝信任只加载用户级 Skills，跳过项目级
用户已标记信任正常加载所有 Skills
Skills 内容变更可选：提示用户重新确认

安全最佳实践：

  1. 沙箱隔离：考虑在隔离环境中执行 Skill 脚本
  2. 权限最小化：限制 Skill 可访问的资源范围
  3. 审计日志：记录 Skill 激活和执行情况
  4. 用户确认：对高风险操作要求显式确认

权限白名单​

如果你的 Agent 有权限系统来控制文件访问，应该将 Skill 目录加入白名单。这样模型在读取捆绑资源时就不会触发用户确认弹窗。否则，每次引用捆绑脚本或参考文件都会弹出权限对话框，打断包含资源的 Skill 的正常工作流程。

实现建议：

// 权限配置示例
{
  "allowed_paths": [
    "~/.claude/skills/",
    "~/.agents/skills/",
    "./.claude/skills/",
    "./.agents/skills/"
  ]
}

上下文管理​

当对话上下文窗口填满时，Agent 可能会压缩或总结旧消息。Skill 内容应该被保护，不被修剪。Skill 指令是持久的行为指导——在对话中途丢失它们会默默降低 Agent 的性能，而没有任何可见的错误提示。模型会继续工作，但失去了 Skill 提供的专业指令。

常见保护策略：

策略说明
标记保护将 Skill 工具输出标记为受保护，让压缩算法跳过它们
结构化标签使用结构化标签标识 Skill 内容，在压缩时保留
去重激活跟踪已激活的 Skills，避免重复加载相同指令

去重激活示例：

如果模型（或用户）尝试加载已经在上下文中的 Skill，可以跳过重新注入，避免相同指令在对话中出现多次。这不仅节省 Token，也保持了对话的清晰性。

全局 Skills 位置​

工具全局 Skills 目录
Claude Code~/.claude/skills/
OpenAI Codex~/.codex/skills/
Trae IDE~/.trae/skills/
Cursor~/.cursor/skills/
Windsurf~/.windsurf/skills/
Gemini CLI~/.gemini/skills/
OpenCode~/.opencode/skills/
Cline~/.cline/skills/

全局 vs 项目 Skills​

  • 全局 Skills：适用于所有项目，适合通用技能（如代码审查、文档生成）
  • 项目 Skills：仅适用于当前项目，适合项目特定需求（如特定框架规范）

优先级​

当全局和项目中存在同名 Skill 时，项目级 Skill 优先。

Skills 共享​

GitHub 仓库​

可以将 Skills 发布到 GitHub 仓库供他人使用：

my-skills/
├── README.md
├── skills/
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── test-generator/
│       └── SKILL.md
└── LICENSE

安装共享的 Skills​

从 GitHub 仓库安装：

# Claude Code
git clone https://github.com/user/my-skills.git temp
mv temp/skills/* .claude/skills/
rm -rf temp

或使用自然语言：

帮我安装 skill，地址是：https://github.com/user/my-skills

跨工具兼容性​

由于 Agent Skills 是开放标准，同一个 Skill 可以在不同工具中使用。

兼容性注意事项​

  1. 目录位置：不同工具使用不同的目录名
  2. description 格式：建议同时包含功能描述和触发条件
  3. 特殊功能：某些工具可能有特殊功能，但核心格式保持一致

跨工具使用示例​

假设你有一个 Skill：

---
name: "code-reviewer"
description: "审查代码质量。当用户请求代码审查时触发。"
---

# 代码审查专家
...

这个 Skill 可以直接复制到不同工具的 skills 目录中使用：

# 复制到 Claude Code
cp -r my-skill .claude/skills/

# 复制到 OpenAI Codex
cp -r my-skill .codex/skills/

# 复制到 Trae IDE
cp -r my-skill .trae/skills/

# 复制到 Cursor
cp -r my-skill .cursor/skills/

# 复制到 Windsurf
cp -r my-skill .windsurf/skills/

# 复制到 Gemini CLI
cp -r my-skill .gemini/skills/

# 复制到 OpenCode
cp -r my-skill .opencode/skills/

# 复制到 Cline (VS Code)
cp -r my-skill .cline/skills/

脚本设计最佳实践​

如果你的 Skill 包含脚本，遵循以下最佳实践可以显著提升 Agent 使用脚本的体验。

避免交互式提示（硬性要求）​

这是 Agent 执行环境的硬性要求。Agent 在非交互式 Shell 中操作——它们无法响应 TTY 提示、密码对话框或确认菜单。一个阻塞在交互式输入上的脚本将无限期挂起。

正确做法：通过命令行标志、环境变量或 stdin 接受所有输入：

# 错误：交互式提示
name = input("Enter your name: ")

# 正确：命令行参数
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--name", required=True)
args = parser.parse_args()

使用 --help 文档​

--help 输出是 Agent 了解脚本接口的主要方式。包含简要描述、可用标志和使用示例：

def main():
    parser = argparse.ArgumentParser(
        description="分析代码库并生成依赖关系图",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
示例:
  python analyze.py ./src
  python analyze.py ./src --format json --output deps.json
  python analyze.py ./src --exclude "tests/*" --exclude "docs/*"
        """
    )
    parser.add_argument("path", help="要分析的代码目录")
    parser.add_argument("--format", choices=["text", "json", "dot"], 
                       default="text", help="输出格式")
    parser.add_argument("--output", "-o", help="输出文件路径")
    parser.add_argument("--exclude", action="append", 
                       help="排除的文件模式")

写有帮助的错误信息​

当 Agent 收到错误时，错误信息直接影响它的下一次尝试。模糊的"Error: invalid input"浪费一次对话轮次。相反，说明哪里错了、期望什么、以及应该尝试什么：

# 错误：模糊的错误信息
if not os.path.exists(path):
    raise ValueError("Invalid input")

# 正确：有帮助的错误信息
if not os.path.exists(path):
    raise ValueError(
        f"Path not found: {path}\n"
        f"Make sure the directory exists and is accessible.\n"
        f"Current working directory: {os.getcwd()}"
    )

使用结构化输出​

优先使用结构化格式——JSON、CSV、TSV——而非自由文本。结构化格式可以被 Agent 和标准工具（jq、cut、awk）同时处理，使脚本可在管道中组合使用。

分离数据和诊断信息：将结构化数据发送到 stdout，将进度消息、警告和其他诊断信息发送到 stderr。这样 Agent 可以捕获干净、可解析的输出，同时仍能访问诊断信息。

import sys
import json

def analyze(path):
    # 诊断信息到 stderr
    print(f"Analyzing {path}...", file=sys.stderr)
    
    # 结构化数据到 stdout
    result = {"path": path, "dependencies": [...]}
    print(json.dumps(result, indent=2))

其他设计考虑​

幂等性：Agent 可能重试命令。"不存在则创建"比"创建并在重复时报错"更安全。

输入约束：用清晰的错误拒绝模糊输入，而不是猜测。尽可能使用枚举和封闭集合。

Dry-run 支持：对于破坏性或有状态操作，--dry-run 标志让 Agent 预览将要发生什么。

有意义的退出码：为不同的失败类型使用不同的退出码（未找到、参数无效、认证失败），并在 --help 输出中记录它们。

安全默认值：考虑破坏性操作是否需要显式确认标志（--confirm、--force）或其他适合风险级别的保护措施。

可预测的输出大小：许多 Agent 工具会自动截断超过阈值（如 10-30K 字符）的工具输出。如果脚本可能产生大量输出，默认使用摘要或合理的限制，并支持 --offset 等标志让 Agent 在需要时请求更多信息。

调试 Skills​

验证 Skill 格式​

确保 SKILL.md 文件格式正确：

  1. frontmatter 使用 --- 包围
  2. name 和 description 字段存在
  3. description 不超过 1024 字符

测试触发​

测试 Skill 是否正确触发：

  1. 使用 description 中包含的关键词
  2. 观察是否正确调用 Skill
  3. 检查输出是否符合预期

常见问题​

Skill 不触发

  • 检查 description 是否包含正确的关键词
  • 确认 Skill 文件位置正确
  • 验证 frontmatter 格式

输出不符合预期

  • 检查指令是否清晰
  • 添加更多示例
  • 明确输出格式

工具对比总结​

特性Claude CodeOpenAI CodexTrae IDECursorWindsurfGemini CLI
Skills 支持✅ 完整✅ 完整✅ 完整✅ 支持✅ 支持✅ 支持
MCP 支持✅ 支持✅ 支持✅ 支持✅ 支持✅ 支持✅ 支持
包管理器Skills.shSkills.sh内置工具---
内置安装器自然语言$skill-installer界面引导---
Skill 创建器自然语言$skill-creator界面引导---
多层级 Skills✅ 支持✅ 5级✅ 支持✅ 支持✅ 支持✅ 支持
后台代理✅ 支持✅ 支持✅ 支持✅ Background Agents✅ Cascade-
开放标准✅ 创始者✅ 采用✅ 采用✅ 采用✅ 采用✅ 采用

选择建议​

  • Claude Code：追求最完整的 Skills 生态和官方支持
  • OpenAI Codex：习惯 OpenAI 生态，需要与 GPT 模型深度集成
  • Trae IDE：偏好图形界面，需要可视化 Skill 管理
  • Cursor：需要 Background Agents 和强大的 MCP 生态
  • Windsurf：喜欢 Cascade 模式的智能上下文管理
  • Gemini CLI：深度使用 Google 服务和 Gemini 模型

历史背景​

Agent Skills 标准的发展历程：

  • 2025年10月：Anthropic 在 Claude Code 中首次推出 Claude Skills 功能
  • 2025年12月：Anthropic 将 Agent Skills 发布为开放标准，多家厂商宣布支持
  • 2026年1月：OpenAI 在 Codex CLI 中采用该标准，Vercel 推出 Skills.sh 包管理器
  • 2026年初：Google 在 Gemini CLI 中支持 Agent Skills
  • 2026年：Trae IDE、Cursor、Windsurf 等工具陆续支持，形成跨平台生态

小结​

各工具对 Agent Skills 的支持情况：

  1. Claude Code：创始者，最完整的生态，支持子代理、参数化和钩子
  2. OpenAI Codex：全面支持，提供 $skill-installer 和 $skill-creator 工具
  3. Trae IDE：内置可视化 Skill 创建工具，支持 MCP 集成
  4. Cursor：支持 Background Agents 和丰富的 MCP 生态
  5. Windsurf：Cascade 模式提供智能上下文管理
  6. Gemini CLI：支持渐进式披露
  7. 跨工具兼容：所有工具遵循相同的开放标准，Skills 可无缝迁移
  8. 跨客户端共享：使用 .agents/skills/ 目录实现跨客户端共享

下一章是 知识速查表，汇总所有关键知识点。