skills

关于 Skill 的一些知识点

陈鑫杰

目的：深入了解 AI 助手的 Skill 系统，掌握技能的导入、冲突处理与全生命周期管理

一、Skills 简单介绍

在 AI 助手生态中，Skill（技能） 是一种模块化的能力扩展单元。它允许 AI 助手在不修改核心代码的前提下，通过加载独立的技能描述文件来获得特定领域的专业知识和操作能力。每个 Skill 本质上是一个包含 SKILL.md 文件的目录，其中定义了技能的名称、描述、触发条件、执行流程和辅助脚本。

Skill 的核心结构

一个标准的 Skill 目录结构如下：

1
2
3
4
5
6
7
8
9

my-skill/
├── SKILL.md          # 核心描述文件（必需）
├── scripts/          # 辅助脚本目录（可选）
│   ├── helper.sh
│   └── process.py
├── config/           # 配置文件目录（可选）
│   └── config.json
└── assets/           # 静态资源目录（可选）
    └── template.html

其中 SKILL.md 是每个 Skill 的核心文件，采用 Markdown 格式编写，包含两个主要部分：

Frontmatter（元数据）

位于文件顶部，使用 YAML 格式定义技能的基本信息：

1
2
3
4

---
name: "my-skill"
description: "技能的简要描述，用于触发匹配"
---

正文（执行指南）

Frontmatter 下方的 Markdown 内容是技能的详细说明，包括功能概述、触发条件、执行流程、注意事项等。AI 助手在匹配到某个 Skill 后，会读取正文中的指令来执行具体任务。

Skill 的工作原理

当用户向 AI 助手发送请求时，助手会根据以下机制匹配并激活相应的 Skill：

  1. 关键词匹配 — AI 助手分析用户输入中的关键词，与所有已加载 Skill 的 description 字段进行比对。当匹配度达到阈值时，该 Skill 被标记为候选。
  2. 上下文推理 — 除了关键词，AI 还会结合对话上下文、当前工作目录、文件类型等信息，推断用户意图是否与某个 Skill 的触发条件吻合。
  3. 加载执行 — 匹配成功后，AI 助手加载该 Skill 的 SKILL.md 全文，按照其中定义的执行流程调用辅助脚本或执行操作，最终返回结果。

核心要点：Skill 的设计理念是声明式能力扩展：开发者只需编写 Markdown 描述文件，无需修改 AI 助手的核心代码，即可为其添加新的专业能力。这使得 Skill 具备良好的可移植性、可分享性和可组合性。

二、当前目录下的 Skills 总结

当前项目的 .trae/skills/ 目录下共有 164 个 Skill，涵盖了设计系统、开发工具、AI 本地模型、文档生成、支付集成等多个领域。以下是按功能类别的详细统计与分析。

指标 数值
Skill 总数 164
功能类别 4
设计系统 Skill 74
Skill 管理工具 5

类别分布

类别 数量 占比
设计系统类（design-*） 74 45.1%
开发工具类 39 23.8%
TRAE 内置功能类（TRAE-*） 4 2.4%
其他类 47 28.7%
合计 164 100%

各类别详细说明

设计系统类（74 个，占 45.1%）

这是数量最多的类别，来源于 awesome-design-md 仓库的导入。每个 Skill 对应一个知名品牌的设计系统，包含完整的颜色令牌、字体规范、间距系统和组件规范。当用户要求生成符合特定品牌风格的 UI 时，对应的 Skill 会被激活。

代表性 Skill 包括：design-apple、design-stripe、design-vercel、design-tesla、design-figma、design-nvidia 等，覆盖了科技、金融、汽车、消费、媒体等多个行业的品牌。

开发工具类（39 个，占 23.8%）

涵盖前端开发、测试、版本控制、代码质量、动画框架等开发者日常使用的工具型 Skill。其中包含一套完整的 Skill 生命周期管理工具链（5 个），以及 Chrome 扩展开发工具链（5 个）、HyperFrames 视频创作工具链（5 个）等。

