企业官网建设流程全解析

1. 从“会聊天”到“会干活”，只差一层skills

这两年做大模型应用，我最大的感受是：模型本身的推理能力早就不是瓶颈了，真正卡住项目进度的，是智能体怎么在真实业务里“干活”。

你可能也有过类似的体验——给GPT类产品接了一堆API，模型确实能理解用户意图，能把“帮我订周五去上海的机票”解析成结构化参数，但一落地就出问题：工具调用链路太长容易断、返回结果不稳定、加一个新接口就要改一大圈主逻辑。搞到最后，业务方抱怨“这玩意儿聊聊天还行，真让他办事儿不靠谱”，你也委屈，因为问题根本不在模型，而在你的Agent架构缺少一层标准化的能力封装层。

这个封装层，就是agent-skills在做的事。

我第一次看到agent-skills这个项目标题时，以为它又是一个“把工具函数注册给LLM”的轻量封装库。真正用下来才明白，它解决的是Agent工程化里一个更根本的问题：如何把零散的API调用升级为可编排、可复用、可治理的“技能资产”。今天这篇文章，我就结合自己上手agent-skills的实际经历，聊聊技能层到底怎么设计、怎么落地、生产环境里会踩哪些坑。

如果你正在做AI Agent相关的项目，被工具调用的稳定性、扩展性、可维护性折磨过，这篇文章应该能给你一些直接能落地的思路。

1.1 一个典型Agent项目的失控现场

先说一个我去年接过的真实项目。那是一个企业内部的IT运维助手，核心场景是员工用自然语言报障，比如“打印机连不上了”“申请开通数据库权限”，系统需要自动完成工单创建、知识库检索、权限系统对接等一系列操作。

最开始的结构很简单：把每个系统的API封装成函数，扔给LLM做function calling。几十个函数的时候，效果还不错。但随着场景增加，问题开始密集爆发：

第一，函数越写越臃肿。为了兼容不同用户的输入，每个函数里塞满了分支判断和默认值，动辄上百行。比如创建工单这个看似简单的函数，要处理加急、抄送、关联资产、选择审批流……代码迅速腐化。

第二，上下文被撑爆。每次对话把几十个函数的描述全部塞给模型，还没开始干活呢，2000多个token就没了，而且模型经常选错工具，因为在海量函数描述里，“相似”的函数太多了。

第三，完全没法复用。市场部想做一个类似的智能助手，但它们的系统不一样、流程不一样，代码拷贝过去要大改，改完又不敢动，一动就崩。

这其实不是个例。我观察过不少团队做大模型落地，前期demo跑得飞快，一进入生产环境就原形毕露，根本原因就是：工具层只解决了“能被调用”的问题，没解决“能被可靠地编排和治理”的问题。agent-skills的切入点，恰好就是这里。

1.2 agent-skills要解决的核心命题

再往前说一层。agent-skills这个项目，核心思想是把“技能”作为Agent能力的基本单位——一个技能不再是孤零零一个函数，而是包含了触发条件、输入输出Schema、执行逻辑、依赖资源、权限声明、版本信息等完整元数据的自包含单元。

这么设计的好处非常明显：Agent的主逻辑只需要维护一张“技能清单”，拿到用户请求后先做路由，把请求分发到对应的技能上，技能内部再自行决定调用哪些底层工具、按什么顺序调用。主流程和具体能力实现之间，被彻底解耦了。

以我的理解，agent-skills项目面向的读者画像很清晰：

• 已经过了“调通一个Agent demo”的阶段，正在往生产环境推的开发者
• 对function calling的局限性有切身感受，想找更系统化方案的架构师
• 需要在多个业务线之间复刻同一套Agent能力，同时对权限、审计有要求的团队

如果你只是想把一个聊天机器人接入微信公众号，那还用不上技能层这么重的抽象；但只要你做的Agent需要对接两个以上内部系统、需要处理超过二十个工具调用场景、需要多人协作维护，那技能层的价值就会立刻体现出来。

