Skill 创建与使用最佳实践（以Trae为例）

一、什么是 Skill？

Skill 是 AI 助手的“能力插件”——一个封装了特定领域知识、标准化工作流程和可复用逻辑的模块化功能包。简单来说：

• 给 AI 的“岗位操作手册”：告诉 AI 如何处理某一类任务
• 可复用的工作流模板：同样的输入，稳定输出同样的格式
• 能力边界清晰的功能单元：一个 Skill 只专注解决一个问题

核心理念：Skill 本质上是将“一次性提示词”升级为可复用、可版本管理、可共享的工程化能力单元。

---

二、通用 Skill 规范（Agent Skills Specification）

2025 年 12 月，Anthropic 正式将 Agent Skills 作为开放标准发布，目前已在 Claude Code、Cursor、GitHub Copilot、Gemini CLI 等 16 种以上主流 AI 工具中获得支持。

2.1 核心设计原理：渐进式披露

Skill 采用三层渐进式披露机制来平衡“能力丰富度”与“推理成本”：

层级	内容	加载时机	作用
L1 发现层	名称 + 简短描述（元数据）	Agent 启动时预加载	让 Agent 知道“有哪些能力”，仅占约 100 tokens
L2 激活层	完整 SKILL.md 指令文件	任务匹配该 Skill 时自动加载	注入详细步骤、规则和示例
L3 执行层	脚本、参考文档、资源文件	执行具体子任务时按需调用	处理复杂计算，不占用 LLM 上下文

实测数据：渐进式披露架构能将上下文 Token 消耗降低 60%-80%，同时显著提升长文本任务中的指令遵循准确率。

2.2 标准目录结构

一个符合通用规范的 Skill 是一个文件夹，包含以下内容：

my-skill/                      # 技能根目录（文件夹名即技能名）
├── SKILL.md                   # 必需：元数据(YAML) + 核心指令(Markdown)
├── scripts/                   # 可选：可执行脚本（Python/Shell等）
│   └── helper.py
├── references/                # 可选：参考文档（按需加载）
│   └── guide.md
└── assets/                    # 可选：模板、图片等资源文件
    └── template.docx

2.3 SKILL.md 文件规范

SKILL.md 是每个 Skill 的唯一入口文件，必须包含 YAML frontmatter 和 Markdown 正文：

---
name: skill-name
description: 一句话说明技能功能和适用场景
license: Apache-2.0
metadata:
  version: "1.0.0"
---

# 技能说明
详细描述这个技能解决什么问题...

# 工作流程
1. 第一步...
2. 第二步...

# 注意事项
- 边界情况...
- 错误处理...

字段要求：

• name（必需）：小写字母、数字、连字符组成，最长 64 字符，必须与父文件夹名一致
• description（必需）：最长 1024 字符，说明“做什么”和“何时使用”
• license（可选）：许可证名称
• metadata（可选）：自定义键值对，可用于存放版本号等信息

正文规范：

• SKILL.md 正文建议控制在 500 行以内，超出时应将详细文档移至 references/ 目录
• 采用祈使句编写指令，明确说明“为什么”而非仅“做什么”

---

三、Trae 中的 Skill 实现

3.1 存放位置

Trae 支持两种 Skill 范围：

范围	路径	生效范围
项目级	项目根目录/.trae/skills/<skill-name>/	仅当前项目
用户级	~/.trae/skills/<skill-name>/	所有项目

3.2 Trae 对通用规范的遵循

Trae 完整遵循 Agent Skills 开放规范。这意味着：

• 一个通用 Skill 文件夹（包含 SKILL.md + 可选 scripts/references/assets）可以直接放入 Trae 的 skills 目录使用
• Trae 实现了渐进式披露机制——启动时仅加载元数据，匹配任务时再加载完整指令
• 来自 skills.sh 或其他平台的开源 Skill，理论上可以直接在 Trae 中使用（具体兼容性需测试确认）

---

四、通用 Skill 与 Trae Skill 的区别与联系

对比维度	通用 Skill 规范	Trae 中的 Skill
定位	跨平台标准，定义“Skill 长什么样”	该标准在 Trae IDE 中的具体实现
核心文件	SKILL.md（必须）+ 可选资源目录	完全一致，也使用 SKILL.md
目录结构	标准化的多目录结构（scripts/references/assets）	完全兼容，但也可以只放一个 SKILL.md
渐进式披露	规范定义的核心机制	已完整实现
Skill 范围	由各平台自行定义	项目级（.trae/skills/）+ 用户级（~/.trae/skills/）
可移植性	设计目标就是跨平台复用	通用 Skill 可直接放入使用

