企业官网建设流程全解析

1. 从"会聊天"到"会干活"：Agent Skills到底解决什么问题

我做AI Agent相关的项目差不多两年了，踩过的坑比写过的代码还多。最早期的时候，圈子里流行的是"把所有指令塞进提示词"，指望大模型自己领悟该怎么干活。Demo阶段确实惊艳，可一上真实业务就露馅：模型今天记得调接口，明天忘了；同一个任务换个提问方式，执行顺序就乱了。后来我逐渐意识到，我们缺的不是更聪明的模型，而是一套让Agent稳定执行任务的"肌肉记忆"。把这种肌肉记忆沉淀成一个个可复用、可单独调试的模块，就是agent-skills这个方向存在的根本意义。

1.1 单纯靠提示词让Agent干活，瓶颈在哪

拿一个我早期做过的案例来说。当时要做一个自动整理周报的Agent，提示词里写得很详细——"请从邮件、IM、项目管理系统里收集本周任务，按项目分组，输出Excel表"。听起来没什么问题，真实跑起来全是问题。

第一个问题是数据来源的口径漂移。邮件里说的"本周任务"是按周一开始算的，项目管理系统里的"本周"可能按上周五截止，两边的数据对不上。模型不会主动发现这个差异，它只会默默把两边数据拼接在一起，然后给出一个"看着挺合理"的结果。

第二个问题是错误被悄悄消化。某个数据源接口超时，Agent没有停下来报告，而是自己发挥想象力补了一段数据进去。这在演示环境里看不出来，放到生产环境就是事故。

第三个问题更隐蔽——提示词越长，模型越容易丢失重点。你把"本周的判定标准""去重规则""异常处理方式"全部塞进一段提示词里，指令之间反而会互相干扰。而且提示词是无法拆解的，换一个任务场景，所有内容都要推倒重来。

当时我反复思考一个问题：人是怎么解决这些问题的？答案是——人会把"整理周报数据"这套流程固化成自己的操作习惯，下次直接用，不用每次重新思考。Agent需要的就是这种固化能力，技能模块就是这种固化的载体。

1.2 技能（Skills）和工具（Tools）、工作流（Workflows）的边界

很多人会把"技能"“工具”“工作流”这三个概念混在一起，我最初也绕晕过。用大白话捋一遍：

工具（Tools）是原子操作，比如"发送一条HTTP请求"“读取一个文件”"执行一段Python代码"。它们是Agent的"手指",一般由框架提供或者由外部API封装而来，独立且无状态。

技能（Skills）是由多个工具调用组合成的、能完成一个完整业务子任务的功能模块。举个例子，"从网盘批量下载本周报表"这个技能，内部可能依次调用"获取访问令牌""识别报表目录""匹配文件名""并发下载""校验文件完整性"五步。技能是面向具体业务场景的、可复用的能力单元——这是整个agent-skills架构里最核心的一层。

工作流（Workflows）是把多个技能按业务规则串联起来的编排层，可以带条件分支、循环、超时重试、人工审批节点。比如"周报自动生成"工作流：调用"收集数据"技能，然后调用"生成摘要"技能，再调用"发送报告"技能，最后等负责人确认。

工具是手，技能是手的连贯动作，工作流是编排整套动作的舞谱。做agent-skills项目，重点要打磨的恰恰是中间这层——技能。工具层太底层，通用性高但业务价值有限；工作流层太顶层，跟具体业务强绑定，很难跨场景复用。**只有技能层，既具备足够的业务抽象，又保持相对稳定的复用边界。**这个认知上的转变，是我后来重构整个Agent项目的最重要起点。

2. Skill的系统设计：输入契约、输出契约与状态管理

确定了要把"技能"作为核心设计单元之后，下一个问题就是：一个技能模块到底应该长什么样？我见过很多团队拿"给模型写一段好提示词"的思路来设计技能，结果做出来的是一个"高级提示词模板"。这完全跑偏了。技能模块的本质不是提示词，而是一段经过封装的、可执行的任务逻辑，它有明确的边界、可验证的输入输出、独立的错误处理。

2.1 为什么必须先定义输入输出契约

