企业官网建设流程全解析

1. 为什么"能力"从来不是 Agent 的瓶颈

先把结论摆在前面：我见过太多团队在 Agent 项目上翻车，复盘到最后，几乎没有人是因为"模型不够聪明"而失败的。真正让 Agent 在生产环境里表现拉胯的，是它不知道"在什么情况下该做什么、不该做什么、做完之后怎么判断自己做对了"。这三件事，恰好就是资深工程师脑子里那套看不见的流程。

举个特别典型的场景。你让一个刚入行的工程师去改一个线上 bug，他大概率会直接打开文件、找到可疑的那一行、改掉、提交。而一个干了十年的老工程师会怎么做？他会先看这个 bug 的影响面，确认是不是有回归测试覆盖，改完之后跑一遍相关用例，再检查一下有没有别的调用方受影响，最后才提交。这两者的差距不在"写代码的能力"，而在"流程"。

Agent 现在的情况和那个新人一模一样。你给它一个足够强的模型，它能写出漂亮的代码，但它不知道什么时候该停下来验证，不知道哪些操作是不可逆的，不知道一个改动可能牵连到哪些模块。这就是为什么"把资深工程师的流程写成 skill"这件事，比"换一个更强的模型"要重要得多。

所谓 skill，本质上就是把一段可复用的、带判断逻辑的工作流程，封装成 Agent 可以调用的能力单元。它不是简单的 prompt 模板，也不是一个函数，而是"触发条件 + 执行步骤 + 质量门 + 失败回退"这一整套东西。热词里反复出现的 agent skill、codex skill、skill 插件、skill 脚本，说的都是同一件事：让 Agent 在特定场景下，按照人类专家沉淀下来的方式去干活。

这篇文章我想聊的不是"skill 是什么"这种概念科普，而是我实际把资深工程师流程拆成 skill 的过程中，踩过的坑、总结出的结构、以及那些文档里不会写的判断标准。如果你正在做 agent 开发、agent 框架与编排，或者只是想让自己的 AI coding agent 少犯点低级错误，下面的内容应该能直接用上。

2. 拆解资深工程师的"隐形流程"：从直觉到可执行步骤

2.1 专家流程的三个层次：感知、判断、动作

我一开始尝试写 skill 的时候，犯的最大错误就是直接把"步骤"写下来。比如"修改代码前先跑测试"，听起来很对，但 Agent 执行起来一塌糊涂。后来我才意识到，资深工程师的流程其实分三层，缺一层都不行。

第一层是感知：他得先知道现在是什么情况。是改一个新功能，还是修一个线上问题？代码库有多大？有没有测试？这些信息决定了后面所有动作。第二层是判断：基于感知到的信息，决定走哪条路。有测试就跑测试，没测试就先补一个最小验证。第三层才是动作：具体执行。

我见过的大部分失败的 skill，都只写了第三层。Agent 拿到一个"修改代码"的 skill，它不知道什么时候该用、用了之后怎么判断成功，结果就是机械执行，错得离谱。

所以拆解流程的第一步，不是记录"他做了什么"，而是记录"他在什么信号下做了什么决定"。这个信号，就是 skill 的触发条件。

2.2 把"经验"翻译成"条件判断"的具体方法

这里有个很实用的技巧：找资深工程师做一次"出声思考"（think aloud）。让他一边干活一边把脑子里想的说出来。你会听到大量这样的句子："这里我得小心点，因为……"、"如果这个文件被别的地方引用了，那我就不能直接改"、"先看看有没有现成的工具，没有的话再自己写"。

这些"因为"、"如果"、"先看看"，就是条件判断的原材料。我的做法是拿一张表，左边记他说的话，右边翻译成可执行的条件。

这张表就是 skill 的骨架。你会发现，翻译的过程本身就是一次知识提炼，很多专家自己都没意识到自己在做这些判断，写下来之后才恍然大悟。

2.3 为什么"步骤清单"式的 skill 一定会失败

