Skill 创建与使用最佳实践（以Trae为例）
摘要 Skill是AI助手的模块化能力插件，包含标准化工作流程和领域知识。它采用三层渐进式披露机制（元数据、完整指令、执行层）来优化性能，标准目录结构包括SKILL.md主文件和可选资源目录。Trae完整支持Agent Skills规范，允许项目级和用户级Skill部署，并兼容最小化实现（仅SKILL.md文件）。通用Skill与Trae Skill核心规范一致，区别在于Trae降低了使用门槛。示
文章目录
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 的方案
方案一：直接复制粘贴
-
从 GitHub 或其他来源获取一个符合通用规范的 Skill 文件夹
-
将其完整复制到 Trae 的 skills 目录：
.trae/skills/contract-analyzer/ ├── SKILL.md ├── scripts/ ├── references/ └── assets/ -
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-skillsanthropics/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
方法三：手动下载
- 从 GitHub 下载 Skill 文件夹
- 解压到
.trae/skills/<skill-name>/ - 确保目录结构正确（包含
SKILL.md文件）
8.3 验证安装
在 Trae 中检查 Skill 是否被识别：
- 打开 Trae 设置 → “规则和技能”
- 查看技能列表，确认已安装的 Skill 出现
- 检查元数据（名称、描述）是否正确显示
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 |
掌握这套方法论后，你可以：
- 为团队创建标准化的 Skill 库，统一 AI 协作规范
- 从开源社区获取高质量 Skill，快速扩展 AI 能力
- 将自研 Skill 发布到社区，实现跨平台复用
小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用
更多推荐
5
0- 0
已为社区贡献1条内容
所有评论(0)