企业官网建设流程全解析

“skills”这个词，这几年在AI Agent圈子里被反复提起。最早是给模型“喂提示词”，后来是挂工具、调工作流，而到了现在，“Skill”已经变成了一种独立的设计单元——一个可复用、可分享、可版本化的原子技能模块。你能把某个特定领域的知识、判断逻辑、处理步骤全部打包进一个目录，让Agent在需要时自动加载它。说白了，就是把“你会什么”拆成一个个可以按需调用的功能包。这篇文章就围绕我的实际项目经验，拆一拆Skill到底怎么设计、怎么写、怎么调优，以及在生产环境里让人头疼的那些坑。无论你是在做私人助理型Agent，还是在搞企业级自动化流程，这套方法论都能直接抄作业。

1. 从“提示词”到“Agent Skills”：这个概念的来龙去脉

1.1 为什么Agent只有“会说话”远远不够

我最早接触Agent开发的时候，思路非常简单：给模型写一大段系统提示词，把业务规则一条条列进去，然后让它根据用户输入自己发挥。初期demo阶段没毛病，模型确实能听懂人话、能调用几个API。但一旦进入真实业务场景，问题立刻就出来了：一是提示词越长，模型越容易“选择性失忆”，规则10条它记住6条，剩下4条靠猜；二是逻辑互相干扰，你让它同时会算工资、查库存、写周报，它经常把库存数字当成工资基数去算；三是完全没法复用，另一个项目想用你这段能力，只能整段复制再改改，改完又得重新调。

后来我开始琢磨，这不就是“内聚”问题嘛。你写代码都知道要高内聚低耦合，凭什么到了Agent Prompt这儿就允许一锅烩？所以“skills”这个概念一出现，我几乎是第一时间上手试。它的核心思路很简单：把一项能力涉及的指令、参数定义、脚本逻辑、参考示例打包成一个独立目录，Agent只有在用户需求命中这个技能范围时才会加载和调用。相当于把原来塞满系统提示词的“大杂烩”，拆成了一个个带标签的“专用工具箱”，需要哪个拿哪个。

这个转变带来的直接收益非常明显。第一，单技能的提示词上下文可以控制得很小，规则命中率高很多。第二，多个技能之间天然隔离，不再互相污染。第三，技能可以单独测试、单独迭代，甚至单独分发给别的Agent用。我接手过某个跨平台系统项目，里面塞了二十多个技能模块，每个模块的负责人都不一样，但整体调度依然很清晰，就是靠这种拆解。

1.2 Skills与Tools、Prompt、Workflow的边界划分

很多同学刚接触时会问：Skill和Function Calling的Tool有什么区别？和Prompt模板又有什么区别？和Workflow又有什么区别？这个问题我踩过不少次，先给出我目前项目中使用的划分标准。

Tool是“原子操作”，比如“查天气API”“发送邮件”“读写数据库”这类单个可执行动作。它没有业务判断，不关心调用时机，纯粹是模型的一个手脚延伸。Skill则是一整套“战术动作”，它内部可能要用到多个Tool，甚至要自己做逻辑分支。一个Skill是对“某类问题如何解决”的完整封装，而Tool是对“某个动作如何执行”的单一封装。

Prompt模板是“台词”，Skill是“剧本+演员+舞台调度”。一段Prompt只是告诉模型怎么说，但Skill会额外提供脚本、数据模板、校验逻辑和兜底策略。比如我做工时统计Skill的时候，Prompt里只写“把用户话术转成结构化记录”，但Skill的Python脚本会负责读日历、算时长、判重、推送结果，Prompt本身只是整个流程的入口。

Workflow则是“预先编排好的固定流水线”，步骤顺序是死的。Skill恰恰相反，它的步骤顺序不是固定的，而是由模型在执行时根据上下文动态决定。Skill更灵活，Workflow更可控。我个人的选型经验是：规则明确、步骤固定、不允许模型自由发挥的场景用Workflow；场景多变、需要模型理解语义后自主决策的场景用Skill。两者不是替代关系，而是互补关系。

2. 拆解一个Skill的标准结构：清单、模板和心智模型

2.1 Skill目录的标准结构与命名规范