我早期做过一个"代码审查 skill"，就是把审查清单列了二十条，让 Agent 逐条检查。结果呢？Agent 要么漏掉一半，要么在不该用某条的时候硬套。比如"检查是否有硬编码密钥"这条，在一个纯前端展示组件里根本不需要，但 Agent 还是会去查，浪费大量 token。

问题出在：步骤清单是线性的，而专家的判断是树状的。专家会根据当前情况动态选择走哪条分支，而不是把所有步骤都跑一遍。所以 skill 的正确结构不是清单，而是决策树——先判断场景，再选择对应的子流程。

这个认知转变之后，我重构了所有 skill，把"步骤"改成了"分支"。效果立竿见影，Agent 的执行路径短了一半，准确率反而上去了。

3. 一个 skill 的完整结构：触发、执行、质量门、回退

3.1 触发条件写不好，后面全白搭

触发条件是 skill 的第一道关，也是最容易被忽视的一关。写得太宽，Agent 会在不该用的时候乱用；写得太窄，该用的时候又触发不了。

我的经验是，触发条件要同时包含正向信号和负向信号。正向信号是"出现这些特征就该用"，负向信号是"出现这些特征就绝对不能用"。

举个例子，一个"重构 skill"的触发条件：

• 正向信号：代码存在重复逻辑、函数超过 50 行、有明确的坏味道注释
• 负向信号：文件正在被其他分支修改、处于发布冻结期、没有测试覆盖

负向信号特别重要。很多事故都是因为 Agent 在一个不该动的时刻动了代码。加上负向信号之后，Agent 会主动"拒绝"执行，这比执行错了再回滚要安全得多。

提示：触发条件里的每一个信号，都应该是可以被程序化检测的。如果一条信号需要"人来判断"，那它就不适合放在触发条件里，应该放到质量门里。

3.2 执行步骤要带"意图说明"，而不是纯命令

Agent 执行 skill 的时候，如果只给它命令，它会机械照做；如果给它意图，它能在遇到意外时做出合理调整。这是我在实际项目里验证过很多次的经验。

对比一下两种写法：

# 纯命令式 1. 读取目标文件 2. 找到目标函数 3. 替换实现 4. 保存文件 # 带意图式 1. 读取目标文件（意图：确认当前实现，避免基于过时信息修改） 2. 定位目标函数（意图：确认修改范围，如果函数被多处调用需标记） 3. 替换实现（意图：保持接口不变，只改内部逻辑） 4. 保存并验证（意图：确认修改后语法正确、测试通过）

带意图的写法，Agent 在第二步发现"这个函数被 8 个地方调用"时，会主动停下来提示风险，而不是闷头改完。这就是把专家的"谨慎"注入了 skill。

3.3 质量门：让 Agent 自己判断"我做对了吗"

质量门是我认为整个 skill 结构里最有价值的部分，也是最难写的部分。它的作用是：在 Agent 声称"完成"之前，强制它做一次自我验证。

质量门分两类。一类是硬门，必须通过才能继续，比如"测试必须全绿"、"语法检查必须通过"。另一类是软门，不通过会警告但不阻断，比如"代码复杂度上升了"、"新增了未使用的变量"。

硬门的判断标准要极其明确，最好是二值的。我见过有人写"代码质量要好"这种质量门，Agent 根本没法判断。正确的写法是"圈复杂度不超过 10"、"没有新增的 lint 错误"这种可量化的。

软门则用来捕捉那些"不致命但值得注意"的情况。它的价值在于给人类审查者提供线索，而不是阻断流程。

3.4 回退机制：失败不是终点，而是分支

回退机制经常被忽略，但它决定了 skill 在生产环境里能不能用。一个没有回退的 skill，一旦失败就会留下烂摊子。

回退的设计原则是：每一步都要有对应的撤销动作。改文件之前先备份，执行命令之前先记录状态，调用外部接口之前先确认幂等性。这些看起来是常识，但在 skill 里必须显式写出来，因为 Agent 不会"想当然"地去做。

更进一步，回退本身也可以是一个分支。比如测试失败之后，不是简单回滚，而是进入"诊断分支"：分析失败原因，如果是环境问题就重试，如果是代码问题就回退并报告。这种"失败即分支"的设计，能让 skill 在复杂场景下表现得像一个有经验的工程师，而不是一个脆弱的脚本。

