企业官网建设流程全解析

1. 项目概述：agent-skills 到底是什么

去年年底开始，我一直在折腾 AI Agent 相关的项目，从最早的单纯调 API，到后来自己做多步任务编排，再到研究怎么让 Agent 稳定地完成复杂工作流。中间踩过的坑不少，最深的体会是：Agent 的能力边界，往往不是模型决定的，而是你给它配了多少可用的"技能"决定的。

这个名为 agent-skills 的项目，核心就是把 Agent 的能力拆成一个个可复用、可组合、可独立测试的"技能模块"。你可以把它理解成给 Agent 装了一套乐高式的扩展件——每个技能解决一类具体问题，技能之间可以互相调用，也可以被不同 Agent 共享。项目本身提供了一套技能定义规范、加载机制和生命周期管理方案，配合示例技能库一起使用。

一个典型场景：你有一个负责写周报的 Agent，过去它只会机械地把数据填进模板。有了技能体系之后，你可以给它挂上"数据汇总技能""异常检测技能""文案润色技能"，它就能先拉数据、做分析、再组织语言，输出一份像样的周报。这个思路适合所有正在做 Agent 应用开发的团队，也适合刚入门想搞懂 Agent 架构的开发者。

1.1 为什么技能化是 Agent 开发的关键一步

先说一个我的判断：大模型本身的能力提升已经进入平缓期，而 Agent 的可用性提升空间还大得很。过去两年里，各家模型在通用推理上的差距在缩小，但真正决定一个 Agent 产品好不好用的，是它能不能可靠地完成特定任务——比如准确操作某个系统、解析某种格式、执行一套业务规则。这些能力靠模型背诵是背不出来的，必须显式地教给它，或者更准确地说，以某种结构化的方式注入给它。

技能化就是把"注入能力"这件事标准化。我见过不少团队用 prompt 硬怼，把几十条指令塞进 system prompt，结果模型经常顾此失彼，该用工具的时候不用，不该用的时候乱用。技能化之后，每个能力边界清晰、入口明确、参数可校验，模型只需要根据当前任务选择合适的技能去执行，负担小得多。

1.2 这个项目适合谁来参考

如果你属于下面任何一种情况，agent-skills 的思路都能给你实质帮助：

• 正在开发生产级 Agent，发现 prompt 越来越长但效果越来越差
• 团队里有多个 Agent 各管一摊，重复逻辑越来越多，想统一收敛
• 想给 Agent 增加自定义工具，但不清楚工具和技能之间的边界
• 对 Agent 工程化感兴趣，想了解如何设计一套可测试、可演进的能力体系

2. 核心思路：技能设计的目标与原则

动手写技能之前，先把设计目标想清楚。我把技能体系需要满足的要求归纳成四点：

2.1 可复用性

技能不能绑定某个具体 Agent 的上下文。一个"CSV 清洗技能"应该能同时服务数据分析 Agent 和报表生成 Agent，而不是写死在某个工作流里。这就要求技能在设计时尽量以通用输入输出接口来定义，不要暗含太多调用方的业务假设。

2.2 可组合性

复杂任务几乎不可能靠单个技能完成。更常见的是把大任务拆成子步骤，每个子步骤对应一个技能，技能之间按顺序或条件组合执行。组合意味着技能的结果格式必须稳定、可预期，否则下游技能没法消费。

2.3 可测试性

每个技能可以单独给一组测试用例，验证输入输出符合预期。这样当整个 Agent 出问题时，你能快速定位是哪一个技能掉了链子，而不是对着几百行日志发呆。

2.4 可观测性

技能执行过程中的关键日志、耗时、调用参数、返回值都要有记录。生产环境里 Agent 是个不确定系统，没有观测手段，出了问题连复现都困难。

我个人还有个额外偏好：技能的思维模式要显式化。什么意思呢？一个技能不能只定义"做什么"，还要定义"怎么思考"。比如数据清洗技能，内置的思考步骤应该是：先识别缺失值→再判断缺失策略→接着检查类型一致性→最后输出清洗报告。把思考步骤写清楚，模型的执行稳定性会明显提升。

3. 技能定义：从描述到结构化规格

技能定义是整个体系的基石。我采用 YAML 格式来写技能清单，核心字段包括：

3.1 技能描述字段设计

描述字段直接决定模型能不能在关键时刻选中这个技能。写得模糊，模型就容易犯迷糊；写得过于啰嗦，又浪费 token。我的经验是描述控制在三句话以内，核心句式是"当 [触发场景] 时，用此技能 [做什么动作]，输出 [什么格式的结果]"。

