企业官网建设流程全解析

1. 从"agent-skills"这个标题说起：它到底在解决什么问题

第一次看到"agent-skills"这个词，我脑子里蹦出来的不是某个具体框架，而是一类很实际的需求：怎么让一个智能体（agent）真正具备可复用、可组合、可迁移的能力模块。说白了，就是别每次遇到新任务都从零写一遍提示词、从零搭一遍工具链，而是把"会做的事"沉淀成一个个标准化的技能包，需要的时候挂载上去就行。

这个方向最近一年热度一直往上走，原因也不复杂。早期大家玩智能体，基本是"一个提示词打天下"，写个几百字的系统提示，塞几个工具函数，能跑通一个场景就算成功。但真到了要落地的时候，问题全冒出来了：同一个智能体要处理十几种任务，提示词越堆越长，模型开始"精神分裂"；换个业务场景，之前写的工具调用逻辑几乎没法复用；团队里几个人协作，谁的提示词改了、改了哪一版，根本说不清楚。agent-skills 这套思路，本质上是把软件工程里"模块化"和"关注点分离"的老经验，搬到了智能体的能力组织上。

它适合谁来参考？我梳理了一下，大概三类人最用得上。第一类是正在做智能体应用落地的开发者，手里有一堆零散的工具和提示词，想整理成体系；第二类是做平台或中台的同学，需要给业务方提供一套"技能市场"式的接入规范；第三类是对智能体架构感兴趣、想自己动手搭一套可扩展框架的爱好者。不管你是哪一类，核心诉求其实是一致的：让能力可插拔，让行为可预期，让维护成本降下来。

我下面要聊的，不是某个具体开源库的 API 文档，而是围绕 agent-skills 这个主题，把设计思路、核心机制、实操落地、踩坑经验完整地过一遍。你可以把它当成一份"如果我要从零设计一套智能体技能系统，我会怎么想、怎么做"的实战笔记。

2. 技能系统的整体设计思路拆解

2.1 为什么不能把技能直接写进系统提示词

很多人第一反应是：技能不就是一段说明吗，我直接写进系统提示词不就行了？我早期也这么干过，结果很快就撞墙了。假设你有 20 个技能，每个技能平均 150 字描述，光技能说明就 3000 字，再加上工具定义、输出格式约束、安全规则，系统提示轻松破 5000 字。这带来三个直接后果。

第一是注意力稀释。模型的上下文窗口虽然大，但它对提示词里不同部分的"关注度"是不均匀的。技能描述堆得越多，每个技能被准确激活的概率就越低，经常出现"该用 A 技能的时候它用了 B"或者"两个技能混着用"的情况。第二是维护灾难。改一个技能的描述，可能影响其他技能的触发边界，牵一发动全身，回归测试根本做不完。第三是无法按需加载。有些技能只在特定场景用，比如"生成周报"和"查询库存"八竿子打不着，但每次请求都要把两者都塞进上下文，纯属浪费。

所以技能系统的第一个设计原则就出来了：技能必须与主提示词解耦，支持按需检索和动态注入。主提示词只保留"元能力"——怎么发现技能、怎么调用技能、怎么组合技能，具体技能内容放在外部存储里，用到才取。

2.2 一个技能应该包含哪些字段

既然要解耦，就得定义清楚"一个技能"到底长什么样。我参考了常见实践，也结合自己踩过的坑，总结出一套比较实用的字段结构。这里要说明的是，具体字段名各家实现不一样，但语义层面这几块基本跑不掉。

我重点说说触发描述这个字段，因为它是最容易被低估的。很多人写触发描述就一句话"用于生成周报"，结果模型在"帮我总结下这周工作"的时候根本想不起来调用它。好的触发描述应该包含三部分：场景信号 + 动作意图 + 边界说明。比如："当用户提到'周报''本周总结''工作汇报'，且需要按固定模板输出时使用；如果只是随口聊聊本周感受，不要调用。"这样写，召回率和精确率都能明显改善。

2.3 技能的三种组织形态

技能攒多了，怎么组织也是个问题。我见过三种主流形态，各有适用场景。

扁平列表最简单，所有技能平铺，靠检索匹配。适合技能数量在 50 个以内的场景，实现成本最低。缺点是技能一多，检索精度下降明显。

分类树把技能按领域分组，比如"办公类""数据类""沟通类"，先选大类再选具体技能。适合技能数量中等（50-200）、领域边界清晰的场景。缺点是跨领域任务不好归类，而且分类本身需要维护。