我先讲一个反面案例。团队里一个同事做了个"客户反馈分类"技能，输入是"一段客户留言文本"，输出是"分类标签"。听起来很清晰对吧？实际使用中才发现，分类标签到底有哪几类，他没定义——有时候返回"投诉"，有时候返回"退款意愿强"，同一个意思多种表达。下游做统计的同事为了兼容这些五花八门的标签，光清洗数据就花了三天。

这就是典型的输出契约缺失。设计一个技能时，第一件事不是写实现，而是把输入输出彻底定死：

输入契约至少要明确三点：参数名、类型、约束范围。以"客户反馈分类"为例，输入参数应该是{ "text": string, "max_length": int, "language": "zh" | "en" }，而不是"把客户留言传进来"。参数约束越清晰，技能的可控性越强。

输出契约则是一个结构化的JSON Schema，比如：

{ "category": "投诉 | 咨询 | 表扬 | 退款 | 其他", "confidence": 0.0, "key_phrases": ["响应慢", "客服态度差"], "needs_human_review": false }

定义输出契约的好处是，所有下游逻辑都可以基于稳定的结构去处理，而不是依赖自然语言描述。实践里还可以再加一个fallback_reason字段——当技能无法处理某个输入时，返回这个字段而不是甩给模型"自由发挥"。

提示：写技能设计文档时，把"输入输出契约"放在最前面，比先把实现代码写出来要省力得多。先想清楚边界，再谈实现，能帮你省掉后面80%的麻烦。

2.2 状态管理与上下文传递的三种做法

技能设计里另一个绕不开的问题是：技能执行过程中需要跨步骤传递临时数据时，状态放在哪？

我实践下来，有三种做法，各有适用场景：

第一种：无状态技能（Stateless）。技能内部把任务一次性完成，不保留任何中间状态。比如"URL抓取并提取正文"技能，输入URL，输出正文文本，一次搞定。这种技能最简单、最稳定、也最容易被多个Agent复用，是默认推荐的做法。

第二种：外部状态存储（External State）。技能执行过程中，把中间结果写入Redis、数据库或对象存储。适用于多步骤、可能要跑几分钟的重型技能。比如"批量处理1000张图片"，每处理完一张就把结果写入数据库，中途崩溃了可以断点续跑。这种方案的关键是状态读写要和技能逻辑分离，否则技能就没法摆脱具体的运行环境了。

第三种：会话上下文透传（Context Passing）。技能接收一个context对象，里面带着前面步骤的结果、用户偏好、业务元信息。这种方式在现代Agent框架里最常见，因为整个技能链条本来就是靠上下文串起来的。但要注意：context越大，模型和技能的负担越重，处理时需要做裁剪和摘要。

我个人的组合策略是：常规技能一律无状态；重型任务用外部存储；需要多技能协作时，用轻量级context传递关键信息，而不是把整个历史一股脑传下去。

2.3 技能描述怎么写才能让模型准确调用

技能有了，还得让Agent"知道"什么场景下该调用它。这靠的是技能的description字段——这是决定技能调用准确率的关键，却常常被当成可有可无的装饰。

写得好的技能描述，应该像一个清晰的服务说明。举两个例子对比：

写得差的：

description: "对文本进行情绪分析。"

写得好的：

description: "当用户需要判断一段中文文本蕴含的情感倾向（积极/消极/中性），或需要从客户反馈中提取情绪信号时，使用此技能。输入stext为原始文本，返回情感标签及置信度。若文本长度超过5000字请先截断。不要用此技能做文本分类，那是text_classifier技能的工作。"

注意到差别了吗？好的描述包含触发条件（When）、输入说明（What）、约束边界（Limits），甚至还告诉模型"这个技能不适合做什么"。这样做有两个直接好处：一是减少误调用——模型不会把一个分类任务错误地交给情绪分析技能；二是减少无效调用——你知道这个技能处理不了超长文本，先截断再传。

给所有技能写描述的时候，我都要求按"触发场景 + 输入期望 + 输出格式 + 不适用场景"这个模板来。写入框架后实测，技能调用的准确率从70%出头提升到了90%左右，效果立竿见影。

3. 从零搭建一个技能库：目录规划与技能实现流程

