本文为「Agent Skills 开发实战」系列第 7 篇，承接前文四层排错体系与需求分析 Skill 实战，全内容经 Trae/OpenClaw 双平台实测验证，小白可直接照搬落地。

一、开篇直击痛点：你写的 Skill，是不是换平台就直接报废？

不少粉丝看完上一篇需求分析 Skill 实战教程，私信我说了同一个高频问题：
自己在 Trae 里写好的 Skill，本地运行稳得一批，输出格式、触发逻辑全正常；原封不动复制到 OpenClaw，直接全面翻车：

• 技能列表一片空白，系统完全识别不到文件夹

• 手动 @能调用，但自然对话永远不会自动触发

• 输出格式乱飘，内置的 PRD 模板被平台规则直接覆盖

• 文件读写、流程执行半路中断，同一段代码两边表现完全不同

很多人翻来覆去用四层排查法自检，单平台文件、触发、优先级、环境全合规，一换平台就出 bug，折腾两三天也找不到根源。

其实核心原因非常简单：

Trae 和 OpenClaw 看似都遵循 SKILL.md 通用标准，实则在目录规则、元数据解析、专属语法、系统权限上藏了大量私有差异。新手写 Skill 一不小心混入平台专属代码，直接就丧失了可移植性。

本篇结合我踩过的 12 个兼容坑，整理出一套零修改跨平台通用 Skill 开发规范，一套文件夹复制到 Trae、OpenClaw 都能稳定运行。全文保姆级分步讲解，附通用 SKILL.md 模板 + 可直接下载的资源包，小白照着做也能一次成功。

二、先搞懂底层：4 个核心差异，90% 的兼容坑都来自这里

想要实现跨平台通用，必须先摸透两套平台的底层区别，所有失效问题都源于这四点，刚好对应我们系列的四层排查体系：

2.1 目录规则差异

这是新手最容易踩的低级错误，差一个字母技能就直接加载失败。

平台	项目内技能目录	全局共享技能目录	核心区别
Trae	项目根目录 .trae/skills/（带隐藏前缀）	Windows：%userprofile%/.trae/skills Mac/Linux：~/.trae/skills	技能包裹在.trae隐藏文件夹内
OpenClaw	项目根目录 skills/（无隐藏前缀）	Mac/Linux/WSL：~/.openclaw/skills	技能直接裸放根目录，无额外隐藏层

踩坑提醒：直接把 Trae 项目的.trae文件夹复制到 OpenClaw，OpenClaw 无法识别隐藏前缀目录，技能会彻底加载失败。

2.2 元数据解析差异

两套平台对 YAML 头部字段的兼容度完全不同：

• Trae 仅兼容通用三字段：name、version、description，额外私有字段会直接解析失败，技能消失；

• OpenClaw 支持拓展私有字段：requires、bins、env，用于声明脚本依赖、工具调用。

兼容红线：通用 Skill 的 YAML 头部，只允许保留 3 个通用基础字段，绝对不能写入 OpenClaw 专属配置。

2.3 执行语法差异

• Trae 独有 ! 行内命令语法，可一键读取本地 Git 日志、项目文件内容；

• OpenClaw 完全不识别!特殊标记，会直接当作普通文本输出，整套工作流直接失效。

通用原则：纯业务 Skill 全程用自然文本描述工作流，不嵌入任何平台专属终端命令。

2.4 系统权限差异

1. 路径分隔符：Windows 反斜杠\仅 Trae 原生兼容，OpenClaw（WSL/Mac）仅识别正斜杠/；

1. 编码要求：两套平台统一要求 UTF-8 无 BOM，GBK、带 BOM 编码会出现解析乱码；

1. 脚本支持：OpenClaw Windows 原生环境不支持批量脚本，仅 WSL 完整适配；Trae Windows 原生完整支持文件读写。

三、必守 6 条铁律：写出零修改双平台通用 Skill

严格遵守以下 6 条通用开发规范，写出的技能一套文件夹双向复制，Trae、OpenClaw 无需改动任何内容，完美适配四层排查自检标准。

3.1 命名与编码全统一

1. 技能文件夹：全部小写英文 + 连字符，如requirements、code-review，禁止中文、驼峰、大写命名；

1. 核心文件固定命名 SKILL.md，全程大写，大小写敏感系统不会识别失败；

1. 文件编码强制 UTF-8 无 BOM，仅用 VS Code 等纯文本编辑器编写，禁用 Word/WPS；

1. YAML 头部---必须顶格放置，前后不允许存在空行，两套平台解析规则完全一致。

✅ 全平台通用标准头部

yaml --- name: requirements version: 1.0.0 description: 用户新建项目、变更需求、撰写PRD、需求评审时，自动引导生成标准化结构化需求分析文档 ---

❌ 禁止错误写法

yaml --- name: requirements version: 1.0.0 description: xxx需求分析技能 openclaw:   requires: ["python3"] ---