2. 先搞清楚：一个可用的Agent技能栈到底长什么样

聊概念容易飘，我们先拆结构。我在agent-skills里实际用下来，它的技能体系分成三个层级，有点类似编程里的“函数—模块—服务”的层次关系。

2.1 技能的三种粒度：原子、复合、业务

第一层是原子技能，粒度最小，对应一个具体的外部调用。比如“查询工单状态”“获取用户部门信息”“发送企业微信消息”。这一层做的事情很纯粹，就是定义“输入什么、调用哪个API、输出什么”，内部不做业务判断，保证每个技能都能被独立测试。

第二层是复合技能，它编排多个原子技能形成一条执行链路。比如“创建故障工单并通知主管”这个复合技能，内部就是“查询主管”→“创建工单”→“发送通知”三个原子技能的串行编排。这一层的价值在于，复杂的业务流程被固化成了可复用的“套路”，上层调用时不需要关心链路细节。

第三层是业务技能，它面向具体的业务场景，更像是Agent的一种“岗位能力”。比如“IT支持专家”这个业务技能，可能包含报障受理、知识库检索、权限申请审批等一整组复合技能和原子技能，并且定义了哪些场景归它处理、哪些场景需要移交。

我在自己项目里落地时的经验是：不要一上来就追求三层齐全，先用原子技能跑通最小闭环，等场景确实复杂了再逐级封装。层级太多，小团队会陷入过度设计的泥潭。

2.2 一个技能的结构化描述应该包含什么

在agent-skills里，一个技能的描述文件承担着“接口契约”的职责。我总结了一下，一个规范化的技能描述至少要包含以下字段：

这里尤其想强调description字段。它直接影响LLM的选型准确率。我见过太多人写description特别随意，比如“创建工单”就真的只写“创建工单”，结果模型在“创建工单”和“批量创建工单”之间反复横跳。正确写法应该是：“当用户报告设备故障或服务异常时调用，创建一条IT服务工单；若用户要求同时为多人报修，应使用批量创建接口，权限要求为it_operator及以上。”

2.3 为什么不能继续用裸函数硬扛

我知道肯定有人想说，这些功能我用函数+JSON Schema也能做，何必引入技能层？

确实，function calling本身就是一种技能调用机制，但它天然有几个短板。裸函数的描述和实现绑在一起，改造一个函数，描述就得跟着改，很容易出现“模型记住了旧描述、调用新函数”的错位。函数之间的编排逻辑散落在Agent主Promot里，靠自然语言约束，时间一长根本没法维护。函数没有版本、权限、审计这些治理概念，对于企业级应用来说是硬伤。

如果把function calling比作“把工具递给工人”，那么技能层就相当于“把工人的操作手册也一并定义好”——不仅知道有什么工具，还知道什么场景用什么工具、按什么顺序用、哪些人有权用。这一层抽象，才是Agent从玩具走向生产力的分水岭。

3. 技能设计的核心约束：让模型“用对”比“能调”更重要

这个部分聊聊我踩坑最多的地方，也是agent-skills这类项目最见功力的设计点——怎么保证LLM能稳定地选对技能、传对参数。毕竟技能再多，模型用错了就等于零。

3.1 单一职责：一个技能只做一件完整的事

很多人设计技能时容易走极端，要么把技能拆得特别碎，一个“查天气”都要分成“查温度”和“查湿度”；要么把技能堆得特别大，一个函数里什么都能干。这两种做法在生产环境都很痛苦。

我的经验是：技能的拆分标准不是“动作粒度”，而是“意图闭环”。用户说“帮我订个明天下午两点的会议室”，这应该是一个完整技能，内部可能涉及查会议室、订会议室、发通知三个原子操作。但如果把“查会议室”单独拆成一个面向用户的技能，就有点过了，因为用户一般不会只查不订，单独暴露反而增加了模型选错的可能性。

