企业官网建设流程全解析

1. 从"agent-skills"这个标题说起：一个被低估的工程化命题

第一次看到"agent-skills"这个标题的时候，我脑子里冒出来的第一个念头不是"又一个Agent框架"，而是"终于有人把这件事单独拎出来讲了"。过去一年多，我陆陆续续接触过十几个跟智能体相关的项目，从最简单的对话机器人到能自己调工具、自己规划任务的多步执行系统，踩过的坑加起来能写一本小册子。而其中绝大多数坑，归根结底都不是模型能力不够，而是"技能"这一层没设计好。

所谓agent-skills，直白点说，就是给一个智能体配备的"能力包"。你可以把它想象成一个刚入职的新员工：脑子再聪明，如果没人告诉他公司有哪些系统、每个系统的入口在哪、遇到什么情况该走什么流程，他照样干不了活。模型本身是那个"脑子"，而skills就是那本员工手册加上一整套工具箱。这个标题背后真正要解决的问题是：如何把零散的、可复用的能力，以一种结构化、可插拔、可组合的方式，挂载到智能体身上，让它在面对不同任务时能按需调用，而不是把所有逻辑都塞进一个巨大的提示词里。

这件事听起来简单，做起来极其琐碎。我见过太多项目，一开始就是把所有工具描述一股脑写进system prompt，工具少的时候还能跑，一旦超过十个，模型就开始犯迷糊：该调A的时候调了B，参数传错，或者干脆该调工具的时候跟你聊天。这不是模型笨，是技能的组织方式出了问题。所以agent-skills这个主题，适合所有正在做智能体落地的人——不管你是刚入门想搞清楚概念，还是已经做过几个Demo正在头疼怎么规模化，都能从中找到对应的参考点。

接下来我会从设计思路、核心细节、实操落地、问题排查几个层面，把这个主题彻底拆开讲一遍。内容会偏工程实践，少讲虚的，多讲我实际试过、验证过的东西。

2. 整体设计思路：为什么技能要"包"起来而不是"堆"进去

2.1 技能的本质是一次能力抽象

在动手写任何代码之前，得先把"技能"这个概念想清楚。我的理解是：一个skill就是一次能力抽象，它把"完成某件事所需要的全部信息"封装成一个自包含的单元。这个单元至少包含四样东西——技能的名字、它解决什么问题（描述）、调用它需要什么输入（参数schema）、以及调用之后会发生什么（执行逻辑和返回格式）。

为什么强调"自包含"？因为智能体在运行时的决策依据，本质上就是它能看到的信息。如果技能的信息散落在提示词的不同角落，模型拼凑起来就容易出错。把每个技能做成一个独立单元，模型在需要的时候只需要看这一个单元，认知负担就小很多。这跟人处理任务是一个道理：你让我同时记住二十件事的细节，我肯定乱；但如果你给我二十张卡片，每张卡片写清楚一件事，我按需翻看，就从容多了。

这里有个常见的误区，就是很多人把skill等同于"一个函数"。函数只是执行部分，真正的skill还包括了给模型看的元信息。元信息写得好不好，直接决定了模型会不会在正确的时机调用它。我踩过的一个坑就是：早期写的技能描述太技术化，比如"执行HTTP请求并返回JSON"，模型根本不知道什么时候该用它。后来改成"当需要从某个网址获取最新数据时使用"，调用准确率立刻上来了。所以技能抽象的第一原则是：描述要面向"什么时候用"，而不是"它是什么"。

2.2 分层设计：把技能分成"原子"和"组合"两层

技能一多，就会面临一个选择：是全部平铺，还是分层？我的经验是必须分层，而且要分成至少两层——原子技能和组合技能。

原子技能是最小可执行单元，比如"读取一个文件""发送一条消息""查询一次数据库"。它们的特点是单一职责、参数简单、无副作用或副作用明确。组合技能则是由多个原子技能编排而成的，比如"生成一份周报并发送给相关人"，它内部可能先查数据、再生成文本、再发送。组合技能对模型暴露的接口更粗粒度，模型不需要关心中间步骤。