子类别 数量 代表性 Skill
Skill 管理 5 skill-creator, skill-remote-import, skill-local-sync, skill-analyze-reorganize, skill-distribute-deploy
Chrome 扩展开发 5 chrome-extension-dev-workflow, chrome-extension-policy-checker, chrome-i18n
动画/交互框架 5 gsap, hyperframes, hyperframes-cli, hyperframes-media
前端/UI 开发 4 frontend-design, shadcn, dynamic-ui, web-design-guidelines
测试工具 3 test-driven-development, webapp-testing, extension-test-runner
React 生态 3 react-best-practices, react-native-skills, composition-patterns
其他开发工具 14 git-commit, gh-cli, mcp-builder, electron, claude-api 等

TRAE 内置功能类（4 个，占 2.4%）

Trae Work 平台自带的核心功能 Skill，提供浏览器自动化、计算机操作和代码模式编排等能力：

  • TRAE-browseruse — 内置浏览器自动化，支持页面导航、元素交互、截图等
  • TRAE-browseruse-external — 外部 Chrome 浏览器控制
  • TRAE-computer-use — macOS 桌面自动化，通过 Accessibility API 控制原生应用
  • TRAE-code-mode-orchestrator — 代码模式编排器，在隔离运行时中执行 JavaScript

其他类（47 个，占 28.7%）

包含文档生成（pdf、docx、xlsx、pptx）、本地 AI 模型（local-tts、local-txt2img、local-asr 等 10 个 Intel AIPC 本地推理 Skill）、支付集成（alipay-payment-integration、douyinpay-payment-integration）、知识管理（notion-cli、obsidian-cli 等）、内容创作与分析等多元化能力。

三、什么是 Skills 冲突

当多个 Skill 的功能范围产生重叠，或者两个 Skill 拥有相同或高度相似的名称时，就会发生 Skills 冲突。冲突会导致 AI 助手在匹配用户意图时产生歧义，可能激活错误的 Skill，或因重复加载而浪费上下文窗口。

冲突的主要类型

类型一：命名冲突

当两个 Skill 的目录名或 name 字段完全相同或高度相似时发生。这是最常见的冲突类型，通常在以下场景中出现：

  • 跨来源导入：从不同 AI 服务（如 Claude 和 Cursor）同步了同名 Skill
  • 远程仓库导入：远程仓库中包含与本地已有 Skill 同名的目录
  • 大小写差异：SKILL.md 与 skill.md 在不区分大小写的文件系统上可能造成混淆

实际案例：在本次实践中，从 Trae 用户级目录同步时产生了 skill-creator_trae-user（同步时自动添加后缀），与已存在的 skill-creator 形成命名冲突。类似地，TRAE-computer-use-ptc 与 TRAE-computer-use、agent-browser 与 TRAE-browseruse 也是功能重叠导致的冲突。

类型二：功能冲突

两个 Skill 虽然名称不同，但核心功能高度重叠。例如 frontend-skill 和 frontend-design 都提供前端 UI 生成能力，用户输入”帮我设计一个页面”时，AI 助手难以判断应该激活哪一个。功能冲突不会报错，但会降低匹配精度，导致用户体验下降。

类型三：触发条件冲突

多个 Skill 的 description 字段包含相同的关键词，导致 AI 助手在解析用户意图时产生歧义。例如，如果两个 Skill 的描述都包含”生成图片”，当用户说”帮我生成一张图片”时，助手无法区分应该使用 local-txt2img（本地文生图）还是 byted-seedream-image-generate（云端文生图）。

冲突的影响

影响维度 说明
匹配歧义 AI 助手可能激活错误的 Skill，导致输出结果与用户预期不符
上下文浪费 重复的 Skill 占用上下文窗口空间，减少可用于实际任务的有效 token 数量
维护困难 重复 Skill 的内容可能不一致，更新时容易遗漏，导致行为不一致
命名混乱 带时间戳后缀的冲突 Skill（如 my-skill_20260808_153000）可读性差，难以管理

四、如何解决 Skills 冲突

解决 Skills 冲突需要一套系统化的方法，涵盖预防、检测、合并和重命名四个环节。以下是完整的冲突解决策略。

策略一：导入时自动重命名（预防）

在导入或同步 Skill 时，如果检测到目标目录已存在同名 Skill，自动为新导入的 Skill 添加后缀标识，避免直接覆盖。这是第一道防线：

冲突来源 命名规则 示例
远程仓库导入 添加时间戳后缀 my-skill → my-skill_20260808_153000
本地服务同步 添加来源标识后缀 code-reviewer → code-reviewer_claude
后缀仍冲突 追加时间戳 code-reviewer_claude_20260808_153000
时间戳仍冲突 追加序号 my-skill_20260808_153000_1