标签网络给每个技能打多个标签，检索时按标签组合匹配。灵活度最高，适合技能数量大、组合场景多的场景。缺点是实现复杂度高，标签体系设计不好容易乱。

我的建议是从扁平列表起步，技能超过 30 个再考虑引入标签。别一上来就搞复杂架构，很多项目死在过度设计上。分类树我个人的评价是"看起来很美"，实际用起来维护成本不低，除非你的业务领域天然就是树状的，否则不太推荐。

3. 核心机制解析：技能是怎么被"用起来"的

3.1 技能检索：从用户输入到候选技能

技能系统的核心链路，第一步永远是检索。用户说一句话，系统得判断该激活哪些技能。这一步做不好，后面全白搭。

常见的检索方式有三种。关键词匹配最简单，维护一个关键词到技能的映射表，命中就召回。优点是快、可控、可解释；缺点是不懂同义表达，"周报"和"工作小结"可能匹配不上。向量检索把技能描述和用户输入都转成向量，算相似度。优点是能处理语义相近的表达；缺点是可能召回"看起来像但实际不该用"的技能，而且阈值不好调。混合检索先用关键词粗筛，再用向量精排，兼顾召回和精度，是目前比较稳的方案。

我实测下来，混合检索 + 一个轻量的重排步骤效果最好。具体做法是：关键词匹配召回一批候选，向量检索再召回一批，合并去重后，用一个小的分类模型或者干脆让主模型自己判断"这些候选里哪些真的相关"。最后这一步虽然多花一点 token，但能显著降低误触发。

提示：检索阈值不要设死。我见过有人把相似度阈值定在 0.8，结果稍微换个说法就召回不到。建议先用一批真实用户问法做测试，把阈值调到"宁可多召回一点，靠重排兜底"的位置。

3.2 技能注入：怎么把技能塞进上下文

检索出候选技能后，下一步是注入。这里有个关键决策：是注入完整技能内容，还是只注入技能摘要，等确定要用再加载完整内容？

我的经验是两段式注入。第一段只注入技能的"名称 + 触发描述 + 输入参数概要"，让模型判断该不该用、用哪个。第二段在模型选定技能后，再把完整的执行逻辑注入。这样做的好处是上下文占用小，模型决策负担轻。坏处是多一次交互往返，延迟略高。

对于延迟敏感的场景，可以退化成一次性注入，但只注入 top-3 候选，别把所有召回结果都塞进去。我试过把 10 个候选全塞进去，模型反而选择困难，经常挑一个"差不多"的而不是最合适的。

3.3 技能执行：提示词、代码还是工作流

技能的执行逻辑有三种实现方式，选择哪种取决于技能的确定性要求。

纯提示词技能最灵活，适合开放式任务，比如"写一段产品文案"。缺点是输出不稳定，同样的输入两次结果可能差很多。代码技能最确定，适合有明确计算逻辑的任务，比如"计算两个日期之间的工作日数"。缺点是灵活性差，遇到边界情况容易崩。工作流技能是前两者的组合，把任务拆成多个步骤，部分步骤用提示词、部分用代码，适合复杂任务，比如"抓取数据 → 清洗 → 分析 → 生成报告"。

我的选型原则很简单：能用代码解决的，绝不用提示词。提示词只用在"确实需要语言理解和生成"的环节。很多新手喜欢把所有事都交给提示词，结果系统又慢又不稳，还费 token。举个例子，"从一段文本里提取邮箱地址"，用正则一行搞定，非要用提示词让模型提取，既慢又可能漏。

3.4 技能组合：多个技能怎么协同

真实任务往往需要多个技能配合。比如"帮我分析下这周的销售数据并生成周报"，可能涉及"数据查询""数据清洗""趋势分析""报告生成"四个技能。怎么让它们协同？

最简单的是串行编排，前一个技能的输出作为后一个的输入。实现简单，但不够灵活，中间任何一步失败整个链路就断了。进阶一点的是带条件分支的编排，根据中间结果决定下一步走哪条路。再复杂的是动态规划，让模型自己决定调用顺序和组合方式。

我的建议是：先用串行编排把主流程跑通，再逐步引入分支。动态规划听起来很酷，但调试成本极高，除非你的任务确实需要高度灵活的组合，否则别轻易上。另外，技能之间传递数据时，一定要定义清楚数据契约，别让上游输出一个自由文本、下游去猜格式，这是组合场景里最常见的翻车点。

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