为什么要这么分？因为模型在不同场景下的"注意力预算"是有限的。面对一个复杂任务，如果只给它原子技能，它得自己规划一长串调用，中间任何一步出错都会导致整体失败，而且调试起来极其痛苦。如果只给它组合技能，灵活性又不够，遇到稍微变化的需求就抓瞎。两层结构的好处是：常用流程固化成组合技能，保证稳定性；边缘情况用原子技能兜底，保证灵活性。

我做过一个对比实验，同样的任务，纯原子技能方案的成功率大概在六成左右，而两层结构能到八成五以上。差距主要来自中间步骤的容错——组合技能内部可以做重试、可以做参数校验，而模型自己编排的时候这些都得靠它"自觉"。

2.3 注册与发现机制：让技能"可插拔"

技能包设计好之后，下一个问题是：怎么让智能体知道有哪些技能可用？最土的办法是硬编码，把所有技能写死在代码里。这在技能数量少的时候没问题，但一旦要支持动态扩展，就完全不够用了。

我的做法是引入一个注册中心。每个技能在初始化的时候，把自己的元信息注册进去，智能体在运行时通过查询注册中心来获取当前可用的技能列表。这样做有几个好处：第一，新增技能不需要改动智能体核心代码，只要注册就行；第二，可以根据运行环境动态开关某些技能，比如在测试环境禁用发送真实消息的技能；第三，可以对技能做权限控制，不同角色的智能体看到的技能列表不一样。

注册中心的数据结构其实很简单，就是一个字典，key是技能名，value是技能的元信息和执行入口。但就是这么个简单的东西，让整个系统的可维护性上了一个台阶。我后来把这个模式复制到了好几个项目里，屡试不爽。

提示：注册中心一定要做技能名的唯一性校验。我遇到过两次因为技能重名导致调用错乱的问题，排查了大半天才发现是两个模块注册了同名技能。加一行校验代码就能避免的事，别省。

3. 核心细节解析：一个技能包到底该包含什么

3.1 技能描述：写给模型看的"使用说明书"

技能描述是整个skill里最容易被忽视、但影响最大的部分。它直接决定了模型在什么时机、以什么方式调用这个技能。我总结了几条写描述的经验：

第一，用"当……时使用"的句式开头。这比"这个技能用于……"更能触发模型的调用判断。因为模型在做决策时，本质上是在匹配"当前情境"和"技能适用情境"，前者是情境描述，后者也应该是情境描述，匹配起来更直接。

第二，描述里要包含反例。也就是明确告诉模型"什么情况下不要用这个技能"。比如一个"发送邮件"的技能，描述里可以加一句"如果只是需要生成邮件内容而不需要实际发送，请使用文本生成技能"。这一句话能挡掉相当一部分误调用。

第三，控制描述长度。太短信息不够，太长又会稀释关键信息。我的经验是控制在两到四句话，大概五十到一百字之间。超过这个范围，模型抓重点的能力会下降。

下面是一个我实际用过的描述模板，你可以直接参考：

技能名：query_user_info 描述：当需要获取某个用户的详细信息（如昵称、注册时间、等级）时使用。 输入为用户ID，返回结构化的用户信息。 如果只是需要用户ID而不需要详细信息，不要调用此技能。

3.2 参数Schema：把"传什么"说清楚

参数定义是另一个重灾区。很多人写参数就是列个名字加个类型，结果模型传参的时候各种离谱——该传字符串的传了数字，该传数组的传了单个值，必填项不填，选填项乱填。

我的做法是用JSON Schema来定义参数，而且要把每个字段的描述写清楚。描述里要说明这个参数是什么、格式要求、有没有默认值、取值范围。举个例子，一个"设置提醒"的技能，时间参数如果只写"type: string"，模型可能传"明天下午"这种自然语言；但如果描述里写"格式为ISO 8601，例如2024-01-01T09:00:00"，模型传参的准确率会高很多。

