企业官网建设流程全解析

如果你用过 AI 编程工具，大概率经历过这样的场景：每次想让 AI 帮忙完成某类固定任务，都得把规则从头到尾说一遍——代码要什么风格、注释怎么写、输出格式是什么样、有哪些必须避开的坑。刚开始还行，用得多了你会发现，同一套提示词反复重复，稍微漏掉一句，AI 给出的结果就跑偏。Trae 里的 Skill 就是专门解决这个问题的。它把一套完整的指令、上下文和参考文件打包成一个可复用的能力单元，配置一次之后，后续只要在对话里触发对应的描述，AI 就会自动套用这套规则。这篇文章我会从零开始讲清楚 Skill 是什么、目录结构长什么样、配置文件怎么写，然后带着你手把手创建并测试一个能真正落地的 Skill，最后再分享几个我在实际项目中用到的高频场景和踩坑记录。无论你是刚开始用 Trae 的新手，还是已经基于它写过一段时间代码的开发者，这篇教程都能让你少走不少弯路。

1. 先想明白：Skill 到底在解决什么问题

1.1 没有 Skill 的时候，AI 协作有多痛苦

先说个我自己的真实体感。前阵子我在某个跨平台项目里做代码审查，代码量不大，但涉及多个服务端模块，风格要求还不一样。最开始的做法是每轮对话里都花几百字写清楚：审查维度、优先级定义、输出格式、哪些模块需要特别关注。第一轮 AI 表现确实不错，但第二轮换了个新对话之后，我又得重新把这些内容敲一遍。更麻烦的是，不同时间写出来的规则文本不可能完全一致，今天强调了安全优先，明天可能漏了这条约束，AI 的行为就会跟着飘。

这个问题不是个例。凡是你需要 AI 反复处理的固定流程，都会遇到类似的重复劳动。比如生成单元测试、写提交信息、整理代码变更说明、输出固定模板的技术文档，本质上是同一个套路，只是每次的输入数据和场景细节不同。规则集本身是稳定的，却不被复用，这是最明显的效率损失。

1.2 Skill 的工作原理：把能力封装成文件

Skill 的核心思路很朴素：把一套稳定的指令和规则，固化成一个文件夹里的结构化文件，AI 在需要的时候自动读取并应用。

我习惯把它类比成“给 AI 写岗位说明书”。你招一个实习生，肯定不会每次布置任务都把公司规范从头念一遍，而是先给一本员工手册，然后说“按手册来”。Skill 就是那本手册：里面写了这个角色是谁、要干什么、按什么标准干活、不能干什么。对话时你不需要重复这些内容，AI 会根据 Skill 的描述（description）判断当前任务是否需要调用它，需要的时候就加载对应文件里的规则开始工作。

这个机制带来的直接好处有两个。第一是规则的一致性：同一个 Skill 无论被调用多少次，里面的约束是完全一样的，不会再出现这次忘了说“禁止修改业务代码”之类的疏漏。第二是上下文的稳定性：Skill 可以把额外参考文件、脚本工具一起打包，复杂任务的执行不再依赖你在对话中临场补充的各种碎片信息。

1.3 什么场景适合用，什么场景不该用

Skill 不是万能的，立项之前先判断场景是否合适，能避免不少投入打水漂的情况。

适合做成 Skill 的任务，通常具备三个特征：规则稳定、频率较高、结果有明确预期。代码审查、单测生成、提交信息规范、文档模板输出、代码结构分析，都属于典型场景。这些任务的核心约束长期不变，变的只是输入代码或业务上下文，非常适合封装。

不适合的场景也有三类。第一类是一次性探索型任务，比如你没接触过某类技术方案，想让 AI 帮你头脑风暴一下，这类对话本就需要自由发挥，套上固定规则反而限制思路。第二类是强依赖实时信息的任务，比如读取最新版本的第三方 API 文档，Skill 里的内容是静态的，无法保证时效。第三类是规则本身还不确定的任务，如果你连自己想要的输出标准都没想清楚，写出来的 Skill 大概率也是反复返工。

说到这你会发现，Skill 真正的价值不是把简单的事变复杂，而是把你已经想清楚的流程固化下来，减少每一次对话中的规则沟通成本。想明白这点，后面学配置的时候就不会一头雾水。

