企业官网建设流程全解析

1. 从“agent-skills”这个标题说起：它到底在解决什么问题

第一次看到“agent-skills”这个标题，我脑子里蹦出来的不是某个具体框架，而是一类很实际的需求：怎么让一个智能体（agent）真正具备可复用、可组合、可评估的能力模块。过去两年里，我参与过几个自动化流程和智能助手相关的项目，踩过最大的坑不是模型不够强，而是“能力”这件事被写得太散——每个任务都重新写一遍提示词、重新接一遍工具、重新调一遍参数，最后维护成本高得离谱。agent-skills 这个方向，本质上就是想把这种散乱的状态收敛成一套有结构的东西。

说得直白一点，agent-skills 关注的不是“让模型更聪明”，而是“让模型的能力被组织起来”。它要回答几个很朴素的问题：一个智能体要完成某类任务，需要哪些最小能力单元？这些单元怎么描述、怎么调用、怎么组合？调用失败了怎么回退？效果好坏怎么量化？这些问题听起来像工程问题，但真正落地时会牵扯到提示词设计、工具封装、上下文管理、错误处理、评估体系等一整条链路。

这篇文章适合谁看？如果你正在做智能助手、自动化工作流、多步骤任务编排，或者你只是想让自己的脚本从“一次性”变成“可复用”，那 agent-skills 这套思路对你是有直接参考价值的。我不打算把它讲成学术概念，而是按一个实际做过类似系统的人的视角，把设计思路、核心细节、实操过程、踩坑经验一层层拆开。你会看到我为什么这么选、参数怎么定、哪些地方看起来能省事但实际会埋雷。

需要先说明一点：agent-skills 并不是某个唯一标准，不同团队对“skill”的粒度定义差别很大。我下面讲的是基于常见工程实践的一套可落地方案，你可以把它当成一个参考骨架，按自己的场景裁剪。核心目标只有一个——让能力可管理，而不是让每次调用都从零开始。

2. 整体设计与思路拆解：为什么要把能力拆成“技能”

2.1 从“一个大提示词”到“技能模块”的转变逻辑

早期做智能体，最常见的做法是写一个很长的系统提示词，把所有规则、工具说明、输出格式全塞进去。任务简单时没问题，一旦任务变多，这个提示词会膨胀到几千字，改一处影响一片，调试基本靠猜。我印象很深的一次，一个流程里同时涉及信息提取、格式转换、外部查询三个环节，提示词写到后面连自己都不敢动，因为一动就不知道哪个环节会崩。

agent-skills 的思路是把这种“单体提示词”拆成多个技能模块。每个技能只负责一类明确的能力，比如“从非结构化文本里抽取字段”“把结构化数据转成指定格式”“根据条件选择下一步动作”。每个技能有自己的描述、输入输出约定、调用示例和失败处理策略。这样做的好处很直接：改一个技能不会波及别的技能，测试可以单独跑，复用也变得自然——同一个抽取技能可以用在三个不同流程里。

这里有个关键判断：拆分的粒度。拆得太粗，等于没拆；拆得太细，技能数量爆炸，组合成本反而上升。我的经验是，一个技能最好对应“一个明确的动作意图”，而不是“一个函数”。比如“抽取字段”是一个技能，“把日期格式从 A 转成 B”也可以是一个技能，但“处理用户请求”就太粗，“把字符串第 3 个字符大写”就太细。判断标准可以简单点：如果这个能力在别的流程里也可能被独立调用，那它就值得成为一个技能。

2.2 技能描述为什么比技能实现更重要

很多人做 agent-skills 时把精力全放在实现上，觉得描述随便写写就行。实际恰恰相反：技能描述是智能体决定“要不要用这个技能”的唯一依据。模型不会读你的代码，它只能读你给的描述。描述写得含糊，模型就会在错误的时候调用它，或者该调用时不调用。

我一般要求技能描述包含四块信息：这个技能做什么、什么时候用、输入长什么样、输出长什么样。举个例子，一个“提取联系人信息”的技能，描述里要明确说“当输入文本包含人名、电话、邮箱等联系信息且需要结构化输出时使用”，而不是只写“提取联系人”。前者能让模型判断场景，后者只能让模型猜。