必填和选填的区分也很关键。必填参数如果模型没提供，执行层要能明确报错并告诉模型缺了什么，而不是默默用一个错误的值继续跑。我见过一个项目，必填参数缺失时默认传了空字符串，结果技能执行成功但结果是错的，这种"静默失败"最难排查。

3.3 执行逻辑：幂等性和超时是两条生命线

技能的执行逻辑，除了实现功能本身，有两个工程属性必须考虑：幂等性和超时。

幂等性指的是同一个技能用同样的参数调用多次，结果应该一致。为什么重要？因为智能体在遇到不确定的情况时，可能会重试。如果技能不幂等，重试就会产生副作用——比如重复发送消息、重复扣款。对于有副作用的技能，要么设计成幂等（比如发送前先检查是否已发送），要么在描述里明确标注"此技能不可重复调用"，让模型谨慎处理。

超时是另一条生命线。技能执行如果卡住，整个智能体就会挂起。我的做法是给每个技能设置一个合理的超时时间，超时后返回明确的错误信息，让模型决定是重试还是换方案。超时时间怎么定？看技能类型：本地计算类可以短一点，几秒；网络请求类给十几秒；涉及人工审核的另说。关键是别用默认的"无限等待"。

3.4 返回格式：结构化优于自然语言

技能返回给模型的结果，格式很重要。我的强烈建议是：能用结构化数据就用结构化数据，别返回一大段自然语言。原因很简单，结构化数据模型解析起来更准，而且方便后续技能继续处理。

比如查询用户信息，返回{"name": "张三", "level": 5, "registered": "2023-01-01"}就比返回"该用户名叫张三，等级5，注册于2023年1月1日"要好。前者模型可以直接提取字段，后者还得做一次理解。

当然，如果返回内容本身就是给用户看的文本，那自然语言没问题。关键是要区分"给模型看的中间结果"和"给用户看的最终输出"，两者格式要求不一样。

4. 实操落地：从零搭一个技能包系统

4.1 目录结构：让技能"住"得有秩序

动手之前先把目录结构定好，这能省掉后面大量的整理工作。我用的结构大概是这样：

skills/ __init__.py registry.py # 注册中心 base.py # 技能基类 atomic/ # 原子技能 read_file.py send_message.py query_db.py composite/ # 组合技能 weekly_report.py onboard_user.py

每个技能一个文件，文件名就是技能名。这样做的好处是查找方便，而且新增技能的时候照着现有文件抄一份改改就行，心智负担低。registry.py负责扫描目录、加载技能、注册到中心。base.py定义技能基类，规定每个技能必须实现的方法，比如get_metadata()和execute()。

我试过把所有技能写在一个大文件里，刚开始还行，超过十个技能之后那个文件就没法看了。拆成独立文件之后，维护成本直线下降。

4.2 技能基类：统一接口是复用的前提

基类的设计决定了所有技能的"长相"。我的基类大概长这样：

class BaseSkill: name = "" description = "" parameters = {} timeout = 10 idempotent = True def get_metadata(self): return { "name": self.name, "description": self.description, "parameters": self.parameters, } def execute(self, **kwargs): raise NotImplementedError

每个具体技能继承这个基类，填上自己的元信息，实现execute方法。这样做的好处是注册中心可以用统一的方式处理所有技能，不用关心具体实现。而且新增技能的时候，只要照着基类的字段填，不会漏掉关键信息。

参数校验我放在基类里做了一层统一处理：execute被调用之前，先检查必填参数是否齐全、类型是否匹配，不通过就直接返回错误，不进入具体逻辑。这样每个技能就不用重复写校验代码了。

4.3 注册中心的实现：简单但别简陋

注册中心的代码量不大，但有几个细节要注意。核心逻辑就是维护一个字典，提供注册、查询、列出三个方法。我额外加了两个功能：一是技能启用开关，二是调用日志。