2. 动手前必须搞懂的：Skill 的目录结构和配置语法

2.1 Skill 目录结构：一个文件夹就是一个完整技能

Trae 的 Skill 本质上就是一个目录，目录名就是技能名，目录内部按约定组织文件。常见结构如下：

my-skill/ ├── SKILL.md ├── scripts/ │ └── analyze.py └── resources/ ├── template.md └── style-guide.md

我来逐一说下每个部分的作用。

SKILL.md 是技能的主文件，包含两个部分：开头的 YAML 元信息和后面的 Markdown 正文。YAML 元信息里声明技能的名称和触发描述，Markdown 正文里写希望 AI 遵循的具体规则。这个文件是 Skill 的核心，缺了它整个目录不会被识别。

scripts 目录用来放辅助脚本。某些任务光靠 AI 的推理能力不够，比如要遍历项目文件、做静态检查、跑测试用例，这时候可以让 AI 调用 Python 或 Shell 脚本来完成实际计算。脚本不是必须的，但加上之后能扩展 Skill 的能力边界，后面我会有实际例子。

resources 目录放参考资源，比如项目规范文档、输出模板、代码示例。AI 在执行任务时可以把这些文件作为背景知识读取，避免你在规则正文里堆砌大量内容。把长文档放在 resources 里引用，比全部塞进 SKILL.md 更清晰，也更利于维护。

关于存放位置，我在当前版本里项目级 Skill 放在项目根目录下的.trae/skills/里，全局 Skill 放在用户目录下的.trae/skills/下。不同版本可能支持路径有细微差别，建议你在设置面板里确认一下当前版本的默认目录。拿不准的话，先放项目级目录最稳，这样只有当前项目会加载，不会影响你其他项目的协作。

2.2 SKILL.md 的 YAML 头：让 AI 知道什么时候该用它

YAML 头是 SKILL.md 的第一部分，放在文件最顶部，用三根短横线包起来。它的作用很关键：AI 不是每次对话都加载所有 Skill，而是先读这些元信息，判断当前任务是否匹配。描述写得越清楚，触发就越准确。

一个典型的 YAML 头长这样：

--- name: code-review-skill description: 对项目代码进行系统审查，检查代码风格一致性、潜在缺陷、安全漏洞和可维护性问题。当用户要求“审查代码”“review 一下代码”“看看这段代码有没有问题”时使用。 version: 1.0.0 ---

字段的解释和注意事项如下：

description 是最值得花心思的字段。我见过不少不生效的 Skill，问题都出在这：描述写得过于宽泛，比如“帮助用户审查代码”，AI 很难判断什么时候该加载，结果就是该触发的时候不触发。正确写法是明确场景描述加触发词的组合，让 AI 在对话进行中一碰到相关请求就能对上号。另外不要在这里堆砌规则细节，description 是触发器，正文才是执行手册，两者别混。

2.3 正文规则怎么写：从说清楚要求到给足上下文

YAML 头写完后，接下来是正文部分。正文用 Markdown 编写，这就是 AI 在任务执行中会实际遵循的指令。

写正文最忌讳的是“一句带过”。比如只写“你是一名资深的代码审查员，请认真审查代码”，AI 确实会认真“演”这个角色，但具体按什么标准查、输出什么样、有哪些红线，全靠临时发挥，结果自然不稳定。我建议正文至少包含四个区块：角色定义、执行流程、输出格式、边界约束。

角色定义告诉 AI 以什么身份做这件事。执行流程是具体步骤，先做什么后做什么，比如先扫变更文件再逐文件分析最后汇总问题。输出格式规定结果长什么样，是列表还是表格，分几个优先级，这些直接关系到你能不能快速用结果。边界约束是不可少的部分，包括不能擅自修改代码、遇到歧义要先提问等。

正文的组织方式也有讲究。用标题划分区块，用清单列出要点，控制每个区块的长度。如果某项规则特别复杂，不要硬塞进正文，可以把详细内容放到 resources 目录，然后在正文里用引用指示 AI 去读取。这样 SKILL.md 本身保持简洁，规则可维护性也更好。

2.4 辅助脚本和资源文件：什么时候需要、怎么放