4. 把流程写成 skill 时最容易踩的五个坑

4.1 坑一：把 skill 写成了"万能工具"

我见过最典型的失败案例，是一个团队做了一个"代码修改 skill"，试图覆盖所有代码修改场景。结果这个 skill 臃肿到没人敢用，Agent 调用它的时候经常走错分支。

正确的做法是按场景拆分。修 bug 是一个 skill，加功能是一个 skill，重构是一个 skill，每个 skill 只处理一类场景。热词里提到的"测试 skill"、"看图技能 skill"、"GIS 空间分析 skill"，都是这种按场景拆分的思路。

拆分的粒度怎么定？我的标准是：如果一个 skill 的触发条件需要写超过 5 条，或者执行步骤超过 10 步，就该考虑拆了。

4.2 坑二：忽略了"上下文预算"

Agent 的上下文是有限的，skill 写得越长，留给实际任务的上下文就越少。我早期写的 skill 动辄两三千字，结果 Agent 光读 skill 就耗掉大半预算，真正干活的时候反而没空间了。

后来我把 skill 压缩到 500 字以内，把详细的参考文档放到外部，需要的时候再检索。这个思路和"渐进式披露"是一个道理：核心流程精简，细节按需加载。

注意：skill 的长度和它的可靠性不成正比。我实测下来，500 字以内的 skill 执行成功率反而更高，因为 Agent 不容易在长文本里迷失重点。

4.3 坑三：质量门写成了"走过场"

有些团队的质量门形同虚设，比如"检查代码是否符合规范"，Agent 随便看一眼就说"符合"。这种质量门不但没用，还会给人类审查者虚假的安全感。

质量门必须可验证、可复现。判断标准要具体到"运行哪个命令、看哪个输出、什么值算通过"。如果一条质量门没法用程序验证，那它就不该存在。

4.4 坑四：没有考虑"skill 之间的协作"

实际工作里，一个任务往往需要多个 skill 配合。比如"修复一个 bug"可能涉及"定位 skill"、"修改 skill"、"测试 skill"、"提交 skill"。如果这些 skill 各自为政，Agent 在它们之间切换的时候就会丢失上下文。

我的做法是给每个 skill 定义清晰的输入输出契约。上一个 skill 的输出，就是下一个 skill 的输入。这样即使 skill 是独立开发的，也能串起来用。

4.5 坑五：写完就不管了

skill 不是写完就完事的，它需要持续迭代。我建议给每个 skill 加一个"执行日志"，记录每次调用的场景、结果、失败原因。定期复盘这些日志，你会发现很多设计时没想到的边界情况。

我自己的习惯是每周看一次 skill 的执行日志，把高频失败场景提炼出来，要么补充到触发条件里，要么新增一个分支。这个过程持续几个月之后，skill 的可靠性会有质的提升。

5. 从"能跑"到"可信"：skill 的验证与迭代

5.1 怎么判断一个 skill 是真的可用

"能跑通"和"可信"是两回事。一个 skill 在 demo 里跑通很容易，但在生产环境里稳定可用是另一回事。我判断一个 skill 是否可信，看三个指标。

第一个是触发准确率：该触发的时候触发了吗？不该触发的时候有没有误触发？这个指标需要收集大量真实场景的调用记录才能算出来。第二个是执行成功率：触发之后，有多少次是完整走完流程并达到质量门的？第三个是回退率：失败之后，回退机制有没有正确生效？

这三个指标里，我最看重触发准确率。因为触发错了，后面全错。执行失败还可以重试，触发错误往往是灾难性的。

5.2 用真实任务做回归测试

skill 的测试不能只用构造的样例，必须用真实任务。我的做法是维护一个"回归任务集"，里面是过去真实发生过的任务，每个任务都有明确的预期结果。每次修改 skill 之后，跑一遍这个任务集，看通过率有没有下降。

这个任务集不需要很大，20 到 30 个就够，但必须覆盖各种边界情况：正常场景、异常场景、高风险场景、多 skill 协作场景。我见过有团队用 5 个任务做回归，结果 skill 一上线就出问题，因为那 5 个任务太"干净"了。