还有一个容易被忽略的点：描述里要写清楚边界。比如“本技能不处理图片中的文字”“本技能假设输入已经是纯文本”。这些边界信息能显著减少误调用。我吃过亏，一个技能没写边界，结果模型把带表格的输入也丢进去，输出直接乱掉，排查了半天才发现是调用条件没约束好。

2.3 组合方式的选择：串行、并行还是条件分支

技能拆好之后，下一个问题是怎么组合。常见有三种方式：串行、并行、条件分支。串行适合有前后依赖的流程，比如先抽取再转换；并行适合互不依赖的子任务，比如同时查两个数据源；条件分支适合根据中间结果决定下一步，比如“如果抽取到的字段缺失，就走补全技能”。

我的建议是默认串行，按需并行，谨慎分支。串行最容易调试，出问题能定位到具体环节；并行能省时间，但会引入结果合并和错误传播的复杂度；条件分支最灵活，但也最容易写出难以维护的“技能迷宫”。我见过一个流程里套了四层条件分支，最后连作者自己都说不清某条路径是怎么走到的。如果确实需要复杂分支，建议把分支逻辑单独抽成一个“路由技能”，而不是散落在主流程里。

另外，组合时要注意上下文传递。每个技能的输出怎么传给下一个技能，是直接透传还是做一层转换，这个要提前定好。我一般要求技能输出统一成结构化格式（比如 JSON），这样下游技能不用关心上游是怎么实现的，只关心字段含义。这个约定看起来简单，但能省掉大量联调时间。

3. 核心细节解析与实操要点：技能怎么定义、怎么调、怎么评估

3.1 技能定义的结构：一份可落地的模板

技能定义我一般用一份结构化描述来承载，包含以下字段。你可以用 YAML、JSON 或者直接写在代码里的配置对象，形式不重要，关键是字段齐全。

description我前面强调过了，这里补充一点：示例比描述更能约束模型行为。一组好的输入输出示例，能让模型对格式的理解准确度提升很明显。我通常会给两组示例，一组正常情况，一组边界情况，比如输入为空或字段缺失时输出什么。

failure_policy是很多人会漏的。技能调用失败是常态，不是异常。失败时是重试、降级、还是直接返回错误让上游处理，要提前定。我一般把失败策略分成三类：可重试（比如网络抖动）、可降级（比如用默认值兜底）、不可恢复（比如输入格式根本不对）。分类之后，上游组合逻辑就能按类型处理，而不是一刀切。

3.2 输入输出约定：为什么我坚持用结构化格式

技能之间传递数据，我坚持用结构化格式，最常用的是 JSON。原因有三个：一是字段含义明确，下游不用解析自然语言；二是便于校验，字段缺失或类型不对能提前发现；三是便于日志和回放，出问题能直接看数据。

这里有个实操细节：字段命名要稳定。我见过一个项目，上游技能输出叫user_name，下游技能读的是username，结果一直取不到值，排查了半天。后来我们定了个规矩，所有技能的输出字段名必须在一个公共字典里注册，新增字段要评审。这个规矩听起来重，但比事后排查便宜得多。

另外，空值和缺失要区分。空字符串、null、字段不存在，这三种情况在业务上含义可能完全不同。我一般要求技能明确说明：字段不存在表示“没提取到”，null 表示“提取到了但值为空”，空字符串表示“提取到了且值就是空串”。这个区分在后续处理里很关键，比如补全逻辑只应该对“没提取到”生效，而不是对“值为空”生效。

3.3 技能调用的触发条件：怎么让模型选对技能

技能定义好了，怎么让模型在合适的时候调用合适的技能？这是 agent-skills 落地时最核心的难点之一。我的做法是在系统层面维护一份技能清单，把每个技能的 description 和触发条件一起给模型，让模型自己判断。但光靠模型判断不够稳，所以我会加一层规则兜底。

规则兜底的意思是：对于高频、明确的场景，直接用规则匹配，不走模型判断。比如输入里包含“提取邮箱”这种明确指令，就直接路由到对应技能。规则和模型判断结合，既能覆盖明确场景，又能处理模糊场景。我一般把规则放在前面，规则没命中再交给模型判断。