设计好单个技能的系统结构之后，下一个大问题是：技能库整体怎么组织？这不是一个简单的"建几个文件夹"的问题。技能库本身是一个会持续演进、会腐烂、会被团队多人修改的资产，组织方式决定了它的生命力和复用率。

3.1 先给技能库画边界：什么该收，什么不该收

很多人的第一个技能库是从"把有用的小功能都塞进去"开始的。没有边界，技能库很快就会变成垃圾场——每个技能都很"有用"，但谁也不知道该用哪个。

我建议按照"业务域 + 能力类型"两个维度来圈定边界。业务域解决"这个技能是给谁用的"，例如"销售域""客服域""数据域"；能力类型解决"这个技能干什么活"，例如"信息提取""内容生成""数据分析""系统操作"。

用这个框架来取舍：一个技能要进入库，至少要满足三个条件——第一，面向明确的业务场景；第二，具备跨任务复用的可能；第三，实现逻辑已经验证稳定。一次性脚本、临时Hack、个人偏好型的加工逻辑，都不该进技能库，把外部API直接包装成技能的做法也尽量少用。技能库不是API网关注册中心，它要保存的是"经过思考后的业务逻辑"，不是纯粹的传输层封装。

3.2 一个技能从抽象到落地的完整流程

以我最近给团队做的"合同关键条款抽取"技能为例，完整走一遍流程：

第一步：需求抽象。业务方提的需求是"帮我看一眼合同，告诉我哪些条款有风险"。这句话太模糊，不能直接做成技能。我把它拆解成更明确的子任务：抽取合同双方名称、合同金额、付款节点、违约责任、保密期限、解约条件。每个子任务都对应明确的信息抽取目标。

第二步：定义输入输出。输入是合同的PDF路径和页数范围；输出是上述字段的结构化JSON。这个定义过程要跟业务方反复确认，尤其是"风险"的判定标准——业务方真正想要的不是"判断风险"，而是"提取出人工判断风险所需的全部信息"。

第三步：选型与实现。合同大概率是PDF格式，先用解析库提取文本，然后分段送入模型做信息抽取。这个技能同时涉及"PDF解析""文本切片""结构化抽取"多个底层能力，但它对外暴露的是一个统一入口：传入合同文件，得到结构化字段。

第四步：编写技能描述与测试用例。准备20份真实合同（脱敏后）作为测试集，记录抽取的准确率、漏抽率、格式错误率。达不到预期就迭代，直到稳定。

第五步：接入Agent场景。把技能注册到多Agent协作环境里，让"合同审查Agent"在实际任务中调用它。

这五步缺一不可，但最容易被跳过的是第四步——测试。一个没有测试用例的技能就是一个"不知道什么情况下会出错"的定时炸弹。我的最低要求是每个技能必须伴生至少5个典型测试用例和2个边界用例，否则不允许合入技能库主线。

3.3 技能命名与版本号：小细节，大麻烦

命名这个事看着小，等技能库里有了两三百个技能，你会发现命名混乱比代码混乱更让人头疼。我的命名规范是"业务域-能力-对象-形态"：sales-extract-contract-clauses、>1. 文本预处理：清洗转写文本，合并重复片段，标记说话人； 2. 分段理解：将长文本按话题切分，分别做信息抽取； 3. 结构化组装：将抽取结果按统一schema组装，并做去重和校验； 4. 任务对接：将待办事项逐条转换为项目管理软件的字段，并写入系统。

最容易出问题的是第三步。模型对"待办事项"的提取经常漏掉责任人，或者给出的截止时间是相对描述（比如"下周"）而不是具体日期（"2025-12-08"）。我的对策是：在抽取阶段就要求模型对每个待办输出action（动作描述）、owner（责任人姓名）、due_date（ISO8601格式日期）、priority（高/中/低）四个字段；凡是责任人缺失的，默认标记为"待确认"并放进"需要升级的事项"里，而不是默默丢弃。

第四步的容错也值得说。项目管理工具的写入接口有可能因为权限、字段格式、并发锁等原因失败。我在技能里做了一个简单的"半自动对接"策略：写不进去的事项，不会让整个技能崩溃，而是返回一个sync_failed列表，由人工确认后重新触发。Agent技能不等于全自动，灵活地在自动化和人工兜底之间切换，才是生产环境里真正耐用的做法。