启用开关是为了应对不同环境。比如开发环境不想真的发消息，就把send_message技能关掉，模型查询可用技能列表时就看不到它，自然不会调用。调用日志则是为了排查问题，每次技能被调用，记录下技能名、参数、返回结果、耗时。出问题的时候翻日志，比猜快得多。

class SkillRegistry: def __init__(self): self._skills = {} self._enabled = {} def register(self, skill): if skill.name in self._skills: raise ValueError(f"技能重名: {skill.name}") self._skills[skill.name] = skill self._enabled[skill.name] = True def list_available(self): return [ s.get_metadata() for name, s in self._skills.items() if self._enabled.get(name) ] def call(self, name, **kwargs): skill = self._skills.get(name) if not skill or not self._enabled.get(name): return {"error": f"技能不可用: {name}"} # 参数校验、超时控制、日志记录... return skill.execute(**kwargs)

这段代码我用了很久，基本没大改过。简单的东西往往最耐用。

4.4 组合技能的编排：把原子技能串起来

组合技能的价值在于把常用流程固化下来。实现方式有两种：一种是用代码硬编排，一种是用配置描述编排。我倾向于前者，因为代码更灵活，能处理各种边界情况。

以"生成周报"为例，组合技能内部大概是：先调用query_db拿到本周数据，再调用generate_text生成报告文本，最后调用send_message发送。每一步之间可以做数据转换、可以做条件判断、可以做重试。这些逻辑如果让模型自己编排，它得调用三次技能，中间还得自己处理数据格式，出错概率高得多。

组合技能对模型暴露的接口就一个：给它一个用户ID和时间范围，它返回"周报已发送"。模型不需要知道内部发生了什么。这就是抽象的价值。

注意：组合技能内部调用原子技能时，建议绕过注册中心直接调用，避免日志重复记录和权限检查的额外开销。注册中心是给模型用的入口，内部编排走内部通道。

4.5 与智能体的对接：把技能列表喂给模型

最后一步是把技能列表交给模型。具体做法是在构造提示词的时候，把registry.list_available()的结果序列化后塞进去。模型看到技能列表，就知道自己有哪些能力可用。

这里有个细节：技能列表不要一次性全塞。技能少的时候无所谓，技能多了之后，提示词会变得很长，既浪费token又稀释模型注意力。我的做法是按需加载——先根据任务类型筛选出相关技能，只把这一部分给模型。比如任务是"处理用户咨询"，那就只加载查询类技能，发送类技能先不给。等模型明确需要发送的时候，再动态加载。

这个"按需加载"的思路，是我从实际项目里摸索出来的。一开始全量塞，模型经常在无关技能上纠结；改成按需之后，调用准确率和响应速度都有明显提升。

5. 常见问题与排查技巧实录

5.1 模型不调用技能，只跟你聊天

这是最常见的问题。模型明明有技能可用，但就是不动手，跟你绕圈子。排查思路按顺序来：

先看技能描述。描述里有没有明确的"当……时使用"？如果描述是"这个技能可以查询数据"这种陈述句，模型很难判断什么时候该用。改成"当需要获取实时数据时使用"，通常就能解决。

再看技能列表有没有真的传进去。有时候是代码bug，列表为空，模型自然不知道有技能。打印一下提示词确认。

如果前两条都没问题，那就是模型本身的倾向问题。有些模型天生"话多"，倾向于先聊两句再动手。这时候可以在系统提示词里加一句"如果技能列表中有能完成当前任务的技能，优先调用技能而不是直接回答"。这一句往往能扭转局面。

5.2 调用了错误的技能

模型在多个相似技能之间选错，通常是因为描述区分度不够。比如同时有"查询订单"和"查询物流"两个技能，如果描述都写得很笼统，模型就容易混。

解决办法是在描述里加区分性信息。查询订单的描述里写"根据订单号查询订单状态和金额"，查询物流的描述里写"根据订单号查询配送进度和当前位置"。把各自的独特用途点出来，模型就能分清了。