在agent-skills的体系里，判断一个技能是否拆分合理，可以看它的description是否足够“边界清晰”。如果你发现自己要在description里写一大堆“如果……但是……除非……”才能说清楚适用范围，那十有八九是技能职责定宽了，该拆。

3.2 输入输出的Schema化：一切歧义都应在入口被消灭

第二个核心约束是，技能的输入输出必须严格Schema化。这个“严格”不是指字段类型写清楚就够了，而是要在Schema层面就把歧义消灭掉。

举个例子，很多系统的工单优先级是字符串枚举：low、medium、high。如果实参直接让LLM填，就经常出现LOW、High、紧急这类鬼东西。在agent-skills里，正确的做法不是靠Prompt约束模型“请使用小写枚举值”，而是把输入Schema的枚举定义清楚，同时在服务端做归一化兜底。

我自己在项目里常用的模式是：输入字段能枚举就枚举，不能枚举就加正则约束加示例值。比如时间字段，Schema里写清楚格式是YYYY-MM-DD HH:mm:ss，并附上一个示例值。模型看到示例值后，传错的概率会显著下降，这是实测得出的经验。

3.3 自包含：技能不隐式依赖“外部状态”

第三个约束，可能是新手最容易忽略的，就是技能的自包含性。一个技能应该自带运行所需的全部信息，不能偷偷依赖某个全局变量、某条Memcached缓存或者某个“肯定会存在的”会话状态。

我在早期版本里犯过一个经典错误：为了让“创建工单”技能拿到操作人信息，我直接去读Agent会话上下文里的user_id字段。Demo跑得好好的，上线后频繁报错，排查半天才发现，有几个入口走了异步通道，会话上下文里的user_id压根没传进去。后来改成：技能入口处显式声明operator_id为必填参数，由上游负责注入，一切问题迎刃而解。

技能自包含带来的另一个好处是可测试性。每个技能都能脱离Agent主流程单独跑通测试，这在多人协作时的价值难以估量——你可以给后端同学一个技能清单，让他们针对每个技能写单测，而不需要理解整个Agent的调度逻辑。

4. 技能注册、加载与编排：工程上的落地链路

前面讲了技能长什么样，接下来聊agent-skills在工程上是怎么把这些技能组织起来运转的。这部分属于“骨架”级的内容，掌握了它，你就能在自己的项目里搭建一套哪怕不用agent-skills、也能借鉴的技能管理框架。

4.1 技能注册中心：让Agent知道“我有什么牌可打”

在agent-skills的架构里，所有技能不是散落在代码里，而是注册到一个技能注册中心。这个中心维护着一张完整的技能清单，每个技能包含描述文件、可执行代码、版本号、依赖关系等元数据。

当Agent启动时，它并不会把全部技能描述加载进上下文，而是按需加载。具体来说，系统会先加载一个“技能路由索引”——每个技能的名称、描述、适用场景的超精简版——用来做初筛；命中候选集后，再把候选技能的全量Schema加载进LLM上下文。这套“二级检索”机制，是控制token消耗的关键设计。

我做过一个粗略的量化：一个全量技能描述平均约1500字符，50个技能就是7.5万字符，约等于2万token，光描述就把上下文吃掉一半。而用路由索引后，初始上下文只有3000字符左右，效果差异非常明显。所以如果你在自研Agent框架，请务必考虑技能的全量加载与按需加载，而不是一股脑全塞进去。

4.2 技能执行的统一调用协议

技能执行部分的工程实现，是agent-skills最值得借鉴的地方。它的调用协议可以简化成三段式：路由匹配、参数组装、结果归一化。

路由匹配阶段，系统根据用户请求和技能路由索引，选出候选技能，这一步可以由LLM做，也可以用更轻量的规则、向量检索甚至分类模型做，各有利弊：

参数组装阶段，系统从用户输入和上下文里抽取技能所需参数，并做格式校验。这一步的工程要点是：校验不通过时，不要直接调API，而是返回“参数缺失”状态，由上层Agent发起追问澄清。很多Agent项目翻车就翻在参数校验上——参数错了，但代码继续往下走，等到API报错才暴露，这时返回给用户的报错信息已经没法看了。