4.3 实测效果与调优方向

技能上线后我统计了一个月的使用数据：一共处理了46次会议记录，自动提取的待办事项共218条，人工需要修正的只有9条，准确率在95%以上。这比之前纯靠人工整理省了大概四分之三的时间。

准确率能到这个水平，其实取决于一个很关键的细节——标题级约束。我在技能描述里明确写了"输出待办事项时，必须使用'动词 + 具体内容 + 责任人 + 时间'的句式，不要使用模糊表达"，这个约束对模型输出的规范性提升非常明显。

后续我还在迭代两个方向：一是接入企业内部知识库，让纪要里的术语和项目名称能自动映射到标准名称；二是对跨团队的会议，增加"相关方影响"字段。技能这个东西就是这样，第一版能跑通就成功了一半，剩下的靠跟业务方的持续碰撞打磨。

5. 落地过程中的坑与对策

任何项目做到生产环境，问题才开始真正暴露。Agent技能落地也不例外。我总结了自己和团队踩过的三个最深的坑，每一个都花了不少时间去趟平。

5.1 技能边界模糊引发的"套娃式"调用

第一个坑是技能之间的边界模糊。早期技能库里有一个"获取客户信息"的技能和一个"分析客户画像"的技能。听名字好像边界清楚，实际使用中问题很大——"获取客户信息"技能里其实包含了部分统计分析逻辑，"分析客户画像"技能里也调用了部分原始数据查询。一个"分析客户流失原因"的任务触发了两个技能反复调用对方，形成了"套娃式"调用链，延迟翻了3倍还多。

排查的时候我画了一下真实的调用关系图，才发现两个技能在功能上有大面积重叠。我当时的对策是重构技能边界：把"获取客户信息"强行收敛为只返回原始字段，不做任何分析；所有统计、建模、画像的逻辑统一收进"分析客户画像"技能。这一步执行完之后，调用链变得清晰干净，延迟降了60%。

这个坑的本质其实是设计时"顺手多做了一点"造成的。技能的设计原则应该是单一职责——一个技能只做一件事，哪怕这件事特别小。宁可多设计几个"做小事"的技能，由工作流把它们串起来，也不要搞"万能技能"。万能技能往往什么都做不好。

5.2 模型能力参差时的降级策略

第二个坑是我刚开始没用本地小模型跑Agent时踩到的。不同的底层模型对同一个技能描述的理解能力差异极大。同一个"会议纪要结构化归档"技能，用旗舰模型跑，输出规范、字段齐全；切到轻量模型，可能漏掉一半字段，或者把JSON schema都搞变形了。

这迫使我在技能设计里引入模型能力分级的概念。具体做法是：技能配置中增加一个model_level字段，标记该技能的最低可用模型等级。同时每个技能都要提供"降级预案"——当检测到当前模型能力不足时，技能自动走向更保守的执行路径，比如：

• 简化输出字段，只保留最核心的信息
• 从"完全自动抽取"降级为"自动抽取 + 人工确认"
• 从"多步骤连续执行"降级为"分步骤执行，每步都让用户确认"

这套降级策略上线之后，最直观的体验是：换模型不再导致连带事故。即便底层模型变了，技能也能知道自己的能力边界，不会硬着头皮硬闯。

注意：模型能力分级不是一个固定配置，它应该随着模型迭代不断更新。我每季度会跑一遍全量技能的自测用例，把测试结果跟model_level配置对比，发现不匹配就调整。

5.3 技能测试不能只靠端到端

第三个坑是关于测试的。刚开始我觉得技能测试很简单：写几个测试用例，跑一遍看输出对不对就行。真正做起来才发现，端到端测试的用例是"过了就不知道有没有覆盖到，挂了也不知道坏在哪里"。

举个具体的情景。某个技能在一个测试用例中输出了预期结果，但这个结果恰恰是"模型运气好"或者"恰好命中了训练数据里的相似案例"产生的。同一个技能换一批输入，表现立刻暴跌。面对这种随机性，端到端测试帮不了你什么。

合理的做法是分层测试：