还有一个技巧：给技能加“负向示例”。也就是明确告诉模型“以下情况不要用这个技能”。比如“当输入是图片路径时不要调用文本抽取技能”。负向示例能显著减少误调用，尤其是技能之间边界模糊的时候。

3.4 效果评估：怎么知道技能好不好用

技能做完不是终点，得能评估。我一般从三个维度看：准确率、稳定性、成本。准确率看输出对不对，稳定性看同样输入是否稳定输出，成本看调用耗时和资源消耗。

评估数据从哪来？两个来源：一是人工构造的测试集，覆盖正常和边界情况；二是线上真实调用的采样。测试集用于回归，线上采样用于发现新问题。我一般要求每个技能至少有 20 组测试用例，覆盖正常、边界、异常三类。这个量不大，但能挡住大部分低级问题。

评估频率上，技能改动后必须跑一遍测试集，线上采样每周看一次。如果某个技能的准确率或稳定性下降，先看是不是上游输入变了，再看是不是模型版本变了，最后才怀疑技能本身。这个排查顺序能省很多时间，因为技能本身往往不是第一嫌疑人。

4. 实操过程与核心环节实现：从零搭一个技能系统

4.1 环境与依赖准备：先把地基打稳

动手之前，先把基础环境定下来。我一般需要这几样东西：一个能调用模型的运行时、一个存技能定义的地方、一个日志与回放机制、一个测试框架。运行时可以是任意支持模型调用的环境，技能定义我习惯用文件存（便于版本管理），日志我要求记录每次调用的输入、输出、耗时、命中的技能，测试框架用最常见的单元测试工具就行。

这里有个容易忽略的点：技能定义的加载方式。我建议启动时一次性加载所有技能定义到内存，而不是每次调用都读文件。原因是读文件有 IO 开销，而且文件可能被中途改动导致行为不一致。加载后可以加一个版本号，改动时热更新，但更新要可控，不能悄悄变。

依赖管理上，我建议把技能实现和技能定义分开。定义是配置，实现是代码。这样改定义不用重新部署代码，改实现也不用动定义。两者通过 name 关联。这个分离在技能多的时候优势很明显，我试过把两者混在一起，后来改一个描述都要重新走一遍发布流程，很痛苦。

4.2 第一个技能：从最简单的抽取开始

搭系统我习惯从最简单的技能开始，跑通链路再扩展。第一个技能我一般选“从文本里抽取指定字段”，因为它输入输出清晰，容易验证。

实现步骤大致是这样：先定义技能描述和输入输出 schema，然后写实现逻辑，接着构造测试用例，最后接入调用链路跑一遍。实现逻辑我一般分两步：先用规则或关键词做一轮粗筛，再把候选内容交给模型做精提取。这样做的好处是减少模型调用次数，成本低，而且规则能挡住明显不相关的输入。

参数上，我一般会设一个置信度阈值。模型输出每个字段时可以带一个置信度，低于阈值的字段标记为“待确认”，而不是直接采用。阈值定多少要看场景，我一般从 0.7 开始试，根据误报和漏报情况调整。这个阈值不是拍脑袋定的，要拿测试集跑一遍，看不同阈值下的准确率和召回率，选一个平衡点。

跑通第一个技能后，我会立刻做一件事：把它接到一个真实的小流程里。哪怕流程很简单，比如“读一段文本→抽取字段→打印结果”，也能暴露很多定义阶段想不到的问题，比如字段命名冲突、空值处理、日志缺失。这一步不能省，我见过太多技能单独测没问题、一组合就崩的情况。

4.3 技能组合：把多个技能串成一条流程

单个技能跑通后，开始组合。我一般先画一张流程图，标清楚每个环节的输入输出和依赖关系。画图不是为了好看，是为了发现循环依赖和缺失环节。我踩过的坑是：两个技能互相依赖对方输出，结果谁都没法先跑。画图能提前发现这种问题。