先说说资源文件。当你的规则里涉及到具体模板、术语表或规范文档时，放 resources 目录是最佳选择。比如说你希望 AI 按公司内部的项目复盘模板生成文档，模板内容很长，直接贴进 SKILL.md 会严重拉低可读性，这时放进resources/review-template.md，然后在正文写“读取 resources/review-template.md 中的模板并严格遵循其结构”即可。

辅助脚本的价值在于补齐 AI 不擅长的事情。AI 擅长理解和生成内容，但在精确遍历文件、解析特定格式、执行计算上，有时不如一个脚本来得可靠。比如你想做全项目范围的 TODO 扫描，AI 逐文件翻找既慢又容易漏，这时候写个 Python 脚本遍历目录，AI 只需获取脚本输出就能继续分析。

放置脚本时的几个约定：脚本文件统一放 scripts 目录，脚本内部尽量处理单一时机，避免逻辑过于庞大导致 AI 难以理解和调用。另外脚本命名要直观，比如scan_todos.py比utils1.py好得多，AI 能通过文件名快速理解脚本职责。写脚本时建议加简要注释说明输入输出格式，实测下来能明显减少 AI 调用脚本时出现的偏差。

3. 保姆级实操：5 步创建你的第一个 Skill

3.1 规划：明确目标和触发场景

为了不空谈理论，我带你完整做一个实际可用的 Skill。下面以“代码审查”为例，因为这是几乎所有项目都会用到的场景，也最容易看出 Skill 带来的效果差异。

先花两分钟把需求想清楚。这个 Skill 要解决什么问题？我希望 AI 在代码合并之前做一轮自动化的质量把关，重点看代码风格是否统一、有没有明显的逻辑缺陷、有没有安全隐患、是否容易维护。输出的结果要能直接指导修改，不能泛泛而谈。然后想触发场景：当我提出“审查代码”“review 一下这段代码”“帮我看看这个改动有没有问题”时，AI 应该自动调用这个技能。

为了避免规则太散，我把它聚焦成一个原则：一次审查只做一件事，输出必须能落地。有了这个规划，后面每个规则的取舍就有依据了。

3.2 搭建目录和初始文件

规划完成后开始搭目录。假设我们在项目根目录下操作，执行下面几条命令：

cd /path/to/your-project mkdir -p .trae/skills/code-review-skill/scripts mkdir -p .trae/skills/code-review-skill/resources touch .trae/skills/code-review-skill/SKILL.md

第一条命令创建技能主目录code-review-skill，同时建好 scripts 和 resources 子目录，最后创建 SKILL.md 文件。目录命名我用code-review-skill，全程小写加连字符，符合 Skill 命名的约定，也能避免跨平台大小写问题。

这时你的目录是这样的：

.trae/skills/code-review-skill/ ├── SKILL.md ├── scripts/ └── resources/

先不用急着写脚本和资源文件，等 SKILL.md 的规则跑通之后，再去补充需要的内容，这样迭代成本最低。

3.3 编写配置文件：完整的 SKILL.md 示例

打开 SKILL.md，写入 YAML 头和正文。我直接给出一个可以复制的完整示例：

--- name: code-review-skill description: 对项目代码进行系统审查，覆盖代码风格、逻辑正确性、安全漏洞和可维护性。当用户要求“审查代码”“review 代码”“检查这段代码有没有问题”时使用。 version: 1.0.0 --- # Code Review Skill 你是一位拥有十年一线研发经验的资深代码审查专家。你的目标是对用户提供的代码进行严谨、结构化、可落地的审查，帮助开发者在提交前发现潜在问题。 ## 执行流程 1. 获取待审查的代码内容。如果用户没有指定范围，默认审查当前对话中最近一次出现的代码块。 2. 先从整体架构角度快速理解代码职责，再逐函数、逐逻辑分支分析问题。 3. 按下面的审查维度逐项检查，确保覆盖完整。 4. 输出审查报告，按严重程度分级列明问题。 ## 审查维度 - 代码风格：是否符合所在语言的主流风格约定，命名是否清晰统一。 - 逻辑正确性：是否存在边界条件遗漏、空值风险、并发问题、资源未释放等情况。 - 安全隐患：是否存在注入、敏感信息硬编码、不安全的输入校验等风险。 - 可维护性：函数是否过长、是否重复代码、是否存在明显的扩展隐患。 ## 输出格式 问题列表使用表格，必须包含以下列：严重程度、文件位置或代码块编号、问题描述、修改建议。严重程度分为三级： - 严重（必须修复后再提交） - 建议（强烈推荐修复） - 提示（可选优化项） 最后用一小段话总结整体质量结论，给出是否建议合并的判断。 ## 边界约束 - 只做审查，不要直接修改用户代码，除非用户明确要求。 - 不要输出与审查无关的内容。 - 如果代码上下文不足，无法判断特定行为，必须在报告中明确标注“待确认”。