• 单元测试：技能内部每个步骤单独测试，尤其是数据解析、格式转换、异常分支；
• 契约测试：专门校验技能输出是否符合schema定义，字段是否齐全、类型是否正确；
• 场景测试：模拟真实用户的多轮交互，关注技能是否在正确的时机被调用；
• 稳定性测试：同一组输入反复跑50次，观察输出分布是否稳定。

这四层跑下来，技能的可靠性才能有一个基本认知。我最近还在技能库里加了一个"阴影模式"：新技能上线前，先让它在真实流量里"旁听"但不对用户生效，记录它的输出和理想的输出之间的差距，连续观察一周，稳定了才正式开放。这个做法极大降低了上线翻车的概率。

6. 从个人技能库到团队共享：复制与沉淀

当技能库从"我一个人的玩具"变成"一个团队的生产工具"，问题就变了：不再只是"我的技能能不能用"，而是"别人的技能我能不能用""我的技能别人能不能维护"。这个阶段，文档规范和共享机制的重要性，开始超过纯粹的编码能力。

6.1 技能文档：让同事两周后还能看懂

很多搞技术的人讨厌写文档，但我现在要说一句可能让你反感的话：技能代码本身不构成技能，文档才是技能真正可复用的前提。理由很简单——技能库是给多个Agent和多个开发者共享的，如果没有清晰的文档，一个人写的技能别人根本不敢调用。

我给团队定的技能文档模板是五个部分：用途说明（这个技能解决什么问题）、输入输出契约（JSON Schema和示例）、执行流程（步骤和依赖关系）、已知限制（哪些场景下不能用、可能产生什么错误）、变更记录（版本号和每次改了什么）。

文档不需要长，但必须快——让一个不熟悉这个技能的人，读三分钟就能判断"这个技能适不适合我用、怎么用"。这种文档才是技能从"个人经验"变为"团队资产"的关键。

6.2 共享技能库的冲突与合并

技能库一旦多人维护，就一定会遇到并发冲突。两个人同时往库里加了一个都叫parse-invoice的技能，实现思路完全不同，这是最常见的冲突场景。

我的经验是：共享技能库必须有明确的评审和合并纪律。技能不是完美的"代码写出来就能用"，它是业务逻辑的高度抽象，如果有人随意改动，下游的工作流完全无法追踪。我们团队现在实行的是"技能委员会"机制——每个人可以做技能提案，但合入技能库主线前需要过一遍评审：输入输出契约是否清晰、测试用例是否充分、跟已有技能是否有重叠、命名是否合规。

这看起来增加了流程负担，但实际上压低了长期的维护成本。因为技能库的麻烦从来不是"加技能"，而是"技能越来越多之后，没人知道哪个能信、哪个不能用、哪些已经过时"。有评审和版本管理，才能让技能库保持可信。

6.3 一点关于技能生态的实在体会

聊到最后，我想说点跟技术不那么相关、但我觉得更重要的话。

Agent技能设计的本质，不是给模型写代码，而是把业务经验系统地沉淀下来。我见过很多技能库，设计得漂亮、代码写得优雅，但业务方根本不买单——因为技能解决的是技术人员想象中的问题，不是真实业务里的痛点。反过来，最好的那些技能，往往是跟业务方反复碰撞、在一次又一次的"这个字段不对""这个流程太绕""这个输出不够直观"反馈中迭代出来的。

所以如果你现在正准备搭一个技能库，我的建议是：先别急着搭框架、写代码。找一两个真实的、让业务方头疼的重复性任务，手工拆解清楚，定义好输入输出，做成两三个能解决实际问题的技能。技能库不需要大，需要准。当这几个技能真正被用起来、让业务方觉得"离不开"的时候，你再去考虑规模化和共享协作——那时候你会对"什么技能值得沉淀、什么不值得"有本能一般的判断力，比任何方法论都管用。

我在这条路上踩过的坑很多，但收获也实打实：那些曾经反复翻车的提示词，如今变成了一个个稳定的技能模块；那个只能聊天的Agent，如今真的能独立处理团队里一摊子日常活儿。这套东西给你最大的价值，是让你从"和大模型讨价还价"的泥潭里抽身出来，把精力放回真正的业务问题上去。如果有人问我要不要做agent-skills这样的技能体系，我的回答是：一定要做，但要从最小、最痛的那个业务问题开始做。