一个Skill在物理上就是一个目录，目录结构直接决定你的项目能不能被框架正确识别，能否被团队其他人顺手维护。我目前的标准结构分为四块：清单文件、说明文档、脚本代码、参考资源。

SKILL.md是入口，描述这个Skill的意图、触发条件和使用规则，模型会优先读它。scripts目录存放可执行脚本，比如Python或Shell；参考资源包括示例数据、模板文件或小型知识库，按需加载。命名上建议小写字母加上短横线，比如time-tracker、weekly-report-generator，这样目录名就是天然的技能ID，日志里打印出来也干净。

我做技能库整理时吃过“命名不规范”的亏。早期有个技能叫“统计”，结果一个项目里三个“统计”含义完全不同，调度日志打出来没法区分，排查问题浪费了一整天。后来统一规定：目录名必须由“业务域+功能点”组成，如finance-payroll-calc、hr-leave-balance，且目录内必须维护依赖清单，脚本要写明需要哪些第三方库。这个规范看起来简单，但对于超过20个技能的项目来说，命名清晰度直接决定维护效率。

2.2 SKILL.md清单：从意图声明到参数Schema

SKILL.md是核心，我写的每一项都不能含糊，否则模型会不知道怎么触发、怎么传参。我的模板分四块：技能描述要能体现触发场景和效果，用一两句话说明这个技能会在什么情况下被调用；触发条件则用关键词或语义特征来辅助说明，帮助模型判断命中；参数定义用JSON Schema或YAML描述输入参数的类型、必填性、取值范围，直接决定模型提取参数的准确度；最后是使用约束，明确哪些情况必须拒绝执行、哪些数据不能写入、哪些步骤不能省略。

写技能描述很讲究措辞。你写“处理用户的工时信息”，模型可能在闲聊时也莫名其妙触发；你写“当用户提到打卡、工时、加班、调休等词，需要记录或统计工作时间时使用”，命中率能翻一倍。这是因为描述越靠近真实用户话术，模型越容易建立匹配关联。我后来会把历史对话里真实用户问法收集起来，直接塞进触发条件里当示例，比抽象描述有效得多。

参数Schema看起来很简单，但实际坑很深。模型提取参数本质上是“从自然语言中做信息抽取”，如果你的Schema给了模棱两可的定义，它就会给你模棱两可的结果。比如时间范围，不能只写“开始时间和结束时间”，要写明格式、时区、允许的粒度；必填参数缺失时，是要求追问用户，还是使用默认值，要在约束里写清楚。这些细节直接影响下游脚本能不能跑通。

2.3 脚本实现与资源文件打包的取舍

Skill里要不要写脚本，取决于能力复杂度。纯文本生成型技能，靠Prompt就能搞定；但是涉及计算、文件读写、外部接口调用的技能，必须写脚本。我自己的经验是：凡是结果需要精确数值或结构化数据的，都尽量用脚本，因为模型直接输出表格时经常出错，而把规则交给Python处理，结果完全可控。

脚本和模型之间的协作模式有标准的流程：模型解析用户意图并提取参数，以JSON格式传给脚本，脚本跑完后把结果返回给模型，模型再把结果转成自然语言回复用户。这里面有个特别重要的点：脚本做完核心计算，但最终“怎么说”仍然由模型负责。这种分工的妙处在于，数字永远是对的，话术永远是活的。

参考资源这块，我建议“能不放就不放，放就必须精准”。如果你把一个几百KB的知识库直接塞进技能目录，模型的上下文窗口再多也被占满了，检索效率不升反降。我遇到的实际情况是：一个约200条FAQ的知识库，单次加载约1万字符，处理每条工单的Token消耗上涨了20%左右，响应延迟也明显增加。后来我只保留高频的50条，配合语义检索，命中率反而提升了。资源文件应该追求“够用就好”，而不是“应有尽有”。

3. Skill是怎么被调起来的：加载、匹配与执行链路

3.1 意图匹配的几种机制与选型逻辑

Skill的调度机制，是整个体系最核心的一环。目前业界有大概三种匹配方式。