结果归一化阶段，不同后端API的返回结构五花八门，统一转成技能定义的标准输出，包含状态码、业务数据、错误信息和耗时。Agent主流程只认这个标准结构，后端接口再怎么变，都不会影响上层逻辑。

4.3 技能编排：把原子技能串成业务场景

编排是让Agent真正“会干活”的关键。

在agent-skills里，复合技能通过一个简单的DSL来描述步骤之间的依赖关系。比如前面提到的“创建故障工单并通知主管”，它的编排描述大致是这样的：

name: it_ticket_create_and_notify version: 1.0.0 steps: - id: lookup_manager skill: it_user_lookup input: user_id: "${params.reporter_id}" relation: "manager" - id: create_ticket skill: it_ticket_create input: title: "${params.title}" severity: "${params.severity}" reporter_id: "${params.reporter_id}" depends_on: [] - id: notify_manager skill: im_message_send input: target: "${lookup_manager.output.user_id}" content: "工单 ${create_ticket.output.ticket_id} 已创建" depends_on: - lookup_manager - create_ticket

变量${...}在运行时被真实值替换，depends_on声明步骤依赖。这个DSL本身很简单，但它带来了一个关键能力——步骤级别的可观测性。每一步的执行耗时、成功失败、耗时分布都被记录下来，哪天流程慢了，一眼就能看出是查主管耗时长，还是发通知耗时长。

这种“编排即配置”的思路，比我之前用纯代码硬编码流程要灵活太多。流程调整时不用改主程序、不用重新发布，改一下DSL配置就能生效，对业务频繁变化的企业场景来说非常实用。

5. 从零落地一个技能：请假助手接线全过程

光讲理论容易虚，我拿一个我自己完整跑通过的例子，把agent-skills的实际开发流程过一遍。这个例子很典型——给企业微信里的员工助理添加一个“请假申请”技能。它不复杂，但覆盖了技能开发的所有关键环节。

5.1 需求拆解与技能边界定义

首先明确业务需求：员工在对话框里说“我明天请一天病假”，系统需要完成三件事——校验员工身份、检查剩余年假/病假额度、写入请假系统并通知直属主管。

这三件事天然就是两个技能：

• leave_capacity_query：查询员工可用假期额度，原子技能
• leave_request_create：创建请假申请并通知主管，复合技能，内部调用额度校验、创建申请、查主管、发通知四个原子技能

注意，我并没有把“通知主管”单独拆出来，因为它不是一个独立的用户意图，而是创建请假单的流程副作用。如果单独暴露，模型就会出现在“用户没要求通知主管”的情况下，偷偷多调用一个技能，这在实际使用中很让人头疼。

5.2 技能描述与Schema的编写细节

下面这个例子是我在项目里最终采用的技能描述。这里我强烈建议尽量写得详细：哪些情况该用、哪些情况不该用、用什么语气处理、有什么硬限制。