一个反例："处理数据。"——完全没用。 一个正例："当用户提供需要修正的数据文件（含缺失值、格式不一致、重复记录）时，用此技能完成标准化清洗，输出每项问题的处理说明和清洗后的完整数据集。"

3.2 参数与输入输出约束

每个技能必须声明参数 schema，包括参数名、类型、必填性、取值范围。这个 schema 有双重作用：一方面给模型提示应该提供哪些信息，另一方面在运行时做参数校验，把错误挡在技能执行之前。

我见过一个汇报场景：技能要求传入"日期范围"，模型传了个"最近一周"的自然语言描述，如果没有校验，后面解析日期就全乱套。加了 schema 约束并要求 ISO 8601 格式，这个错误在入口就被拦下了。

3.3 技能的执行策略

一个技能的内部执行逻辑可以是一条一个人难以解释的 prompt，也可以是一段确定性的代码，更常见的是两者的组合。我把策略分成三层：

• 纯逻辑层：不需要模型参与，直接写代码完成，比如时间格式化、格式转换
• 模型推理层：需要模型对输入做判断、总结、转换，比如从非结构化文本中抽取字段
• 混合层：先由代码做预处理，再把处理结果交给模型做决策

设计技能的判断准则是：能写代码的别让模型做，必须让模型做的别藏着掖着。确定性逻辑交给代码，可以保证 100% 正确还免费；模型只处理那些真正需要理解力的部分。这样做一方面降低成本，另一方面让行为可预测。

4. 技能加载与调度机制

定义好技能之后，接下来要考虑的是运行时怎么把它用起来。

4.1 启动时加载还是按需加载

技能清单可以很长，但一次对话用到的往往只有几个。把所有技能全塞进上下文会浪费大量 token，还会稀释模型的注意力。我的做法是两级加载：

• 基础技能随 Agent 启动而加载，通常是通用能力，比如日期处理、格式校验
• 扩展技能按需加载，由模型根据当前任务先触发"技能发现"，再加载具体技能描述和逻辑

按需加载的代价是增加一次模型调用，但换来的是上下文的干净。实测数据显示，技能库从 20 个扩展到 80 个之后，基础加载的响应准确率几乎没有下降，就是因为大多数技能根本没进上下文。

4.2 技能路由与调度

当模型决定使用某个技能后，调度器需要负责：

1. 校验技能是否存在、参数是否合法
2. 初始化技能执行环境
3. 把输入数据map到技能接口
4. 执行技能逻辑
5. 把返回值标准化后送回给模型

调度器的设计要点是尽量薄。不要塞业务逻辑，只做流程控制。业务逻辑应该属于技能内部，这样调度器才能保持通用性。

4.3 技能的超时与降级

技能执行可能卡住或者失败，需要设计好超时机制。我习惯给每个技能声明一个预期耗时上限，超时后调度器可以选择重试、降级（调用备用技能）或者直接向模型报告失败原因。这个机制在真实环境中极其重要——在线技能依赖外部 API 时尤其如此，不设超时，整个 Agent 就会被一个慢接口拖死。

5. 实操演示：从零实现一个技能

光讲理论容易飘，我用一个具体例子展示从定义到运行的完整流程。假设我们要做一个"日志异常摘要"技能，它的任务是从一段应用日志中提取错误类型、发生次数、影响范围，并生成一段可读的摘要。

5.1 第一步：写技能清单

先定义技能元信息和参数接口：

name: log_anomaly_summary description: 当用户提供应用日志文本且需要了解错误情况时，使用该技能提取异常类型并生成摘要，输出结构化的 JSON 对象。 version: 1.2.0 parameters: log_text: type: string required: true description: 原始日志文本，建议限制在 20000 字符以内 time_window: type: string required: false description: 时间范围描述，如 2025-01-01T00:00:00Z/2025-01-01T23:59:59Z timeout_seconds: 30

5.2 第二步：实现技能内部逻辑

技能内部我通常用一个 Python 文件承载主要逻辑，关键部分做两层处理。第一层用正则把日志里的异常堆栈、错误码、关键字段抽出来，形成结构化记录；第二层把结构化记录交给一个小模型或主模型生成人类可读的摘要。

import re import json from collections import Counter def extract_errors(log_text): pattern = r"(?P<ts>\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}).*?(?P<level>ERROR|WARN|EXCEPTION).*?(?P<msg>[^\n]*)" matches = re.findall(pattern, log_text) counter = Counter() samples = {} for ts, level, msg in matches: counter[level] += 1 samples.setdefault(level, []).append({"time": ts, "message": msg.strip()}) return {"counts": dict(counter), "samples": samples}