第一种是模型直接选择，框架把所有Skill的描述一次性给模型，模型根据对话内容做函数式调用。这种方式实现简单，但技能数量一多就会出现问题：上下文太长、Token开销大，而且相似技能之间模型容易选错。第二种是嵌入检索，每条Skill的描述做成向量索引，来了新请求先做相似度检索，取Top-3再给模型精排。可扩展性最好，适合技能数量大的项目。第三种是规则路由，走关键词、正则或分类器，适合触发条件非常明确的场景，零成本且稳定，但处理不了复杂语义。

我项目里的选型经验是：技能少于10个，用模型直接选择最简单；技能在10~30个之间，用嵌入检索做粗召回，人工写规则做硬约束；超过30个得考虑分层调度。我做过一个企业内部助理项目，技能超过30个，就是先用规则做第一层粗筛，再用向量检索做第二层召回，最后交还给模型确认，三管齐下才把准确率稳定在90%以上。

3.2 参数提取与校验：如何避免模型“乱填参数”

参数提取是Skill执行中最容易出问题的一环。用户说话往往是零散的，“帮我记一下昨天下午两点的工时，项目是数据分析”这算说得清楚的了，更常见的是“昨天下午干了俩小时活儿，给那个什么数据分析项目”，你让模型直接提取出结构化参数，它经常搞出幻觉，比如把“昨天”填成今天、把“俩小时”理解为120分钟还是2小时有歧义、项目名直接猜一个。

我常用的方案是三层校验。第一层是模型做初步提取，遵循Prompt约束；第二层是脚本侧做严格校验，类型不对就尝试解析修正，解析不了的直接返回“参数缺失”信号；第三层是让模型自己跟用户确认。这三层不是叠加而是递进关系：模型先猜，脚本猜得对不对，不对了就回问用户，而不是让模型瞎编。

有个参数细节很容易被忽略：时间表达。不同模型对“昨天下午”“上周五”这类相对时间的解析结果可能不同，和模型本身的训练数据有关。我在技能约束里会写清楚“所有时间统一换算成UTC时间戳再传给脚本”，脚本内部再转成本地时区。这样就能避免模型用训练时偏好的时区，导致计算出来的结果对不上。

3.3 执行沙箱与异常处理

Skill脚本能不能随便跑？当然不行，尤其是企业内部Agent要操作数据库、发邮件的时候，脚本一旦出错，后果很严重。我给每个技能的执行环境都套了沙箱：文件系统只读目录，网络白名单，CPU和内存限额。比如一个工时统计技能，它只需要读日历文件和写自己的输出目录，那就给它单独临时目录，脚本跑完自动回收。

还有一个我强烈建议加的东西：异常出口。每个Skill都要定义“执行失败后怎么处理”。我的做法是脚本里所有可能出错的地方都返回结构化错误码，并在技能描述里写清楚“如果脚本返回错误码E01，告诉用户无法连接日历服务；如果返回E02，提示用户参数有误”。这样即使用户遇到报错，模型也能用通俗语言解释，而不是甩出一堆堆栈信息。

4. 从零开发一个Skill的完整实操记录

4.1 选题与边界划定：为什么我选了“工时统计”

我拿一个真实做过的项目举例：某团队需要一个智能助理，能记录成员的工作时间、统计每日工时、生成周报。如果按老办法，我会把这个需求塞进系统提示词，要求模型既会聊天又会算数——结果可想而知，写出来的周报数据一塌糊涂。

这次我换成Skill方案。第一步是边界划分：这个Skill只负责“工时数据的录入与统计”，不负责“生成周报文案”。周报文案属于另外的技能，通过数据接口对接。这样划分的好处是，每个技能只解决一个问题，测试的时候只需要验证一组逻辑，不会互相拖累。

我提醒一下：你在做边界划定时，最容易犯的错是“一个技能塞太多职责”。比如又是统计工时，又是分析项目进度，又是预测延期风险。表面看是一条业务线，实际上这三件事的数据源、算法逻辑完全不同，硬要捏在一个Skill里，会让描述长得没法写，命中率也会下降很多。

4.2 编写SKILL.md与脚本的完整过程