4.1 目录结构与技能定义文件

假设我们要搭一套最小可用的技能系统，我推荐这样的目录结构：

skills/ report-weekly/ skill.yaml prompt.md handler.py >id: report-weekly name: 周报生成 version: 1.2.0 triggers: - 周报 - 本周总结 - 工作汇报 description: | 当用户需要按固定模板生成周报时使用。 如果用户只是随口聊本周感受，不要调用。 inputs: - name: date_range type: string required: true desc: 统计的日期范围，格式 YYYY-MM-DD 到 YYYY-MM-DD - name: data_source type: string required: false desc: 数据来源标识，默认使用主数据源 outputs: format: markdown dependencies: ->def retrieve_skills(user_input, registry, top_k=5): # 第一路：关键词匹配 keyword_hits = [] for skill in registry: for trigger in skill.triggers: if trigger in user_input: keyword_hits.append(skill) break # 第二路：向量检索 input_vec = embed(user_input) scored = [] for skill in registry: skill_vec = embed(skill.description) score = cosine_sim(input_vec, skill_vec) scored.append((skill, score)) scored.sort(key=lambda x: x[1], reverse=True) vector_hits = [s for s, _ in scored[:top_k]] # 合并去重 merged = [] seen = set() for skill in keyword_hits + vector_hits: if skill.id not in seen: merged.append(skill) seen.add(skill.id) return merged[:top_k]

这段代码有几个实操要点。第一，关键词匹配要处理大小写和空格，中文场景还要考虑分词，别用简单的in判断就完事。第二，向量检索的 top_k 要设得比最终需要的多，比如最终要 3 个，检索就取 8 个，给重排留空间。第三，合并顺序有讲究，关键词命中的通常更精准，应该排在前面。

注意：向量检索的 embedding 模型要和技能描述的语言匹配。如果你的技能描述是中文，用中文效果好的 embedding 模型，别随便拿个英文模型凑合，相似度算出来会很不准。

4.3 注入与执行的完整流程

把检索和执行串起来，一个完整的请求处理流程大概是这样：

1. 接收用户输入，做基础清洗（去多余空格、统一标点）
2. 调用检索模块，拿到候选技能列表
3. 构造"技能选择提示词"，把候选技能的摘要信息给模型，让它选
4. 模型返回选中的技能 ID 和参数
5. 根据技能 ID 加载完整技能定义
6. 执行技能逻辑（提示词渲染或代码调用）
7. 如果技能有依赖，递归执行依赖技能
8. 汇总结果，返回给用户

第 3 步的提示词我一般这么写：

你是一个技能调度器。根据用户请求，从以下候选技能中选择最合适的一个或多个。 候选技能： {skill_summaries} 用户请求：{user_input} 请输出 JSON 格式：{"skills": ["skill_id"], "params": {...}} 如果没有任何技能合适，输出 {"skills": []}。

这里有个坑：模型有时候会输出不存在的技能 ID。所以拿到结果后一定要做校验，ID 不在候选列表里的直接丢弃。我早期没做这个校验，结果模型编了个技能名，系统直接报错。

4.4 参数提取与校验

技能选定后，还要从用户输入里提取参数。这一步有两种做法：让模型提取或者用规则提取。我的经验是混合用：结构化参数（日期、数字、枚举值）用规则提取，非结构化参数（描述性文本）用模型提取。

参数校验同样重要。必填参数缺失怎么办？我的做法是反问用户，而不是瞎猜一个默认值。比如用户说"生成周报"但没说日期范围，系统应该问"请问统计哪段时间的数据？"而不是默认用本周。瞎猜默认值看起来智能，实际经常猜错，反而增加用户纠正成本。

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

5.1 技能召回不准怎么办

这是最高频的问题。表现是"该用的技能没用"或者"不该用的技能乱用"。排查思路我整理成一张表：

我个人的经验是，80% 的召回问题出在触发描述写得不好，而不是检索算法不行。与其花时间调算法，不如先把每个技能的触发描述打磨一遍，投入产出比高得多。

5.2 技能之间互相干扰怎么破

技能多了以后，经常出现"A 技能和 B 技能都能用，模型选错"的情况。这通常是因为两个技能的触发描述有重叠。解决办法有三个层次。

第一层是描述层面，把两个技能的边界写清楚。比如"数据查询"和"数据分析"，前者只负责取数，后者负责在取数基础上做统计和洞察。描述里明确写"如果只是要原始数据，用数据查询；如果要做趋势判断，用数据分析"。