策略二：相似度分析（检测）

自动重命名虽然避免了覆盖，但产生了大量带后缀的重复 Skill。需要通过多维度相似度分析来识别哪些 Skill 是真正的功能重复：

分析维度 分析方法 权重
名称相似度 编辑距离 + 前缀/后缀匹配 20%
描述相似度 关键词重合度 + 语义比对 30%
功能相似度 正文核心功能段比对 30%
结构相似度 文件结构、脚本数量比对 20%

判定标准：总分 ≥ 80% 判定为高度相似，建议合并；50%–80% 为部分相似，需人工确认；< 50% 为差异显著，建议语义化重命名。

策略三：相似合并（消除）

对于判定为高度相似的 Skill 组，执行合并操作。合并流程如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

检测到相似 Skill 组
        │
        ▼
  选择基准 Skill ←── description 最完整?
        │          ←── 正文最详尽?
        │          ←── 辅助脚本最多?
        │          ←── 目录名最规范?
        ▼
  复制独有脚本到基准目录
        │
        ▼
  追加独有内容到基准 SKILL.md
        │
        ▼
  在 SKILL.md 末尾记录合并来源
        │
        ▼
  删除被合并的 Skill 目录
        │
        ▼
     合并完成

策略四：语义化重命名（规范化）

对于差异显著但名称不规范的 Skill（如 unnamed_skill、带时间戳后缀的 Skill），根据其核心功能进行语义化重命名，采用 领域-用途 格式：

重命名前 重命名后 依据
unnamed_skill business-lookup 正文内容为企业信息查询工具
my-skill_20260808_153000 frontend-linting 正文内容为前端代码检查
code-reviewer_claude code-quality-review 正文内容为代码质量审查

最佳实践：在执行合并和重命名操作前，务必先创建完整备份。合并脚本会自动在 .trae/skills/ 同级目录下创建 skills_backup_<timestamp>/ 备份。重命名时会同步更新 SKILL.md 中 frontmatter 的 name 字段，确保元数据与目录名一致。

五、本地实际操作

本项目的 .trae/skills/ 目录中部署了一套完整的 Skill 生命周期管理工具链，包含四个核心管理 Skill，覆盖了从导入、同步、分析重组到分发部署的完整流程。

工具链总览

1
2
3
4
5
6
7

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│     导入阶段         │     │     整理阶段         │     │     部署阶段         │
│                     │     │                     │     │                     │
│ skill-remote-import │     │                     │     │                     │
│ skill-local-sync    │────▶│ skill-analyze-      │────▶│ skill-distribute-   │
│                     │     │ reorganize          │     │ deploy              │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘

操作一：远程仓库导入

skill-remote-import 用于从 GitHub/GitLab/Gitee 等远程仓库克隆并提取 Skills。当用户粘贴仓库链接并要求导入时，该 Skill 会自动激活。

使用示例

1
2
3
4

# 从 GitHub 仓库导入 Skills
bash .trae/skills/skill-remote-import/scripts/import_remote_skills.sh \
  "https://github.com/VoltAgent/awesome-design-md.git" \
  ".trae/skills"

执行流程：克隆仓库（git clone --depth 1）→ 搜索所有 SKILL.md 文件 → 逐个提取 Skill 目录 → 冲突时添加时间戳后缀 → 输出导入报告。

实际成果：使用此工具从 awesome-design-md 仓库成功导入了 74 个品牌设计系统 Skill，包括 Apple、Stripe、Vercel、Tesla 等知名品牌的设计规范。导入过程中无命名冲突，所有 Skill 直接以品牌名命名（如 design-apple）。

操作二：本地服务同步

skill-local-sync 扫描本地已安装的 AI 服务（Trae、Claude Code、Cursor 等）的全局 Skills 目录，将完整 Skills 仓库拷贝至当前项目。

已知服务路径

服务名称 全局 Skills 路径
Trae（内置） ~/.trae-cn/builtin/global/skills/
Trae（用户级） ~/.trae-cn/skills/
Claude Code ~/.claude/skills/
Cursor ~/.cursor/skills/
Continue ~/.continue/skills/
Windsurf ~/.codeium/windsurf/skills/