组合实现上，我建议用一个编排层来管理技能调用顺序，而不是把调用逻辑写死在某个技能里。编排层负责：按顺序调用技能、传递上下文、处理失败、记录日志。技能本身只关心自己的输入输出，不关心被谁调用、下一个是谁。这个分层让技能真正可复用，也让编排逻辑可测试。

上下文传递我一般用一个共享对象，每个技能从里面读自己需要的字段，写自己的输出字段。共享对象要加命名空间，避免不同技能的字段互相覆盖。比如技能 A 的输出放在skill_a.result下，技能 B 读的时候明确读skill_a.result。这个约定能避免很多隐蔽的字段冲突。

失败处理在组合层做。我一般定义三种策略：重试（最多 N 次，间隔递增）、降级（用默认值或跳过）、终止（返回错误给上游）。具体用哪种，在技能定义里声明，编排层按声明执行。这样技能作者能控制自己技能的失败行为，编排层只负责执行策略。

4.4 日志与回放：出问题时的救命稻草

技能系统跑起来后，最怕的是“出问题了但不知道哪出的”。所以日志必须从第一天就做好。我要求日志记录：调用时间、技能名、输入、输出、耗时、是否命中缓存、失败原因（如果有）。这些字段看起来多，但真出问题时每一个都可能用上。

回放机制是日志的延伸。有了完整日志，就能把某次调用原样重放，看是哪一步出的问题。我一般会做一个简单的回放工具，输入日志记录，输出每一步的中间结果。这个工具在排查偶发问题时特别有用，因为偶发问题往往没法稳定复现，只能靠回放。

日志存储上，我建议结构化存储，便于查询和统计。比如按技能名、时间范围、是否失败来查。我见过用纯文本日志的，查一个问题要 grep 半天，效率很低。结构化存储前期多花点功夫，后期省的时间是数量级的。

5. 常见问题与排查技巧实录：那些文档里不会写的事

5.1 技能误调用：模型选了不该选的技能

这是最高频的问题。表现是模型调用了不相关的技能，或者该调用时没调用。排查思路分三步：先看技能描述是否清晰，再看触发条件是否有冲突，最后看是否有负向示例缺失。

我遇到过一次，两个技能描述里都写了“处理文本”，结果模型经常选错。后来把描述改成“处理纯文本，不含表格”和“处理含表格的文本”，误调用立刻下降。描述里的差异点要显式写出来，不能指望模型自己推断。

还有一个隐蔽原因：技能数量太多。技能清单太长时，模型的选择准确率会下降。我的经验是，单次给模型的技能清单最好控制在 10 个以内。超过就分组，先让模型选组，再在组内选技能。这个分层选择能明显提升准确率。

5.2 输出格式不稳定：同样的输入输出不一样

模型输出有随机性，格式偶尔会飘。表现是字段名大小写不一致、JSON 多了或少了大括号、该是数组的给了字符串。排查时先看是不是提示词里格式说明不够明确，再看是不是缺少示例。

我的做法是在技能实现里加一层格式校验和修复。校验用 schema，不符合就尝试修复（比如补全括号、统一大小写），修复不了就重试或降级。这层校验不能省，因为完全依赖模型输出格式稳定是不现实的。修复逻辑我一般写得保守，只做明确安全的修复，不确定的就走失败策略。

另外，温度参数对格式稳定性影响很大。需要稳定格式时，温度调低甚至调到 0。需要多样性时再调高。这个参数我一般按技能类型定，抽取类技能温度低，创意类技能温度高。

5.3 上下文丢失：多步流程里前面的信息没了

多步流程里，后面的技能读不到前面的输出，这是组合层的经典问题。原因通常是上下文对象没传对，或者字段名对不上。排查时先打印每一步的上下文快照，看字段在哪个环节丢的。

我一般要求编排层在每次技能调用前后都记录上下文快照，这样能精确定位丢失点。字段名对不上的问题，靠前面说的公共字典来防。字典里注册字段时，要写清楚含义和类型，新增字段要评审，避免同名不同义。

还有一个原因是上下文太长被截断。如果上下文里塞了太多无关信息，模型可能读不到关键字段。我的做法是每个技能只接收自己需要的字段，而不是整个上下文。这样既减少干扰，也降低截断风险。

5.4 性能问题：流程跑得太慢