第二层是优先级层面，给技能设优先级，重叠时高优先级胜出。这个适合有明确主次关系的场景。

第三层是互斥层面，明确某些技能不能同时激活。比如"简洁模式"和"详细模式"就是互斥的，同时激活会打架。

5.3 技能执行失败的兜底策略

技能执行失败太常见了：代码报错、模型输出格式不对、依赖服务超时。没有兜底策略的系统，用户体验会非常差。

我的兜底策略分三级。一级是重试，对于偶发失败（比如网络抖动），自动重试 1-2 次。二级是降级，如果某个技能不可用，尝试用功能相近的替代技能，或者退化成纯提示词方式处理。三级是兜底回复，实在处理不了，给用户一个明确的说明，而不是抛一个技术错误。

提示：兜底回复千万别写"系统错误，请稍后重试"这种。用户看不懂，也不知道该干嘛。写成"这个任务我暂时处理不了，你可以试试换个说法，或者直接告诉我你想要的结果格式"，体验会好很多。

5.4 技能版本管理踩过的坑

多人协作时，技能版本管理是个大坑。我踩过最惨的一次是：A 同学改了某个技能的提示词，没通知任何人，结果 B 同学负责的流程突然开始出错，排查了半天才发现是技能被改了。

后来我定了三条规矩。第一，技能定义文件必须进版本控制，每次修改都有记录。第二，技能版本号遵循语义化版本，改了行为就升 minor 或 major，只改文案升 patch。第三，技能变更要跑回归测试，至少覆盖该技能的主要使用场景。这三条看起来简单，但坚持下来能省掉大量扯皮时间。

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

6.1 从单机技能到技能市场

当技能积累到一定数量，自然会想到"能不能让别人也用我的技能"。这就涉及到技能市场化的设计。核心要解决的问题有三个：技能怎么分发（打包格式、依赖声明）、技能怎么发现（搜索、分类、推荐）、技能怎么信任（质量评估、安全审查）。

我参与过的一个模拟项目里，我们尝试过一套简单的技能分发机制：技能打包成标准格式，带元数据和依赖声明，上传到内部仓库，其他人按需拉取。运行效果还不错，但安全审查这一环绝对不能省。技能里可能包含代码执行逻辑，来源不可信的技能直接跑，风险很大。至少要有人工审核或者沙箱隔离。

6.2 技能的自学习与自动优化

再往前看一步，技能系统能不能自己进化？比如根据使用数据自动优化触发描述，或者根据失败案例自动补充边界说明。这个方向很有意思，但我的态度是谨慎乐观。

乐观是因为技术上可行：收集"用户输入 + 是否调用 + 调用结果"的数据，用这些数据去微调检索模型或者优化描述，逻辑上是通的。谨慎是因为自动优化容易失控。技能描述被自动改得面目全非，人看不懂也维护不了，出了问题没法排查。我的建议是自动优化只做"建议"，最终改动还是要人确认。

6.3 我个人的几条实操心得

最后分享几条我在做技能系统过程中总结的心得，都是踩坑换来的。

第一，技能粒度宁小勿大。一个技能只干一件事，干好。我见过有人把"查询数据 + 分析 + 生成报告"塞进一个技能，结果这个技能又长又难维护，还不好复用。拆成三个小技能，组合起来用，灵活得多。

第二，触发描述要像写给新同事看。想象你给一个刚入职的同事介绍这个技能，你会怎么说？把那个说法写下来，基本就是好的触发描述。别用"用于处理相关任务"这种废话。

第三，先跑通再优化。别一上来就追求完美的检索算法、完美的编排逻辑。先用最简单的关键词匹配 + 串行执行把主流程跑通，有了真实使用数据，再针对性优化。很多优化点在没数据之前根本想不到。

第四，日志要记全。每次技能调用，把用户输入、召回结果、选中技能、执行结果、耗时都记下来。这些日志是后续优化的唯一依据。我早期日志记得不全，想分析问题的时候发现啥都查不到，只能重新埋点，浪费了很多时间。

第五，别忽视冷启动。新技能刚上线，没有使用数据，检索效果往往不好。可以手动给新技能加一些"种子触发词"，或者临时提高它的优先级，等积累了一定使用数据再回归正常策略。

这套东西说到底，核心就一句话：把智能体的能力当成软件资产来管理，而不是当成提示词来堆砌。想清楚这一点，后面所有的设计决策都会顺很多。