Skill结构定好之后，就开始写清单文件和实现脚本。以工时统计技能为例，SKILL.md里描述写的是：当用户提到打卡、登记工时、填写工作记录、统计今天的工时、调整某条工时记录等需求时使用。触发条件里则明确了关键词和相近表达，参数Schema里定义了三个字段：日期范围、项目名称、工时数或时间段描述。约束里规定：如果用户没有提供日期，默认今天；如果工时数缺失，必须追问；相同项目和相同日期范围不允许重复记录。

脚本侧我用Python实现记录管理逻辑。写的时候特别注意：所有的输入经过了Schema校验，但脚本侧仍然做防线。比如日期字段，用datetime模块做严格解析；项目名称，用模糊匹配对齐到预置的项目列表上，匹配不上就返回错误码；工时时长统一换算成分钟数存储，这样后续计算不同量级的数据时就不容易搞混。

我用一个具体例子说明完整调用链路。某天我在对话中告诉助理“昨天下午写接口文档写了三个小时，项目是支付网关”，模型解析出参数：日期是昨天、项目是支付网关、时长是3小时，然后调脚本。脚本先做校验，确认支付网关在预置项目列表中，写入一条新的记录，返回成功。模型随后回复“已记录，昨天支付网关项目投入3小时”。整个过程完全不用用户感知到背后还有脚本层。

4.3 本地测试与调试方法

测试Skill，我有一套固定的操作流程。先在本地起一个最小环境，不接外部工具，把对话语料准备好，用几十条真实用户话术跑一遍，重点看三件事：触发准不准、参数提得对不对、脚本跑不跑得通。

参数提取我习惯写成自动化测试，把每条测试话术和期望提取的参数对应起来，跑完后对比差异。比如我有一批测试样本：话术A“记录一下周一的工时”期望日期是本周一；话术B“上周五下午干了俩小时”期望时长是120分钟。每次改Skill描述或Schema，就跑一遍全量测试，改坏了立刻能发现。

还有一类问题要特别留意，就是用真实数据调试时，模型可能会因为上下文里的干扰信息而传错参数。比如某次对话中提到“上次那个需求”，模型把“上次”误当成时间参数给填进日期里了。我排查后发现是因为Schema里有一个日期字段叫作“last_time”，模型看到“上次”这个词就直接往这个字段填。改名字加约束后就正常了。这告诉我：参数命名也要刻意避开那些有歧义的词。

5. 生产环境中的效果调优与踩坑实录

5.1 命中率不高怎么办：描述词与示例的优化

部署到真实环境后，很快收到反馈：有些明显应该命中技能的话术，模型就是不触发。我第一反应是框架问题，排查后发现一个更隐蔽的原因：测试集和真实用户话术的分布差太多。我测试用的都是完整规范的说法，但真实用户讲话特别随意，比如直接发“记一下”“干了半天活儿”“那个项目又拖了”这种碎片输入。

针对这种情况，最直接的办法不是改算法，而是去翻线上日志，把真实触发失败的案例收集起来，看模型卡在哪。然后根据案例去扩充描述。描述里加一些典型表达方式，将那些口语化、模糊的表达都列进去。模型本质上是在做文本匹配，你给的参考分布越接近真实数据，效果越好。这个工作没什么捷径，只能持续迭代。

另外一个坑是：多个Skill的描述如果写得过于相似，模型分不清该调哪个。比如你有个“工时统计”Skill，又有个“考勤管理”Skill，两者都可能涉及“打卡”这个词。我踩过这个坑后，会专门做一次“描述互斥检查”：把每个技能的描述拿去和所有其他技能描述作对比，语义太接近的就主动改写，增加区分度。对于容易混淆的场景，直接在描述里写避让规则，比如“如果用户是想查询上下班时间记录，请使用考勤管理技能”。

5.2 参数幻觉的排查与兜底

生产环境里最烦的就是参数幻觉，用户明明没说项目名，脚本端却收到一个“项目A”，细查发现是模型脑补的。我处理这个问题分两个方向：一是约束上强制，参数缺失时不准编造，必须回问用户；二是处理侧加兜底，脚本把所有参数标好来源，凡是模型提取的全都视为“待确认”状态，不能直接落库。