使用示例

1
2
3
4
5
6
7

# 先扫描可用的本地来源
bash .trae/skills/skill-local-sync/scripts/sync_local_skills.sh --scan

# 从 Trae 用户级目录同步
bash .trae/skills/skill-local-sync/scripts/sync_local_skills.sh \
  --source "$HOME/.trae-cn/skills" \
  --target ".trae/skills"

冲突处理：同步时如果目标目录已存在同名 Skill，会自动添加来源标识后缀。例如从 Claude 同步的 skill-creator 会被重命名为 skill-creator_claude，避免覆盖原有内容。

操作三：分析与重组

skill-analyze-reorganize 是冲突解决的核心工具，提供扫描分析、相似合并和语义化重命名三种操作模式。

扫描分析

1
2
3

# 扫描所有 Skill 并输出分析报告
bash .trae/skills/skill-analyze-reorganize/scripts/analyze_skills.sh \
  --scan .trae/skills

输出每个 Skill 的 name、description、文件统计、正文摘要，以及基于名称前缀的相似度初步检测结果。

相似合并

1
2
3
4

# 合并 skill-creator_trae-user 到 skill-creator
bash .trae/skills/skill-analyze-reorganize/scripts/analyze_skills.sh \
  --merge skill-creator skill-creator_trae-user \
  --target .trae/skills

合并时会自动备份，将独有脚本复制到基准目录，在 SKILL.md 中追加合并来源记录，然后删除被合并的目录。

语义化重命名

1
2
3
4

# 重命名 unnamed_skill 为 business-lookup
bash .trae/skills/skill-analyze-reorganize/scripts/analyze_skills.sh \
  --rename unnamed_skill business-lookup \
  --target .trae/skills

本次实践成果

在本次 Skill 重组实践中，共执行了以下操作：

操作 详情 结果
合并 A skill-creator_trae-user → skill-creator 9 个脚本已合并
合并 B TRAE-computer-use-ptc → TRAE-computer-use 完成
合并 C agent-browser → TRAE-browseruse 完成
合并 D frontend-skill → frontend-design 完成
重命名 unnamed_skill → business-lookup name 字段已同步

重组前后数据变化：Skill 总数从 168 个减少至 164 个（减少 4 个被合并的重复 Skill），所有基准 Skill 均已追加合并来源记录，完整备份保存在 skills_backup_20260808_230216/ 目录中。

操作四：分发部署

skill-distribute-deploy 将整理完成的 Skills 批量部署到本地各 AI 服务的全局 Skills 目录，确保所有服务均可使用统一、最新的技能集。

使用示例

1
2
3
4
5
6
7
8
9
10
11

# 验证源目录中的 Skills 有效性
bash .trae/skills/skill-distribute-deploy/scripts/distribute_skills.sh \
  --validate

# 执行批量分发（带日志）
bash .trae/skills/skill-distribute-deploy/scripts/distribute_skills.sh \
  --distribute --log

# 验证分发结果
bash .trae/skills/skill-distribute-deploy/scripts/distribute_skills.sh \
  --verify

分发逻辑支持配置化管理：通过 config/distribute_paths.json 定义目标路径列表，支持 overwrite（是否覆盖）、skip_identical（跳过相同内容）、create_target_dir（自动创建目标目录）等选项。分发时会自动跳过备份目录和隐藏目录。

完整工作流总结

Skill 管理闭环：整个 Skill 管理工具链形成了一个完整的闭环：导入/同步（获取外部 Skill）→ 分析重组（去重、合并、重命名）→ 分发部署（同步到各 AI 服务）。这个闭环确保了 Skill 仓库的整洁性、一致性和可用性，是 AI 助手能力管理的基础设施。

参考来源

  1. VoltAgent, awesome-design-md. 74 个品牌设计系统 Markdown 文档仓库. https://github.com/VoltAgent/awesome-design-md
  2. Trae Work 官方文档. Skill 系统设计与 SKILL.md 规范.（项目内置文档）
  3. 本项目 .trae/skills/ 目录. 164 个 Skill 的实际目录结构与 SKILL.md 内容.（本地项目文件）
  4. skill-analyze-reorganize SKILL.md. Skill 智能分析与重组工具的设计文档.（本地项目文件）