这一步的核心原则是：能离线处理的数据绝不给模型。正则扫一遍日志，常见的错误码、异常数量都能确定下来，模型只负责做归纳总结，省 token 又准确。

5.3 第三步：注册技能并接入 Agent

在技能库里注册之后，Agent 启动时会读到这个技能的摘要信息。当用户丢来一段日志并问"看看出了什么问题"，模型会判断这个任务匹配技能log_anomaly_summary，然后调用它。执行时，调度器先校验参数、再调用上述代码、最后把返回数据拼到模型的观察结果里，由模型生成最终回答。

5.4 第四步：写测试用例

每个技能我都要求至少三个测试用例：一个正常输入验证输出结构，一个异常输入验证容错，一个边界输入验证超限处理。

# test_log_anomaly_summary.py def test_normal_input(): log = "2025-02-01 10:00:00 ERROR Connection refused" result = extract_errors(log) assert result["counts"]["ERROR"] == 1 assert result["samples"]["ERROR"][0]["message"] == "Connection refused" def test_empty_input(): result = extract_errors("") assert result["counts"] == {} assert result["samples"] == {} def test_big_input_performance(): log = "2025-02-01 10:00:00 ERROR x\n" * 5000 result = extract_errors(log) assert result["counts"]["ERROR"] == 5000

测试用例不需要写得多复杂，但一定要覆盖正常、异常、边界这三类场景。测试完之后技能就能安全地放进技能库了。

6. 实战心得：技能开发中的常见坑

技能开发看起来简单，真正用起来问题多得很。我把这段时间踩过的坑整理成了一张速查表：

6.1 技能描述与实际行为不一致

这是最隐蔽的问题。模型根据描述选中技能，结果技能执行的逻辑和描述对不上，Agent 的输出就开始飘。解决办法是每次改技能逻辑，必须同步更新描述，并且加一个一致性测试：把描述抽出来喂给模型，问它"这个技能做什么"，再拿实际的输入输出验证描述是否成立。

6.2 技能粒度失衡

技能定得太粗，一个技能里塞了太多功能，模型调用时难以精准控制参数；定得太细，技能数量爆炸，调度开销大。我的经验是：一个技能只解决一个明确的任务类型，但这个任务类型内部可以分多个子步骤。比如"文档解析"太粗，"PDF 表格抽取"才算合适粒度。

6.3 上下文污染

技能执行产生的中间数据如果都塞回上下文，很快就把窗口占满了。我在技能执行层做了一层缓冲：只把"结论性数据"返回给模型，中间过程（比如逐行日志解析的过程）不进上下文。省 token 之外，还减少了模型被无关信息干扰的概率。

6.4 错误处理缺失

技能执行出错了怎么办？最常见的是直接把异常堆栈抛给模型，让模型猜这是什么意思。更好的做法是技能内部自己做异常捕获，把错误转换成业务语言再上报。比如"上游接口返回 401"应该被转换成"认证失败：请检查 API 密钥是否有效"，模型看到这个提示能给出更准确的后续动作，直接看堆栈只能干瞪眼。

6.5 技能间的私有依赖

我开始定义技能时，出现过技能 A 直接调技能 B 内部函数的情况。短时间看起来没问题，但一旦 B 内部改了实现，A 就会莫名其妙挂掉。后来我定了一条硬规矩：技能之间只能通过公开接口交互，绝不允许内部互相 import。每个技能的公开接口就是它的输入输出 schema，其它都不算数。

6.6 模型选择要匹配技能复杂程度

不同技能对模型能力的要求不一样，统一用一个模型处理所有技能调用，要么浪费要么不够。我现在做的是给技能打上"所需推理等级"的标签：

• 简单技能（格式转换、数据提取）：直接走便宜的快速模型，速度快成本低
• 中等技能（需要少量理解判断的）：走默认模型
• 复杂技能（需要多步推理或工具结合）：走最强模型，同时给足重试次数

这个分级设计在成本上优势特别明显。我这边一个日调用量几十万次的服务，通过把简单技能分流到便宜模型，整体推理成本砍掉了将近四成，响应速度还上去了。

6.7 技能版本更新要平滑

技能库是长期演进的，今天加个参数，明天改个行为，搞得不好就容易破坏已有 Agent。我现在维护技能版本号，并且明确规定：接口层面的变更必须向后兼容，不允许把必填参数改成可选之外再删掉某个参数。如果一个技能确实需要不兼容的调整，我会先起一个新版本，让旧版本继续跑一段时间，等下游 Agent 全部迁移完再下线旧的。

7. 技能评估：怎么证明你的技能真的有用