3.2 极简目录结构，不搞平台专属文件夹

通用标准技能目录

Plain Text requirements/ └── SKILL.md

拓展说明：如需存放模板、参考文档，新建templates、references通用文件夹即可，两套平台都能正常读取；绝对禁止创建.trae、.openclaw私有配置目录，会造成另一平台无法识别。

3.3 纯文本工作流，舍弃所有平台专属语法

1. 禁用 Trae 专属!文件读取、Git 命令语法；

1. 不写入 OpenClaw 专属脚本依赖声明、CLI 执行指令；

1. 所有业务流程只用自然文字描述执行步骤，不嵌入终端、Shell、Python 代码。

划重点：我们上一篇的三段式需求分析流程，全程纯文字引导，天然满足全平台兼容标准，可直接复用。

3.4 通用化触发描述，双平台自动触发率拉满

两套 AI 解析 description 关键词的逻辑略有区别，通用写法固定结构：前置使用场景 + 后置口语化关键词，不依赖平台私有触发配置，仅靠自然文本匹配。

✅ 通用触发段落模板

markdown ## 触发条件 适用场景：新项目立项、需求迭代变更、PRD文档撰写、项目规划、需求评审 用户口语关键词：需求文档、PRD、需求分析、功能规格、起草需求

3.5 统一优先级声明，规避平台内置 Rule 冲突

结合系列第 4 篇的优先级铁律，通用 Skill 统一在文档内写明：本技能输出格式优先级高于全局 Rule。两套平台全局规则识别逻辑完全一致，不会出现输出格式漂移、模板失效问题。

3.6 路径全用正斜杠，跨系统零报错

全程使用./templates/xxx.md这类正斜杠相对路径，杜绝 Windows 反斜杠\，OpenClaw WSL、Mac 系统不会出现路径解析崩溃。

四、手把手部署：Trae/OpenClaw 双平台分步操作

4.1 方式一：项目内部署

Trae 项目部署步骤

1. 在项目根目录新建.trae隐藏文件夹；

1. 内部创建skills文件夹；

1. 放入完整requirements技能包，重启 Trae 客户端即可加载。

OpenClaw 项目部署步骤

1. 项目根目录直接新建skills文件夹（无需隐藏前缀）；

1. 放入和 Trae 完全相同的requirements技能文件夹；

1. 重启 OpenClaw 客户端，工作区技能优先级最高，自动识别生效。

4.2 方式二：全局共享部署

1. Trae 全局路径：Windows %userprofile%/.trae/skills、Mac/Linux ~/.trae/skills

1. OpenClaw 全局路径：Mac/Linux/WSL ~/.openclaw/skills

1. 把同一套技能文件夹复制到两个全局目录，新建项目无需重复导入。

📌 关键优先级提醒

• OpenClaw：工作区 skills > 全局 skills > 软件内置捆绑技能

• Trae：项目.trae/skills > 全局.trae/skills

两套平台统一遵循项目内技能优先级高于全局，修改项目内 Skill 不会污染全局配置。

五、四层自检法：10 分钟定位所有兼容问题

部署完成后，分别在 Trae、OpenClaw 双环境测试，严格按照四层顺序自检，快速定位所有兼容 bug，和系列前文排错逻辑完全统一：

第一层：文件层兼容校验

1. 文件夹名、SKILL.md 大小写、命名完全合规；

1. YAML 头部仅保留 name/version/description，无平台私有字段、无空行；

1. 文件编码 UTF-8，所有资源路径统一正斜杠；
   ✅ 校验标准：两套平台技能列表均可正常显示该技能。

第二层：触发层兼容校验

1. 手动 @技能名，Trae、OpenClaw 都能正常调用；

1. 自然口语提问，两边均可自动识别触发；
   ✅ 校验标准：不存在单边自动触发、另一边只能手动调用的情况。

第三层：优先级层兼容校验

1. 两套平台运行时，技能内置输出模板均能覆盖全局 Rule；

1. 三段式工作流执行顺序完全一致，不会出现单边流程截断；
   ✅ 校验标准：同一提问输入，Trae、OpenClaw 输出的 PRD 文档结构、格式完全相同。

第四层：环境层兼容校验

1. Windows 端 Trae 完整执行无报错；

1. Mac/WSL 环境 OpenClaw 流程完整运行，无路径、脚本报错；
   ✅ 校验标准：纯文本通用 Skill 全操作系统零异常，不依赖任何本地程序、脚本。

六、避坑指南：新手跨平台最容易踩的 5 个致命坑

坑 1：SKILL.md 写入 OpenClaw 专属 requires 配置

后果：Trae 直接解析失败，技能在列表完全消失；
解决方案：通用技能仅保留 3 个基础元数据字段，删除所有平台私有拓展配置。

坑 2：直接复制 Trae 的.trae 文件夹给 OpenClaw