兜底策略我分三层：第一层是模型自检，Prompt里明确要求“如果参数是从上下文推断而来的，在传给脚本前标注来源”；第二层是脚本校验，对可疑参数做规则校验，比如项目名必须匹配预置列表，日期不能超出合理范围；第三层是人工兜底，对于置信度不高的记录，宁可多问一句也不要直接入库。宁可让用户觉得多了一步，也不能让污染数据进库里。真实业务中，数据错了后面纠偏的成本远高于当时多问一句的成本。

还有一个细节值得关注：模型对“默认值”的理解很飘。如果你在约束里写“日期缺省时默认今天”，它可能把“昨天下午”这个没有显式日期的输入也按“今天”处理。我的改进方法是：默认值的启用必须由脚本端来做，而不是让模型做。模型只要判断出用户有没有给日期，脚本再根据这个判断选择用“今天”还是报参数缺失，分工清楚了，问题自然就少了。

5.3 多Skill共存的冲突与优先级

当项目里的Skill数量多起来，它们之间的调用冲突是不可忽视的问题。比如有“工时统计”和“会议纪要”两个技能，用户说“下午开会讨论支付网关的工时怎么记”，模型可能同时触发两个技能，到底是先记工时还是先写纪要根据业务规则来做优先级排序。

我在架构上的处理是引入一个调度层，不直接让模型自由选。调度层维护一张优先级表，业务上的核心操作逻辑优先。当模型识别出多个技能命中时，调度层会给出一个明确的建议顺序，模型按规则执行，未经许可不得同时调用两个写操作型技能，避免并发写入造成数据覆盖。这条规则被写死在调度层代码里，不依赖模型自觉。

还有一种冲突是同一个技能的不同触发场景打架。比如Skill里有“新增工时”和“修改工时”两个意图，用户说“把昨天记的那个改成三小时”，模型可能匹配到“新增”意图，导致新插入一条错误记录。我后来把这类操作拆成两个子意图，并且给“修改”意图设置了更强的触发条件：只有检测到时间信息、项目名、原记录三者齐备时，才走修改流程，否则一律走新增确认。这个改动让误操作率下降了不少。

6. 常见问题速查表与个人使用心得

6.1 高频问题与解决方案对照表

我把日常运维中遇到的问题整理成了一个速查表，新团队成员接手时能快速上手排障。这张表覆盖了我个人和团队踩过的绝大多数坑，按线上发生率排序。

排查顺序上，先从触发开始。不触发就在描述和触发条件上找原因；触发了但结果不对，就检查参数提取；参数对了但结果不对，就查脚本处理逻辑。从外到内逐层定位，远比一次性从头到尾乱猜要快得多。

这里我想特别强调一点：不要一上来就怀疑框架有问题。我早期有次排查“技能偶发不调用”的问题，查了半天，发现是某个上游模型版本更新后对描述的理解方式发生了变化。这类问题的本质是你的技能描述和运行时模型的能力边界出现了错位。定期回归测试，把关键语料样本在每次模型版本升级后重跑一遍，比事后复盘优先级高得多。

6.2 我对Skill设计的一些个人体会

代码里的高内聚、低耦合原则，放到Agent技能设计里依然适用，这就是我在整个项目中最直观的体会。一个Skill就是一个微服务，它的描述是接口文档，Schema是请求协议，脚本是业务实现，约束是SLA。当你用微服务的思路去设计Skill时，很多困惑会自然消解：该拆多细、内外如何隔离、接口怎么定义、怎么测、怎么发布，这些问题都有了明确的答案。

另一个经常被忽略的点是：Skill不只是给模型用的，也是给人读的。你会发现，当你把一个领域知识整理成结构化的SKILL.md时，这个文档本身就是最好的项目知识沉淀。新人接手项目，先看有哪些技能，每个技能是干什么的、边界在哪里，很快就知道自己该改哪个文件。这比翻几万行系统提示词高效得太多。

最后再分享一个我最近在尝试的方向：Skill的版本管理与复用。目前我把一些与具体业务无关的通用技能，比如时间解析、数据格式化、邮件草稿生成，独立成了一个内部共享库，不同项目直接引用，通过对技能做来源追踪和变更记录，迭代新项目的时候少写了很多重复劳动。Skill这套思路完全可以走出单机助手，成为团队级、甚至组织级的“能力资产库”。你现在设计的每一个好Skill，都是在给未来的自己存下一份可复用的能力。