联系：Trae 是 Agent Skills 开放规范的一个实现者。你在 Trae 中创建的 Skill，只要遵循通用规范，也可以在其他兼容该规范的工具（如 Claude Code、Cursor）中使用。

区别：Trae 为了降低上手门槛，允许最小化形式——只创建一个 SKILL.md 文件即可使用。而通用规范虽然也以 SKILL.md 为入口，但推荐配合 scripts/、references/、assets/ 等目录实现更复杂的功能。

---

五、完整示例

5.1 通用 Skill 完整示例

以下是一个完整的通用 Skill 示例——「PDF 合同分析器」。

目录结构：

contract-analyzer/
├── SKILL.md
├── scripts/
│   └── extract_clauses.py
├── references/
│   ├── contract_clauses.md
│   └── legal_terms.txt
└── assets/
    └── report_template.md

SKILL.md：

---
name: contract-analyzer
description: 分析PDF格式的合同文件，提取关键条款（保密、违约责任、争议解决），识别风险点并生成分析报告。适用于用户上传合同文件或提供合同文本时使用。
license: MIT
metadata:
  version: "1.0.0"
  author: "legal-team"
---

# 角色
你是一位专业的合同分析专家，擅长从合同中提取关键条款并识别潜在风险。

# 工作流程

1. **接收输入**：用户提供 PDF 文件或合同文本内容
2. **条款提取**：扫描并提取以下关键条款：
   - 保密条款（confidentiality）
   - 违约责任条款（liability/indemnification）
   - 争议解决条款（dispute resolution）
   - 知识产权归属（IP ownership）
3. **风险识别**：根据 `references/contract_clauses.md` 中的标准判断风险等级
4. **报告生成**：使用 `assets/report_template.md` 模板生成分析报告

# 关键条款定义

详见 `references/contract_clauses.md`，该文档定义了各类条款的标准表述和风险判断标准。

# 脚本调用

如需批量提取 PDF 文本，可调用 `scripts/extract_clauses.py` 进行预处理。

# 输出格式

```markdown
# 合同分析报告

## 基本信息
- 合同名称：
- 分析日期：

## 关键条款
| 条款类型 | 原文摘录 | 风险等级 | 说明 |
|----------|----------|----------|------|

## 风险提示
- [ ] 风险1
- [ ] 风险2

## 建议
...

我随便在网上找了一个城市供用气合同的模版，可以看出技能生效了

5.2 Trae 简易 Skill 示例

在 Trae 中，如果你只需要一个简单的指令型 Skill，只需一个 SKILL.md 文件即可。

路径：项目根目录/.trae/skills/meeting-minutes/SKILL.md

---
name: meeting-minutes
description: 从会议记录生成结构化会议纪要，提取决策和待办事项。适用于用户提供会议转写文本或笔记时使用。
---

# 角色
你是一位专业的会议纪要整理专家。

# 工作流程
1. 解析文本，提取参会人和议题
2. 抽取决策和待办事项
3. 按以下模板输出

# 输出模板

```markdown
# 会议纪要：{主题}

**日期**：{日期}
**参会人**：{参会人}

## 一、议题
- {议题}

## 二、决定事项
- {决定}

## 三、待办事项
| 任务 | 负责人 | 截止日期 |
|------|--------|----------|

这就是 Trae 的最小 Skill——无需任何额外目录，一个文件即可工作。

我用AI生成了一篇会议，然后用这个skill做会议纪要提取，效果不错：

---

六、在 Trae 中使用通用 Skill 的方案

方案一：直接复制粘贴

1. 从 GitHub 或其他来源获取一个符合通用规范的 Skill 文件夹

2. 将其完整复制到 Trae 的 skills 目录：

   .trae/skills/contract-analyzer/
   ├── SKILL.md
   ├── scripts/
   ├── references/
   └── assets/
   

3. Trae 会自动识别该 Skill

方案二：使用 npx skills add 安装

利用 skills.sh 生态，一键安装开源 Skill：

# 安装来自 Vercel Labs 的 Skill
npx skills add vercel-labs/agent-skills

# 安装特定仓库的 Skill
npx skills add anthropics/skills