{ "name": "leave_request_create", "description": "当用户申请请假时调用此技能。支持病假、事假、年假、婚假、产假等类型。若用户未说明具体请假日期，应主动询问起止日期后再调用。此技能会自动校验假期额度，额度不足时返回 business_error，不要强行创建申请。", "input_schema": { "type": "object", "properties": { "leave_type": { "type": "string", "enum": ["sick", "personal", "annual", "marriage", "maternity"], "description": "请假类型" }, "start_date": { "type": "string", "format": "YYYY-MM-DD", "description": "请假开始日期，如 2025-06-01" }, "end_date": { "type": "string", "format": "YYYY-MM-DD", "description": "请假结束日期，含当日，如 2025-06-03" }, "reason": { "type": "string", "maxLength": 500, "description": "请假原因，可选，但不能为空字符串" } }, "required": ["leave_type", "start_date", "end_date", "reason"] }, "output_schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["success", "business_error", "system_error"] }, "leave_id": { "type": "string", "description": "创建成功后的申请单号" }, "message": { "type": "string", "description": "给用户看的提示信息" } } } }

几个容易被忽略的细节：

• format字段我标注了具体格式并给了示例。LLM对日期格式的敏感度比想象中低，不给示例就敢给你传“2025年6月1日”。
• description明确写了“额度不足时返回business_error，不要强行创建申请”。这是避免模型在业务报错后仍然尝试重试的关键。
• 所有字段都写了描述，即使是reason这种看着就懂的字段。别嫌啰嗦，模型真的会因为字段描述不清晰而传错。

5.3 技能代码骨架与执行逻辑

技能的执行体是一个类，核心方法是execute(params, context)。我习惯把所有外部依赖（HTTP客户端、数据库连接等）都通过构造函数注入，而不是在方法内部直接import，方便单测。

# file: skills/leave/leave_request_create.py from skills.base import BaseSkill class LeaveRequestCreateSkill(BaseSkill): name = "leave_request_create" version = "1.0.0" def __init__(self, hr_client, im_client, org_client): self.hr_client = hr_client # 人事系统客户端 self.im_client = im_client # 即时通讯客户端 self.org_client = org_client # 组织架构客户端 def execute(self, params: dict, context: dict) -> dict: operator_id = context["operator_id"] # 1. 查询假期额度 capacity = self.hr_client.query_capacity( user_id=operator_id, leave_type=params["leave_type"] ) if capacity < self._calc_days(params["start_date"], params["end_date"]): return self._error("business_error", f"假期额度不足，剩余额度 {capacity} 天") # 2. 创建请假申请 leave_id = self.hr_client.create_leave_request( user_id=operator_id, leave_type=params["leave_type"], start_date=params["start_date"], end_date=params["end_date"], reason=params.get("reason", "") ) # 3. 查找直属主管 manager_id = self.org_client.get_manager(operator_id) # 4. 发送通知 self.im_client.send_message( target=manager_id, content=f"您的下属 {operator_id} 提交了{params['leave_type']}请假申请，单号 {leave_id}" ) return self._ok({ "leave_id": leave_id, "message": "请假申请已提交，请等待审批" })

这段代码本身不复杂，我想强调的是返回状态的设计。我把返回分成success、business_error、system_error三种：

• business_error：业务规则拒绝，比如额度不足，此时上层Agent应该直接告诉用户原因。
• system_error：外部系统异常，此时上层Agent应该重试或用兜底话术。

这个区分极其重要。如果不区分，模型会把“额度不足”和“系统崩溃”一视同仁，然后一本正经地告诉用户“系统繁忙请稍后再试”，非常业余。

5.4 联调中的意外发现与应对

这个技能上线前，我在联调时发现了一个很有意思的问题：当用户说“我想请个假”但没说请假类型时，模型经常直接调用技能并传一个默认的annual类型，而不是先追问用户请什么假。

原因在于input_schema里把leave_type设成了必填，但模型为了“完成用户请求”，会自作主张地填一个默认值。这个行为很微妙：Schema要求必填，模型理解到了，但它在“追问用户”和“猜一个值”之间倾向于后者，尤其是在你指示它“尽量完成任务”的时候。

解决办法是在description里明确加上一句：“如果用户未明确请假类型，不要猜测，必须先向用户确认。”是的，这种“人之常情”必须显式写进描述里，模型才不会自说自话。这也再次印证了：在Agent技能设计里，description就是在跟模型“签合同”，条款写得越清楚，模型越守规矩。

6. 技能从“能用”到“好用”：生产环境的治理经验

开发环境跑通技能，只是万里长征第一步。真正折磨人的是上线之后——技能之间的权限边界、调用量的波动、其他人接手维护时的混乱。这一节聊聊agent-skills在生产环境给我最有价值的几个启发。

6.1 技能权限与操作者身份透传

企业级Agent绕不开权限问题。员工助理能查自己的假期额度，但不能查别人的；能提单，但不能审批。在agent-skills里，技能执行时不再从会话上下文里隐式取身份，而是通过调度层显式注入operator_id和permission_token。

这个设计在最初看起来确实有点麻烦，每个技能都要声明自己需要哪些权限，调度层要做一层权限校验，通不过就直接拦截。但上线后你会发现，这个“麻烦”是必须的。否则技能越加越多，迟早会出“低权限用户通过Agent调用了高权限接口”的事故。一旦出现，性质就不是技术事故，而是安全漏洞了。

我的习惯是在技能描述里再加一段required_permissions字段，调度层在路由阶段就做预校验，而不是等到技能执行一半再失败。拦截得越早，用户体验越好，对账也更容易。

6.2 技能的版本与灰度发布

技能是会演进的。今天leave_request_create还在用V1接口，明天HR系统升级，返回结构变了，不能直接改线上代码。agent-skills的技能注册中心天然支持多版本共存，一个技能可以有v1、v2两个版本同时在线，按用户白名单做灰度。

灰度切流的具体做法是：注册中心里每个技能版本有一个weight参数，调度层按比例分配流量。比如先给v2配5%的权重，观察错误率和API响应分布，稳定了再逐步加大，最后再把v1下架。

这一点对To B项目尤其重要——Agent一旦接入了生产系统，它就不再是一个“实验性玩具”，而是核心业务流程的一部分。所有线上变更都要有回退方案，技能版本化就是Agent界的“基础设施”。

6.3 技能调用的可观测性：每一步都是可以回溯的

最后一个治理维度是可观测性。我见过太多Agent项目出问题时排查无门——模型到底选了哪个技能？参数传的是什么？哪一步服务超时？返回给用户的是什么？全都是一笔糊涂账。

agent-skills的做法是：每个技能的每次调用，都会记录一条包含路由结果、参数、执行步骤、耗时、返回值的完整调用链日志。配合可视化看板，每天都能看到技能调用成功率、平均耗时、主要失败原因。这些数据不仅是排查工具，还是技能优化的依据。

例如我发现某个技能的average耗时从800ms涨到了2.5s，查看调用链后发现，是依赖的某个下游API在下午时段响应变慢，于是调度层针对这个技能加了下午时段超时重试的配置。这些优化完全基于可观测数据，而不是靠拍脑袋。

我真心建议所有做Agent的团队，从第一天就把日志和埋点做起来，哪怕前期简陋一点，也比上线后“两眼一抹黑”强得多。要知道，Agent领域的故障排查，比传统后端要复杂得多——你不仅要查代码，还要查模型“当时是怎么想的”，没有调用链日志做支撑，几乎无从下手。

7. 高频踩坑实录：我把生产环境的雷挨个踩了一遍

这一节算是我个人经验的“高危清单”。这些坑，单独看都不大，但组合在一起，足以毁掉一个Agent项目的上线节奏。

7.1 描述冲突导致的技能误调用

第一个坑是技能之间描述边界模糊。我一开始给“查天气”和“查空气质量”两个技能写的description分别是“查询指定城市当前天气情况”和“查询指定城市当前空气质量”，结果模型经常用“查空气质量”技能回答“今天天气怎么样”的问题，因为描述里都出现了“查询”“城市”“当前”这些词，模型分不清边界。

后来我把两个描述重写为：“当用户询问温度、降水、风速等气象要素时使用”和“当用户询问PM2.5、AQI等空气污染指标时使用”，并各自加了正例和反例，误调用率直接下降。描述中的动词和名词越具体，模型越不容易混淆。

7.2 参数默认值的隐藏风险

第二个坑是给可空参数设默认值。我之前为了“用户体验”，在leave_request_create里把reason字段默认成“无”，想着用户不填就不填吧。结果模型越来越懒，经常不追问理由，直接传一个“无”上去。提交的请假单全是“无”，HR那边炸了。

这个问题本质上不是你写了默认值，而是“默认值给了模型偷懒的许可”。后面我把reason设成必填，模型就会主动追问原因。类似的经验是：在技能设计里，语义上的必填项必须是Schema上的必填项，不要为了流程顺畅而在代码里补默认值，否则模型迟早会用默认值糊弄你。

7.3 长技能链路缺乏断点续跑

第三个坑是长链路技能的“一损俱损”。一个复合技能如果内部串了五个原子技能，中途第三个失败，整个技能就返回失败，用户只能重新来。这在“查额度→建申请→查主管→发通知”链路里，经常出现“申请已创建，但通知没发出去，整体返回失败”的怪状，用户一看失败就重试，结果创建了两个工单。

这是在agent-skills里需要特别警惕的，复合技能不是简单的串行“流水线”，要针对步骤依赖设计补偿逻辑。我的修复方案是：把“发通知”改成非阻塞步骤，即使发送失败，技能仍然返回成功，但把notification_sent: false放在结果里，由上层Agent决定是否补充提醒。别小看这个设计，在真实业务里，这避免了一大批重复工单。

7.4 围绕工具链的成套选型

最后补充一点工具链层面的经验。agent-skills的执行调度和注册中心，不一定非要整套自研或者整套照搬某个现成框架。我的做法是：沿用已有的LLM网关做模型路由，技能注册中心用了轻量级的配置存储，技能的API编排直接用Python实现，整体架构并不复杂。真正复杂的是协议设计和治理机制，而这两点，参考agent-skills这类项目的现成约定，是最省力且相对稳固的。

8. 如果让我重做一遍，我会怎么设计技能体系

写到这里，我想把几个“如果重新来一次”会坚持到底的设计原则，作为压轴内容分享出来。这些原则适用于任何基于LLM的Agent项目，不局限于某一种具体框架。

8.1 先定协议，再写代码

设计技能层的第一步，不是写代码，而是先定协议：技能描述长什么样，输入输出格式怎么约束，错误码怎么分类，调用链日志字段怎么定义。协议是整个体系的宪法，一旦定了后面就照着执行。

我见过太多团队一上来就写工具函数，等写了三十个函数后，才发现调用方和被调用方对错误语义的理解完全不同，不得不回头统一协议，重构成本巨大。agent-skills这类项目最大的价值，其实不是它的代码，而是它定义的那套协议规范，那是无数实践沉淀下来的“正确答案”。

8.2 保持技能的可替换性

技能层最忌讳的一件事，就是技能实现和技能定义深度耦合。我坚持的原则是：技能的调用方式永远不变，变的只能是内部实现。

比如leave_request_create从HR系统V1迁移到V2，内部代码全换，但对外暴露的输入输出、错误语义，一个字都不改。做到这一点后，你会发现技术升级、供应商切换都变得很从容——因为替换的是一个“技术细节”，而不是动整个业务链路。这也让多团队协作时互相不阻塞。

8.3 用数据推翻“我觉得”

最后一条，可能也是最反常识的一条：在Agent技能优化这件事上，我逐渐不再依赖自己的直觉和“我觉得”。

以前我总喜欢靠“猜”来优化：觉得模型选错技能了，就改description；觉得某个参数传错了，就加提示。但做了几个项目后，我发现自己多数时候都猜得不够准。反而是调用链日志和分析数据更能说明问题。

比如通过数据分析，我发现某个技能失败率高，不是因为模型选错，而是因为用户在凌晨发起大量请求，而下游系统在凌晨做数据备份，响应特别慢。这个结论靠直觉是永远发现不了的。所以，把可观测性建设前置，让数据帮你决策，是Agent工程化最值得投入的地方。

如果说技能层让Agent“手上有活”，那么可观测性就是让你“心里有数”。两者缺一，Agent落地就始终是一场豪赌。

我用agent-skills改造自己的项目也有几个月了，最直观的感受是：新增一个业务场景的接入成本大幅下降，不再需要改动Agent主逻辑，只需要写一个新的技能注册进去。后续我还会在技能编排和补偿机制上继续深挖，到时有新的实战经验再回来补充。