技能写完了、跑通了，还不算完。关键问题是：这个技能在真实场景里到底有多大帮助？我建立了一套轻量的评估流程，每条技能上线前都跑一遍。

7.1 单技能准确性测试

准备一组带标准答案的测试样本，把样本输入丢给技能，比对输出与答案。这个指标能快速暴露技能逻辑层面的大问题，比如解析规则写错了、字段映射搞反了。

7.2 任务级端到端测试

单技能没问题，不代表整套 Agent 没问题。我会构造几个完整的用户任务，让 Agent 带着技能库去跑，关注几个关键指标：任务完成率、平均轮次、错误恢复次数。完成率提高当然好，但轮次也很关键——同样完成一个任务，所需轮次越少，说明 Agent 的决策越精准。

7.3 回归对比测试

技能库更新之后，把老测试集重新跑一遍，确保改动没有让原有能力退化。这一步最容易偷懒，但一旦偷懒，迟早会在生产环境还回来。我的规矩是：每次技能变更，CI 里必须跑全量回归。

7.4 一个曾经让我印象深刻的评估案例

我之前给一个客服 Agent 加了个"退款政策查询"技能。单技能测试通过率 97%，看起来不错。结果端到端测试时，发现 Agent 经常拿用户订单号调这个技能，但技能只接受政策文本，不接受订单查询，导致整个对话流程卡死。

问题出在哪？技能本身没错，但是 Agent 的任务分配判断出了偏差。后来我在技能描述里加了一句"仅用于查询政策条款，不处理具体订单状态"，再配合在调度层增加一次输入预检——订单号格式的数据来了就挡在门外——端到端完成率一下子从 61% 提到了 88%。这个案例让我明白：技能好用不等于 Agent 会用，你必须从两个层面同时锁死边界。

8. 扩展思路：技能生态与多 Agent 协同

最后聊聊我看到的下一步发展趋势。

8.1 技能库的共享与复用

单个团队维护一整套技能库成本不低，但技能本身是高度通用化的。比如"时间日期标准化""敏感信息脱敏""格式校验"这类技能，几乎所有 Agent 都需要，完全可以做成内部共享技能库。更进一步，团队之间也可以互相开放技能贡献，就像开源社区维护公共组件那样维护技能生态。版本管理、质量评审、兼容性测试这些机制，都是支撑技能共享的关键基础设施。

8.2 技能与多 Agent 分工

我在多 Agent 场景里的做法是：一个主 Agent 负责任务拆解和调度，多个专业 Agent 各自带着自己的技能集工作。主 Agent 不直接拥有技能，它只做路由决策；专业 Agent 才实际执行技能。这个分层的好处是，技能的所有权清晰，各专业 Agent 可以独立演进，互不干扰。

比如说一个数据分析平台，可以有一个"取数 Agent"带着数据库查询技能，一个"可视化 Agent"带着图表生成技能，一个"报告 Agent"带着文档撰写技能。主 Agent 拿到用户意图后，依次调度三者协作，每个 Agent 只需精于自己的领域。

8.3 技能生命周期的管理

技能不是写出来就完事的。我维护了一套技能生命周期：开发中→测试中→已发布→已废弃。已废弃的技能不会被调度器选中注册，但保留历史记录供追溯。这个管理听起来简单，真正坚持做下来对维护成本帮助巨大，至少在问题排查时你不会再对着一个已经没人用的技能找原因。

我在实际项目中有一套技能仓库的管理约定，目录结构大概是：skills/下面按技能名建目录，每个目录里有SKILL.yaml（定义文件）、run.py（实现代码）、tests/（测试用例）。这个约定已经在团队里跑了大半年，新同学上手速度明显快了。

还有个细节，就是技能命名。我吃过亏，早期给技能取名叫process_data、handle_error，过两周回来看完全不知道哪个管哪个。后来统一改成业务域_动作_对象的命名方式，比如data_clean_csv、log_analyze_error，一眼就懂，省了很多沟通成本。

agent-skills 这条路走到现在，我最大的体会是：与其焦虑模型不够聪明，不如把已知的流程、已知的规则、已知的处理方式，都变成一个一个扎实的技能沉淀下来。模型会越来越强，但你沉淀的技能体系，才是你的 Agent 产品真正的护城河。

最后分享一个小经验：技能开发别急于求成，一个技能从定义到稳定，通常至少要经过两轮真实场景的打磨——第一轮你会发现描述理解有偏差，第二轮你会发现有边界情况没覆盖。这是正常节奏，技术债攒在技能里，后面返工的成本远高于一开始多做几轮测试。建议把你手里的 Agent 能力逐条过一遍，凡是逻辑明确、重复出现的处理过程，都应该考虑技能化。