5.3 迭代的节奏：小步快跑还是大版本

我的经验是小步快跑。每次只改一个点，改完立刻跑回归，通过了再改下一个。大版本更新看起来很爽，但一旦出问题很难定位是哪个改动导致的。

具体节奏上，我会把 skill 的改动分成三类：修 bug（立即改）、优化触发条件（攒几个一起改）、重构结构（谨慎，需要完整回归）。这三类的节奏不一样，混在一起改容易乱。

5.4 让 skill 自己"长"出新的分支

这是我觉得最有意思的一点。当 skill 运行足够久之后，执行日志里会积累大量"意外情况"。这些意外情况，其实就是新的分支。

比如一个"代码修改 skill"运行三个月后，日志里出现了十几次"目标文件是自动生成的"这种情况。这时候就可以新增一个分支：检测到文件头有"自动生成"标记时，拒绝修改并提示用户改源文件。

这种"从日志里长出来的分支"，比设计时拍脑袋想出来的分支要靠谱得多，因为它们来自真实场景。

6. 几个可以直接抄的 skill 结构模板

6.1 高风险操作 skill 的骨架

高风险操作指的是那些不可逆、影响面大的操作，比如删除文件、修改公共模块、执行数据库变更。这类 skill 的核心是"多重确认"。

触发条件： 正向：操作目标被标记为高风险 / 影响面超过阈值 负向：处于冻结期 / 无备份 执行步骤： 1. 评估影响面（意图：确认风险等级） 2. 生成操作预览（意图：让人类看到将要发生什么） 3. 请求确认（意图：不可逆操作必须人工介入） 4. 执行操作（意图：在确认后执行） 5. 验证结果（意图：确认操作达到预期） 质量门： 硬门：操作前后状态可对比 硬门：有完整的操作日志 软门：影响面在预期范围内 回退： 执行前备份，失败时自动恢复

6.2 探索型任务 skill 的骨架

探索型任务指的是那些目标明确但路径不确定的任务，比如"找出这个 bug 的原因"、"调研某个方案的可行性"。这类 skill 的核心是"控制搜索范围"。

触发条件： 正向：任务描述包含"找出"、"调研"、"分析"等词 负向：已有明确解决方案 执行步骤： 1. 明确搜索边界（意图：避免无限扩散） 2. 收集候选信息（意图：广度优先） 3. 逐个验证（意图：深度优先） 4. 汇总发现（意图：形成可读结论） 质量门： 硬门：结论有证据支撑 软门：搜索范围未超出初始边界 回退： 无（探索型任务失败不产生副作用）

6.3 多 skill 协作时的编排要点

多 skill 协作最容易出的问题是"上下文丢失"。上一个 skill 的结论，下一个 skill 不知道。解决办法是定义一个共享的"任务上下文"，所有 skill 都从里面读、往里面写。

这个上下文不需要很复杂，一个结构化的 JSON 就够。关键是每个 skill 都要明确声明：我从上下文里读什么，我往上下文里写什么。这样即使 skill 是不同人开发的，也能拼在一起用。

7. 我个人的一些实操体会

做了一段时间之后，我最大的体会是：skill 的价值不在于让 Agent 更聪明，而在于让 Agent 更"守规矩"。模型的能力已经足够强了，缺的是在正确的时候做正确的事的纪律性。而纪律性，恰恰是资深工程师和新人最大的差距。

另一个体会是，写 skill 的过程，其实是在逼团队把"隐性知识"显性化。很多流程老工程师自己都说不清楚，写 skill 的时候被迫想明白。这个过程本身就有价值，哪怕最后 skill 没做出来，团队对流程的理解也上了一个台阶。

最后分享一个小技巧：如果你不知道从哪个流程开始写 skill，就去找团队里"最常被问的问题"。新人反复问的那些问题，往往就是最值得沉淀的流程。把它们写成 skill，既解决了新人的困惑，也让 Agent 有了可遵循的路径。这比从零设计一个"完美流程"要实际得多。