技能多了之后，流程耗时可能变得不可接受。排查时先看每个技能的耗时分布，找出瓶颈。常见瓶颈有三个：模型调用次数太多、串行环节太多、单个技能内部逻辑太重。

优化手段对应也有三个：能合并的模型调用合并、能并行的环节并行、能缓存的中间结果缓存。缓存我一般按输入哈希做 key，相同输入直接返回缓存结果。缓存要注意失效策略，输入变了或技能版本变了要失效。我见过缓存没失效导致输出过期的，排查起来很费劲。

并行化要谨慎，因为会引入结果合并和错误传播的复杂度。我一般只对确实互不依赖且耗时占比高的环节做并行。并行后要确保错误处理覆盖所有分支，不能一个分支失败整个流程挂掉。

5.5 常见问题速查表

6. 技能系统的扩展与维护：让它活得久一点

6.1 技能版本管理：改动不能悄悄发生

技能一旦被多个流程引用，改动就不能随意。我一般要求技能有版本号，改动时升版本，引用方明确指定用哪个版本。这样改一个技能不会影响所有引用方，可以灰度切换。

版本管理还有个好处是回滚方便。新版本出问题，切回旧版本就行，不用紧急改代码。我一般保留最近三个版本，更早的归档。归档不是删除，是移到不常访问的地方，万一要查历史还能找到。

6.2 技能复用：怎么避免重复造轮子

技能多了之后，容易出现功能重叠。我一般定期做一次技能盘点，看哪些技能功能相似、哪些技能没人用。相似的考虑合并，没人用的考虑下线。盘点频率我一般是一个季度一次，太频繁没必要，太稀疏会积累技术债。

复用还有个技巧：把通用逻辑抽成基础技能。比如“字段校验”“格式转换”这类逻辑，很多技能都会用到，抽成基础技能后，其他技能调用它就行，不用各自实现。基础技能要特别稳定，因为依赖它的技能多，改一处影响一片。

6.3 技能下线：怎么安全地移除一个技能

技能下线比上线更需要谨慎，因为可能有流程还在用。我一般分三步：先标记为“废弃”，观察一段时间看还有没有调用；确认没调用后，从技能清单里移除；最后归档定义和实现。标记废弃期间，如果有调用，日志里会有记录，能发现遗漏的引用方。

下线前要通知所有可能的引用方，这个通知不能只发一次，要在多个渠道重复。我见过通知发了但有人没看到，结果技能下线后流程挂了。后来我们定了个规矩，下线前必须确认所有引用方都已知晓，确认方式要留痕。

6.4 技能评估的持续化：别等出问题才看

技能评估不能只在改动时做，要持续做。我一般设几个监控指标：调用量、成功率、平均耗时、格式异常率。这些指标异常时自动告警，不用等人发现。

指标阈值我一般按历史数据定，比如成功率低于 95% 告警，耗时超过历史均值两倍告警。阈值不能定太死，要留调整空间。告警后先看是不是上游输入变了，再看是不是模型版本变了，最后才怀疑技能本身。这个顺序能过滤掉大部分误报。

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

做 agent-skills 这套东西，最大的体会是：技能的质量不取决于实现多精巧，而取决于边界多清晰。一个边界清晰的简单技能，比一个功能强大但边界模糊的技能好用得多。我见过太多技能因为边界不清，在组合时各种出问题，最后不得不重写。

另一个体会是：别追求一次做完美。技能系统是长出来的，不是设计出来的。先做一两个技能跑通链路，再根据实际需求扩展。我一开始想设计一个覆盖所有场景的技能体系，结果设计了两周还没落地，后来改成先做最简单的抽取技能，两天就跑通了，后面扩展反而快。

还有一点：日志和测试要舍得投入。这两块看起来不直接产生价值，但出问题时能救命。我现在的习惯是，技能实现写完后，测试用例和日志字段一起补上，不补完不算完成。这个习惯让我在后续维护里省了大量时间。

最后分享一个小技巧：给技能起名要能自解释。名字里带上动作和对象，比如extract_contact_info而不是process_text。名字清晰，日志好读，模型选择时也更容易判断。这个细节很小，但长期看收益很大。