这个示例里，我把执行流程、审查维度、输出格式、边界约束都写清楚了。运行后 AI 的输出会高度结构化，而不是自由发挥的散文。你可以复制这个模板，把角色定义和审查维度替换成你自己的业务要求。

3.4 加载与测试：让 Skill 真正跑起来

配置写完后，Skill 还不会自动触发，需要测试验证。在 Trae 的对话窗口里输入一句触发指令，比如：

审查一下这段代码，看看有没有质量问题： def calculate_discount(price, level): if level == "vip": return price * 0.8 else: return price

观察 AI 是否调用了 code-review-skill。判断依据是它的输出结构是否符合 SKILL.md 里定义的表格格式和严重程度分级，如果只是自由回答，说明 Skill 没有被正确加载。

第一次测试跑不通时，先检查三件事。第一，目录是不是放在.trae/skills/下，路径是否写错；第二，SKILL.md 里的 YAML 头是否完整，尤其是开头的---有没有漏掉；第三，description 里有没有包含用户触发时用的那句表达。我的经验里，八成问题出在第一个和第三个。路径不对，Skill 根本没被加载；描述不准确，AI 压根不认为是这类任务。

测试通过后，再刻意试几个边界情况：分别用“review 代码”“看看这段代码”等不同说法触发，确认都能命中。这时候 Skill 的基础稳定性就有了保证。

3.5 迭代优化：第一版效果不好怎么办

几乎没有哪个 Skill 第一版就能完美，别期望一次到位。我用一段时间后通常会发现两类问题。

第一类是输出格式和预期不符，比如表格列太少、结论不清晰。这时直接打开 SKILL.md，在“输出格式”一节补充更明确的约束，比如指定“问题描述必须不超过 50 字”“修改建议必须给出具体的代码片段示意”。规则越具象，输出越稳定。

第二类是触发时机不准。有时候你只是随便问一句“这段代码能跑吗”，它也跑去套审查模板，反而啰嗦。解决办法是在 description 里收紧触发条件，把“当用户明确要求审查代码质量时使用”这类表述写得更严格，而不是任何提到代码的对话都触发。

迭代时建议保留版本记录。每次改动后把 version 升一个小号，方便哪天效果不如旧版时回退。我用一段时间之后回过头看，一个稳定的 Skill 往往经过四五轮这样的迭代，前两轮通常都是在压缩输出篇幅和明确边界条件。

4. 进阶玩法：5 个能直接抄作业的高频场景

4.1 代码审查员：给提交做一次自动化把关

代码审查的场景最常见，我上面给的示例已经可以直接用于实践，这里补充两个提效细节。

一是可以给 Skill 加上对 diff 的处理能力。如果你希望它审查的是工作区改动，而不是整段代码，可以在执行流程里加上一句“优先获取当前分支最近一次提交的 diff 进行增量审查”。这样每次输入少量变更，AI 就能按统一标准输出问题清单，非常适合合并请求前的自查环节。

二是把公司内部的编码规范文档放进 resources 目录，例如resources/style-guide.md，然后在正文里加一行“审查时读取 style-guide.md，凡与该规范冲突的内容一律列为严重问题”。实际效果是，团队规范从墙上的文档变成了可自动执行的检查标准，不再依赖每个人自觉手动对齐。

4.2 单元测试生成器：补测试不再看心情

给项目补单元测试是被反复提起的需求，但 AI 生成的测试经常出现两个毛病：要么只测正常路径，边界分析几乎没有；要么断言写得稀松，跑不跑都能过。Skill 正好可以用规则约束住质量底线。

下面是一个单测生成 Skill 的核心配置：