该命令会自动将 Skill 安装到兼容工具的对应目录，Trae 作为兼容平台之一可直接使用。

方案三：Git 克隆

cd .trae/skills/
git clone https://github.com/anthropics/skills.git

方案四：手动创建通用结构

在 Trae 中创建完整的通用 Skill 结构：

mkdir -p .trae/skills/my-skill/{scripts,references,assets}
touch .trae/skills/my-skill/SKILL.md
# 然后按通用规范编写 SKILL.md

---

七、两种方案的对比

对比维度	简易 Skill（仅 SKILL.md）	通用 Skill（完整目录）
文件数量	1 个文件	多个文件/目录
复杂度	低，上手快	中高，需要规划结构
适用场景	纯指令型任务（如格式化输出、工作流引导）	需要脚本处理、大量参考文档、模板文件的复杂任务
Token 效率	相对较高（内容少）	更高（渐进式披露，按需加载大文件）
可移植性	通用规范也支持（仅 SKILL.md 也符合规范）	完整规范，可移植性最好
团队共享	可以，但资源分散	方便，所有资源打包在一起
维护成本	低	中

选择建议：

• 如果你的 Skill 只需指导 AI“怎么做”（如输出格式、工作流程），用简易 Skill 即可
• 如果你的 Skill 需要处理数据、调用外部工具、引用大量文档，建议使用通用完整结构

---

八、如何在 Trae 中使用开源 Skill

8.1 查找开源 Skill

方法一：skills.sh

访问 skills.sh，这是 Vercel 推出的 Skill 索引和分发平台，排行榜按安装量排序，所有 Skill 均来自官方或知名机构，质量有保障。

方法二：GitHub 搜索

在 GitHub 上搜索以下关键词：

• SKILL.md + agent-skills
• anthropics/skills（官方示例库）
• claude-skill 或 agent-skill

方法三：SkillKit

使用 SkillKit 包管理器，它支持 44+ 种 AI 编程工具，提供超过 15,000 个预置 Skill。

npm install -g skillkit
npx skillkit@latest search "pdf"  # 搜索 PDF 相关 Skill

8.2 安装开源 Skill

方法一：npx skills add（推荐）

# 添加指定仓库的 Skill
npx skills add anthropics/skills

# 添加特定 Skill
npx skills add vercel-labs/agent-skills --skill pdf-analyzer

方法二：Git 克隆

cd .trae/skills/
git clone https://github.com/anthropics/skills.git

方法三：手动下载

1. 从 GitHub 下载 Skill 文件夹
2. 解压到 .trae/skills/<skill-name>/
3. 确保目录结构正确（包含 SKILL.md 文件）

8.3 验证安装

在 Trae 中检查 Skill 是否被识别：

1. 打开 Trae 设置 → “规则和技能”
2. 查看技能列表，确认已安装的 Skill 出现
3. 检查元数据（名称、描述）是否正确显示
   

8.4 使用开源 Skill

安装完成后，在对话中直接使用：

使用 pdf-analyzer 分析这份合同文件

Trae 会自动匹配 description 字段，加载该 Skill 的完整指令并执行任务。

8.5 常见开源 Skill 推荐

Skill 名称	来源	功能
vercel-labs/agent-skills	Vercel	Vercel 部署、环境配置等
anthropics/skills	Anthropic	官方示例库，含 DOCX/PDF/PPTX/XLSX 处理技能
react-best-practices	skills.sh	React 代码审查和最佳实践（32.3k+ 安装）
web-design-guidelines	skills.sh	Web 设计规范指导（24.5k+ 安装）

---

九、总结

要素	关键点
通用规范	Agent Skills 开放标准，SKILL.md + 可选目录，三层渐进式披露
Trae 实现	完整兼容通用规范，支持项目级和用户级两种范围
简易 Skill	只需一个 SKILL.md 文件，适合指令型任务
通用 Skill	完整目录结构（scripts/references/assets），适合复杂任务
开源 Skill	通过 skills.sh、GitHub、SkillKit 获取，npx 一键安装
最佳实践	description 写清楚“做什么+何时用”，SKILL.md 正文保持简洁，详细内容放 references

掌握这套方法论后，你可以：

1. 为团队创建标准化的 Skill 库，统一 AI 协作规范
2. 从开源社区获取高质量 Skill，快速扩展 AI 能力
3. 将自研 Skill 发布到社区，实现跨平台复用