后果：OpenClaw 识别不到技能文件夹，完全加载失败；
解决方案：OpenClaw 项目直接新建裸skills目录，单独放入技能包，不要复制隐藏文件夹。

坑 3：使用 Trae 专属！文件读取语法

后果：OpenClaw 把特殊标记当成普通文字，完整工作流直接失效；
解决方案：通用技能全程纯文字描述步骤，不嵌入任何终端命令。

坑 4：路径使用 Windows 反斜杠 \\

后果：OpenClaw WSL、Mac 系统路径解析崩溃，模板文件读取失败；
解决方案：全部统一使用./正斜杠书写相对资源路径。

坑 5：技能文件夹使用中文、大写、驼峰命名

后果：Mac/Linux 大小写敏感系统加载异常，单边识别失败；
解决方案：统一小写英文 + 连字符命名技能目录，和 name 字段保持一致。

七、拿来即用：通用版需求分析 Skill 完整源码

完全兼容 Trae+OpenClaw，无任何平台私有语法，直接复制保存为 SKILL.md 即可使用，一套复制两边部署：

markdown --- name: requirements version: 1.0.0 description: 用户新建项目、需求变更、编写PRD、需求评审时，引导完成标准化需求分析文档，输出规范Markdown PRD --- ## 触发条件 适用场景：新项目开发、需求迭代更新、产品规划、需求评审 触发关键词：PRD、需求文档、需求分析、功能规格、起草需求 ## 工作模式 提供标准三段式流程/自由快速输出两种模式，由用户自主选择 ### 阶段1 上下文收集 1. 收集项目名称、业务目标、受众、工期、技术约束7项基础信息 2. 引导用户倾倒全部业务背景、功能构想、限制条件 3. 根据信息缺口生成澄清问题，补齐信息盲区 ### 阶段2 结构化文档生成 内置6大标准章节：项目概述、功能需求、非功能需求、技术规格、约束、输出规范 逐章节执行提问→头脑风暴→筛选→起草→迭代优化，自动生成requirements.md ### 阶段3 读者自测校验 引导新开空白对话验证文档，修正歧义、逻辑矛盾 ## 固定输出规范 本技能输出格式优先级高于全局Rule，统一使用标准编号FR/NFR，固定Markdown结构 ## 需求文档固定模板 ### 项目概述 项目名称：XXX 项目描述：一句话业务定位 项目目标：可量化业务价值 ### 功能需求 FR-编号：功能描述、适用角色、触发场景 ### 非功能需求 NFR-编号：性能/安全/兼容性量化指标+测试标准 ### 技术规格 前后端、API技术选型规范 ### 约束条件 工期、预算、合规硬性限制 ### 输出要求 带目录、唯一需求编号，支持导出PDF ## 引导容错规则 1. 用户想跳过阶段，提供简化流程选项； 2. 遇到未知业务术语主动提问，不自行脑补； 3. 文档质量优先，拒绝敷衍简略输出

八、资源下载 & 系列回顾

📦 配套资源

资源获取：文章最上方【资源下载】区，一键下载全套通用技能文件夹。

📚 系列文章回顾

本系列从入门到实战全链路打通，建议按顺序学习：

1、《一文读懂 Agent Skills》：核心认知入门

2、《5 分钟上手：写第一个 Hello World Skill》：零基础实操

3、《SKILL.md 文件结构拆解》：底层规范吃透

4、《Prompt、Rule、Skill 区别一篇讲透》：厘清优先级逻辑

5、《为什么你的 Skill 总是不生效？四层排查法》：系统化故障排错

6、《保姆级实战：需求分析 Skill 开箱即用》：完整业务技能落地

九、结尾 & 下期预告

本篇我们彻底搞定了 Skill 跨平台复用的底层规范，不用再为不同平台重复编写两套代码，一套标准技能就能实现 Trae、OpenClaw 全平台通用，彻底解决了兼容失效的痛点。

很多新手朋友反馈，就算掌握了开发规范，从零搭建一套完整可用的业务 Skill 还是要踩不少坑、花大量时间调试。为了帮大家直接落地拿结果，下一篇我们进入系列第 8 周，直接给大家开源分享 2 个高频场景的核心 Skill 模板。

下期文章：《直接复制用：2 个核心 Skill 模板开源分享》 我会把经过多平台实测、稳定可用的 2 套核心业务 Skill 完整开源出来：一套是我们一直在讲的标准化需求分析 Skill，另一套是产品高频使用的Skill。两套模板都严格遵循跨平台通用规范，下载后复制到对应目录就能直接触发使用，不用再从零搭建、反复调试，拿来就能落地到日常工作里提效。

互动话题：
部署过程中遇到任何问题，或者有其他想了解的 Agent Skill 开发技巧，都可以在评论区留言，我都会一一回复。

如果这篇文章帮你省下了踩坑的时间，欢迎点赞👍+ 收藏⭐+ 关注➕，你的支持是我持续更新的最大动力！