--- name: unit-test-generator description: 根据指定的函数或模块生成单元测试代码，自动识别项目使用的测试框架并遵循已有测试风格。当用户要求“生成测试”“补测试”“写单测”时使用。 version: 1.0.0 ---

正文里的关键规则有几条：先读取项目里已有测试文件，识别框架和命名习惯；测试用例必须包含正常输入、边界输入和异常输入三组参数；断言不能只做为空判断，要验证实际返回值；生成的测试代码不得修改被测模块逻辑；输出时附上“测试覆盖说明”，列出每条用例检查的目标和理由。

这里我建议放一个辅助脚本，专门生成边界值测试的参数组合。比如一个函数接收整数参数，脚本可以自动列出 0、负数、极大值、None 等情况的输入。AI 只需要基于脚本输出补充测试逻辑，效率和覆盖质量都能上一截。

4.3 Git Commit 信息生成：统一提交规范

如果你所在团队要求提交信息遵循特定格式，每次手写一大堆说明确实心烦。这个 Skill 的配置重点在于规则细化程度。

先把触发描述写成“当用户要求生成提交信息、根据当前改动写 commit message 时使用”。正文里规定执行流程：先获取工作区 diff 和最近几条提交历史，理解改动内容和风格习惯；按 Conventional Commits 规范生成信息；subject 不超过 50 个字符；body 部分解释改动的动机和影响，而不是简单罗列文件名；出现破坏性变更时必须加上对应的标记。

我实际使用时发现，这个 Skill 是团队落地效果最好的一个。因为它把约定变成了模板和流程，同时保留了内容生成的空间，队友不用记住规范里的细枝末节，只需要跑一句对话然后复制结果。

4.4 技术文档写作助手：让 AI 按你的模板输出

很多人让 AI 写文档，结果总是长篇大论却结构混乱。用 Skill 可以把文档结构和表达风格固定下来。

在 resources 目录放一个doc-template.md，里面定义文档的区块：背景、方案说明、变更影响、验证方式、风险与注意事项。SKILL.md 正文里明确要求：按模板结构输出，标题层级必须与模板一致；“背景”部分小于 200 字；“变更影响”必须覆盖兼容性、性能和依赖关系；代码示例必须完整可运行，不允许写“省略”字样的伪代码。

这个 Skill 对维护内部文档尤其有用。原来一份方案文档可能要写一小时，现在输入关键决策点，AI 按模板生成初稿，我再补几个数据就可以发出去了。核心价值不是省时间，而是所有文档的阅读结构统一，后续查找和比对信息时省了大量精力。

4.5 架构评审助手：让 AI 当你的第二思考者

架构评审比代码审查更高一层，它关注的是模块划分、接口设计、依赖方向、扩展性这些宏观问题。这类分析本来就很考验经验，AI 擅长找漏洞，只要规则给得够具体。

我的几条核心规则供参考。第一，从模块复用性、接口稳定性、数据一致性、依赖方向、并发控制、容错能力六个维度展开分析。第二，输出至少包含“发现的问题”“严重程度”“建议方向”三部分。第三，必须区分“确定性问题”和“基于现有信息的推测”，不能含糊带过。第四，当一个模块的职责超过两个时，自动提示将用户考虑拆分重构。

这类 Skill 的效果上限取决于你对业务背景的描述。我在实际使用时，往往在对话里先补充一段项目背景、模块划分和关键链路，再让 AI 执行评审。规则保证了它不会漏维度，背景信息保证了分析不会脱离实际。

5. 踩坑实录：Skill 创建和使用的高频问题速查

5.1 Skill 不生效，AI 完全不理会

这是我遇到最多的问题，原因一般出在几个地方。

第一，目录放错位置。SKILL.md 必须在.trae/skills/下，它自己单独放在某个随意目录是没用的。第二，SKILL.md 文件名大小写不对，必须是全大写，写成skill.md或Skill.md都可能无法识别。第三，YAML 头格式错误，比如开头的---缺失，或者 description 字段写成desc，都会导致读取失败。第四，description 里没有覆盖用户的触发说法。

排查思路很直接：先确认目录路径和文件名，再检查 YAML 头每一项字段名和格式，最后把触发描述里的关键词和你实际说的话对比一遍。用“换个说法测试”的方式，能快速定位到底是加载失败还是触发失败。