另一个办法是合并。如果两个技能确实高度相似，考虑合并成一个技能，用参数区分。技能不是越多越好，能合并就合并。

5.3 参数传错或缺失

参数问题的排查，第一步是看schema定义是否清晰。类型、格式、必填选填、取值范围，这些都要写明白。第二步是在执行层做严格校验，不通过就返回明确的错误信息，告诉模型缺了什么、格式应该是什么。模型看到错误信息，下一轮通常会修正。

我遇到过一个典型案例：时间参数模型总是传"明天"这种自然语言。后来在schema描述里加了格式示例，并且在执行层做了自然语言解析兜底，问题就解决了。兜底逻辑很重要，因为不能指望模型每次都完美。

5.4 技能执行超时或卡死

超时问题，首先要确认是技能本身慢，还是外部依赖慢。加日志记录每个技能的耗时，很快就能定位。如果是外部依赖慢，考虑加缓存或者异步处理。如果是技能本身逻辑重，考虑拆分。

卡死的情况比较少见，但一旦发生很致命。我的做法是给所有技能强制加超时，超时后返回错误，绝不允许无限等待。另外，对于可能卡死的操作（比如等待用户输入），设计成异步的，不要让智能体主流程阻塞。

5.5 排查速查表

5.6 几条踩坑换来的经验

第一，技能数量控制在十五个以内。超过之后，模型的调用准确率会明显下降。如果确实需要更多能力，用组合技能封装，对模型暴露的接口保持精简。

第二，技能命名用动词开头。"query_user"比"user_query"好，"send_message"比"message_sender"好。动词开头更符合"这个技能是干什么的"的语义，模型理解起来更顺。

第三，一定要有测试用例。每个技能至少准备三组测试：正常输入、边界输入、异常输入。我吃过亏，一个技能在正常输入下跑得好好的，遇到空值直接崩了，而模型恰好传了空值。有了测试用例，这种问题在开发阶段就能发现。

第四，日志要记全。技能名、参数、返回、耗时、调用来源，一个都别省。排查问题的时候，日志就是你的眼睛。我现在的习惯是，新技能上线第一周，每天都翻一遍调用日志，看有没有异常模式。

第五，版本管理要跟上。技能是会迭代的，改了描述、改了参数，都可能影响模型的调用行为。每次改动都记一笔，出问题的时候能快速回滚。我见过因为改了一个技能描述导致整个流程崩掉的案例，有版本记录的话，五分钟就能定位。

6. 技能系统的扩展方向与个人体会

技能系统搭起来之后，能扩展的方向其实挺多的。我试过并且觉得有价值的有两个：一个是技能的组合推荐，根据当前任务上下文，主动向模型推荐可能需要的技能组合，而不是等模型自己找；另一个是技能的效果评估，记录每个技能被调用后的任务完成情况，用数据反过来优化技能描述和参数设计。

组合推荐的做法是维护一个"任务类型到技能组合"的映射表，当识别到当前任务属于某个类型时，把对应的技能组合优先展示给模型。这能进一步降低模型的决策负担。效果评估则是给每次调用打标，任务成功还是失败，积累一段时间后就能看出哪些技能是"拖后腿"的，针对性优化。

我个人在实际操作中的体会是：技能系统的核心不在于技术多复杂，而在于对"模型怎么想"的理解。你写的每一句描述、定义的每一个参数，都是在跟模型对话。站在模型的角度想问题，比站在程序员的角度想问题，效果要好得多。我早期写的技能，自己看着逻辑清晰，但模型就是不会用；后来逼着自己用"如果我是模型，我看到这段描述会怎么理解"的视角重写了一遍，调用准确率立刻上来了。

最后再分享一个小技巧：新技能上线前，先拿十几个真实任务跑一遍，看模型会不会在正确的时机调用它。这个"预演"环节能挡掉大部分低级问题，比上线后救火划算得多。技能系统是个需要持续打磨的东西，没有一劳永逸的方案，但只要方向对，每改一次都会比上一次好一点。