5.2 规则被无视，AI 不按套路输出

Skill 加载了，但 AI 偶尔不遵守规则，这是另一个高频烦恼。多数时候不是它故意不听话，而是上下文或对话历史导致指令冲突。

常见原因有这么几种。一是当前对话上下文太长，AI 的注意力窗口有限，SKILL.md 里的规则被后续大量聊天内容淹没，优先级下降。二是用户在同一轮对话里给出了与规则矛盾的明确指令，比如规则要求“不要修改代码”，但你接着又说“顺便帮我改一下”。三是规则里使用了模糊表述，比如“尽量”“通常”这类词，模型会自由裁量。

应对方案也清晰：尽量把单个任务放在干净的对话上下文中执行；当规则与临时指令冲突时，优先让规则保持简洁，把灵活性放在正文末尾的边界约束里；写规则时尽量用“必须”“不得”“禁止”这类确定性词汇，少出现留白空间。

5.3 引用文件失败或读取不到内容

Skill 里用引用文件的方式指向 resources 目录时，偶尔会读取不到。最典型的原因是路径错了。

我在实践中的几条建议：引用文件时使用相对路径，比如resources/style-guide.md，不要用绝对路径，因为 Skill 目录位置可能跨机器迁移；文件编码统一使用 UTF-8，避免中文乱码影响内容读取；在 SKILL.md 里引用时最好同时说明文件用途，而不只是给路径，比如“读取 resources/template.md 中的项目复盘模板，严格遵循其章节结构”。这样即便是自动加载，AI 也清楚该拿文件来干什么。

如果 SKILL.md 本身写得简洁，内容都放到 resources 里，引用文件的成功率会明显提升。因为模型在读取长文件前，先通过你的描述建立了对文件内容的预期，不会盲目抓取或者遗漏关键部分。

5.4 效果忽好忽坏，输出不稳定

同一个 Skill，有时候效果很好有时候很拉胯，这是很多人反馈的问题。排除模型本身的随机性外，多数不稳定来自输入变化和规则粒度不足。

输入变化指的是待处理对象本身的复杂度不同。代码审查一个 50 行的函数，和审查一个 2000 行的服务模块，AI 的深度和耗时会差很多。规则粒度则是说，你的输出要求可以做到多细。如果所有情况下 AI 都尝试用同样的统一格式输出，信息量过大时自然就开始偷懒省略。

我的处理办法是把规则按“输入规模”做分支。比如在审查 Skill 里写：当代码量少于 200 行时，输出完整问题表格；当代码量大于 200 行时，先按模块输出问题汇总，再对“严重”级别问题逐一展开详细说明。这个分支让 AI 在长代码面前不会因为输出篇幅过大而降低质量。

5.5 几个容易忽略的细节

最后分享几个小细节，都是实际使用中碰过壁才长记性的。

Skill 目录名一旦确定，不要频繁改动。因为 description 里的触发词和目录名是两套体系，改目录名不会自动同步触发效果，反而可能造成历史记忆混乱。resources 和 scripts 里的文件也要保持精简，冗杂的文件会让 AI 在自动选择时感到犹豫，加载了错误资源反而拖累执行。另外别在一个 Skill 里塞过多任务目标，我一开始曾试图把代码审查和重构建议揉进同一个 Skill，结果 AI 老是分不清当前该做哪个，后来拆成两个独立 Skill，稳定性立刻好了很多。

还有一条关于版本管理的经验：你的第一个 Skill 会很粗糙，别急着删除重写，先看几轮实际执行结果，基于问题微调规则。它的成长轨迹会比你推倒重来快得多。

根据我个人的经验，Skill 真正上手之后，最大的变化不是省了多少打字时间，而是你处理问题的方式变得更系统了。以前让 AI 干活靠临场发挥，现在你先想清楚流程，再把这个流程固化下来，AI 输出的可预期性会大幅提升。建议你从自己项目中一个反复出现的固定任务开始，哪怕是一个非常小的模板输出，先建一个 Skill 跑起来。只要这个流程跑通，后面的扩展就只是往 resources 里加文件、往正文里加约束的事。至于更复杂的自定义玩法，等你有了三五个 Skill 在手，自然会摸索出适合自己项目节奏的那一套。