企业官网建设流程全解析

如果你玩过大模型 Agent，大概率遇到过这个场景：模型本身很聪明，但让它去执行一个具体任务——比如查资料、整理文件、跑脚本——就各种翻车。不是它不会，而是它不知道该怎么“动手”。agent-skills 这个标题我第一次看到时，心里就两个字：对味。它把问题往根源上带了——我们缺的不是更强的模型，而是一套能把模型能力转化成稳定执行力的技能体系。

这篇文章我想从工程落地的角度，把 agent-skills 拆开聊透。它能做什么、解决什么问题、适合谁来看，我用大白话讲清楚：所谓 agent-skills，本质上是给大模型配一套“工作技能库”，让模型不再每次从头摸索，而是像老员工一样，知道什么场景调用什么方法、按什么步骤干活、碰到异常怎么处理。适合正在做 Agent 应用、被“模型很聪明但任务老跑偏”折磨的开发者，也适合刚接触 Agent 只想搞明白“技能到底怎么设计”的入门者。

1. 先搞清楚：agent-skills 解决的是 Agent 的什么问题

1.1 从“会聊天”到“会干活”，Agent 缺的是技能栈

很多团队做 Agent 踩的第一个大坑，是把 Agent 当聊天机器人用。用户问一句，模型回一段，看起来挺智能，但落到业务里根本不够——真正要的是一个能“把事办完”的系统。

聊天和干活是两码事。聊天只需要生成文本，干活需要模型具备两样东西：一个是动作能力，也就是能调用工具、读写文件、请求接口；另一个是方法能力，也就是知道先做什么后做什么，遇到什么情况该切换策略。这两样合起来，就是“技能”。

我见过不少人以为只要给模型接上工具就能干活，结果模型拿到一堆函数，今天这个好用，明天那个就乱调。问题就出在工具是散的，而技能是组织起来的。技能把工具的调用方法、前置条件、输入输出约束、异常处理都封装在一起，模型不需要靠“悟性”去理解工具，只需要按技能说明来执行。

所以 agent-skills 解决的最核心问题，就是把“模型会说话”变成“模型能稳定干活”，把不可控的临场发挥，变成可复用的流程资产。

1.2 技能库、插件、工具：三个概念别搞混

聊 agent-skills 之前，有三个词必须先理清，不然讨论起来全是鸡同鸭讲：工具、插件和技能。

工具（Tool）是最小动作单元，通常一个函数对应一件事，比如“发送 HTTP 请求”“读取某个文件”“执行一段 Python 代码”。插件（Plugin）是工具的打包形态，解决的是“怎么接入”的问题，比如一个浏览器插件把搜索、抓取、截图这些工具打包好。技能（Skill）则更进一层，它面向的是一个完整目标，里面可能包含多个工具调用、判断逻辑和兜底策略。

举个例子：搜索是一个工具；把搜索集成好并提供额外接口是插件；“根据用户问题，先拆关键词，再查多个来源，最后整理成要点回答”就是技能。技能本身可以调用工具，也可以调用其他技能，它描述的是做事的方法，而不是单一的接口。

把这三层拆清楚之后，你再看任何 Agent 框架都会通透很多——很多所谓“Agent 效果不稳定”的问题，其实不是模型不行，而是技能层没做好。

1.3 为什么说技能是 Agent 项目里的一等公民

我早期做 Agent 项目的时候，把大部分精力花在调 prompt 上，想着“提示词写得够细，模型自然就听话”。后来发现这是最不划算的路。同一个任务换一个模型要重调，同一个模型换一种说法效果又变了，prompt 修来修去始终在打补丁。

后来我把思路改成：prompt 只负责讲清楚目标和边界，真正干活靠技能。技能一旦定义好，就是可积累的资产。今天让模型学会“联网检索”，明天所有需要检索的任务都能复用；今天调通了“数据清洗”，后天接新数据源直接拿来用。技能就像公司的知识库，不随人员流动流失，也不随模型升级失效。

这也是 agent-skills 这个名字给我的感觉——它把 Agent 开发的重心从“写提示词”拉回到“建设技能体系”，让每一次调试和优化都有沉淀。

2. 技能体系的设计思路与核心拆解

2.1 技能的最小单元：输入输出之外，还要定义什么

一个技能要能被模型稳定使用，光有函数签名远远不够。我总结下来，一个完整技能至少要包含几个部分：名称、描述、输入参数、输出格式、前置条件、副作用、失败兜底。

名称和描述决定模型什么时候会想起来用这个技能。名称要短，一眼能看懂；描述要写清楚“什么时候用、用了能解决什么”。很多人不重视描述，随手写一句“搜索信息”就完事，结果模型在真正需要搜索的时候压根不触发它，反而去编造答案。

输入参数要遵循严格的 JSON Schema，能枚举就枚举，能设默认值就设默认值。模型的参数幻觉是 Agent 工程最大的痛点之一，后面我会专门讲怎么排查。前置条件这块非常容易被忽略，比如“写文件技能”需要先确认目录存在；“发邮件技能”需要收件人邮箱格式合法。这些前置逻辑写进技能里，比模型临场判断可靠得多。

副作用描述的是这个技能会对外部环境产生什么影响。模型并不天然理解“删除文件”“提交订单”是高风险动作，你要在技能设计时明确标注“确认后执行”之类的约束。很多安全事故，追溯到最后都是技能副作用没有写清楚。

2.2 技能编排：串行、并行、条件分支怎么落地

单个技能能解决简单任务，但真实业务往往是复合的：先搜索，再筛选，然后生成报告，最后发送。这就涉及技能的编排问题。

技能编排目前没有标准答案，但大体分两种路线。一种是让模型自己编排，把技能列表全塞给模型，让它根据任务目标决定调用顺序。优点是灵活，缺点是不可控，复杂任务经常出现“绕远路”甚至“循环调用”。另一种是人为预定义流程，用类似 DAG 的方式把技能连起来。这种方式稳定，但灵活性差，换个场景流程就得改。

我的做法是折中：把主干流程用代码固定，分支节点放开让模型选择。举个例子，一个“竞品分析”技能内部定义好了“数据收集—数据清洗—分析生成—报告输出”的骨架，但数据收集环节具体调哪个源、生成报告用什么模板，由模型根据输入动态决定。这样既保住了稳定性，又留了弹性。

实话说，我不推荐把所有业务逻辑都压在模型编排上。模型做顺序决策还行，但让它同时维护多个状态、处理复杂分支，效果和稳定性都会明显下降。能用代码确定的流程，就不要让模型去“悟”。

2.3 上下文工程：技能描述的措辞决定模型用不用

一个技能写得再漂亮，如果模型压根不理解它，等于白写。这里我要专门讲讲技能描述怎么写。

技能描述不是写文档，是写给模型看的“使用说明”。重点不是它是什么，而是它什么时候触发、怎么用。我常用的写法是四段式：触发场景、执行动作、输出格式、失败处理。比如一个搜索技能，我会写：“当用户需要获取最新信息、查找特定数据、或回答需要外部知识的问题时，使用此技能。先拆解查询关键词，调用搜索引擎，获取结果后提取核心信息，按 JSON 格式返回，包含来源链接。如果搜索失败，尝试更换关键词重试一次。”

这里面的关键是触发场景要写得足够具体，不能含糊。如果你的技能描述写“用于搜索”，模型会在很多不需要搜索的时候也去调它，因为描述太宽泛了；如果你写“仅当……时使用”，模型反而能准确判断边界。

另一个容易被忽略的点是上下文长度。技能列表不能无限膨胀，塞太多技能进上下文，不仅浪费 token，还会稀释模型的注意力。建议给技能做摘要索引，先让模型看技能名称和一句话摘要，真正需要时再加载完整描述。这个机制就像人的“工作记忆”和“长期记忆”的分工，agent-skills 如果要做大规模，这一步躲不开。

3. 实操过程：从零到一撸一个可用技能

3.1 先定义技能数据模型

干活之前，先定数据模型。我用 Pydantic 或 TypeScript interface 都行，关键是结构要稳。下面我用 Python 示例展示一个技能的基本形态。

from dataclasses import dataclass, field from typing import Any @dataclass class Skill: name: str # 技能名，短且唯一 description: str # 给模型看的触发说明 parameters: dict # JSON Schema 参数定义 required: list # 必填参数列表 execute: callable # 实际执行函数 timeout: int = 30 # 超时时间（秒） side_effects: list = field(default_factory=list) # 副作用声明

每个字段都有存在的理由。name 是模型用来识别的“函数名”，description 是模型判断触发条件的依据，parameters 约束输入，execute 负责真正执行，timeout 防止技能卡死拖垮整个 Agent，side_effects 则用来标记危险动作。

3.2 写一个真正能跑的超简单技能

接下来我们写一个可用的小技能：联网搜索并整理要点。这个技能很适合做第一个练手项目，因为链路短、结果直观，能快速验证整套技能机制是否通畅。

import json import requests def search_and_summarize(query: str, max_results: int = 5) -> str: # 这里简化处理，实际接入你的搜索服务 url = "https://api.example.com/search" params = {"q": query, "n": max_results} resp = requests.get(url, params=params, timeout=10) resp.raise_for_status() results = resp.json() # 提取核心信息 summaries = [] for item in results["items"]: summaries.append({ "title": item["title"], "source": item["url"], "snippet": item.get("snippet", "")[:200] }) return json.dumps(summaries, ensure_ascii=False, indent=2) skill = Skill( name="search_and_summarize", description=( "当用户需要获取最新信息、查询特定数据、或回答依赖外部实时知识的问题时，" "使用此技能。先拆解用户问题中的核心关键词，再执行搜索，最后提取关键信息" "返回摘要列表。" ), parameters={ "type": "object", "properties": { "query": {"type": "string", "description": "搜索关键词"}, "max_results": {"type": "integer", "default": 5, "minimum": 1, "maximum": 10} } }, required=["query"], execute=search_and_summarize, timeout=15, side_effects=["外部网络请求"] )

这个例子里有几个细节值得注意。第一个是 timeout 设成了 15 秒，搜索接口不可控，给它 30 秒风险太大，15 秒比较合理。第二个是 max_results 设置了上下限，防止模型传一个 999 把服务打爆。第三个是 side_effects 标记了“外部网络请求”，后续如果做权限审计，这个字段能派上大用场。

3.3 技能注册：怎么让模型“看到”技能

技能定义好了，得让模型知道它的存在。调用链路一般分四步：加载技能列表、拼进系统提示词、模型决定是否调用、执行技能返回结果。

# 1. 注册所有技能到一个管理器 skill_registry = { "search_and_summarize": skill, } # 2. 构建给模型的技能描述 def build_function_schemas(registry): schemas = [] for s in registry.values(): schemas.append({ "type": "function", "function": { "name": s.name, "description": s.description, "parameters": s.parameters, "required": s.required } }) return schemas # 3. 模型返回要调用的技能后，解析并执行 def run_skill_call(model_response, registry): for call in model_response.tool_calls: skill_name = call.function.name args = json.loads(call.function.arguments) if skill_name not in registry: return "Error: unknown skill" skill = registry[skill_name] result = skill.execute(**args) # 返回值可以回传给模型做二次生成 return result

很多模型 API 都原生支持 function calling，你不需要自己写模型侧的逻辑，但要注意两点。第一，参数解析一定要做防御，模型生成的数据经常出现缺字段、类型错误、字符串不合法 JSON 的情况，解析失败要兜底。第二，执行结果要返回给模型继续推理，技能通常只是中间步骤，不是最终答案。

我的习惯是始终保留一个“执行失败”的返回状态。技能出错了不要直接报异常给用户，而是把错误信息作为文本返回给模型，让它决定是换个参数重试还是换技能。这个机制简单，但能显著提升任务完成率。

3.4 实测对比：技能描述写法真的影响触发率

我分别用三种写法试过同一个搜索技能，触发率的差别非常明显。当然这只是我的实测，不同模型结果会有差异，但方向基本一致。

第一种写法是“搜索信息并返回结果”，触发率只有四成左右。模型经常在需要外部知识的时候直接编造答案，根本没想到调用搜索技能。第二种写法加上了触发条件：“当问题涉及最新新闻、实时数据、具体数值或用户明确要求查询时，使用此技能”，触发率提升到六成。第三种写法把决策权直接交给模型并给了反例：“如果问题内容无需外部知识即可回答，或者仅涉及常识性知识，则不使用此技能”，触发率能到八成以上。

这段实测的核心启发是：技能描述决定模型多少个节点在用。别急着把代码写复杂，先在描述上多花几轮，效果好得多。

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

4.1 技能不生效：多半是描述写得像科普文章

你给模型配了技能，它就是不调用，这是最普遍的问题。我排查这类问题第一步不是改代码，而是把技能描述拿出来读一遍，看它像什么。如果描述读起来像“某某产品介绍”，基本就废了。

什么叫像科普文章？比如“本技能用于提供天气信息，支持城市查询、未来几小时预报、温湿度展示等功能”，这种写法满篇都在讲我有什么能力，没有告诉模型你该在什么时候用它。模型是没有常识的，它不知道“用户问今天要不要带伞”等价于“查询当前天气”，需要你显式写清楚。

改成什么样子为好？“当用户询问当前或未来的天气状况，包括温度、降水、风力，或者用户问要不要带伞、要不要晾衣服这类隐含天气需求的问题时，使用此技能。”把触发场景列得越具体，模型越不容易跑偏。

4.2 参数幻觉：模型自己发明参数怎么办

参数幻觉是最让人头疼的问题之一。明明你的技能只需要两个参数，模型非要传五个，甚至编造一个你根本没定义过的参数名。这种情况在参数较少、描述不够严谨的时候尤其高发。

我的应对策略是三道防线同时上。第一道是严格 JSON Schema，能设 enum 就设 enum，能设 format 就设 format，让模型几乎没有自由发挥的空间。第二道是参数清洗，模型传进来的参数过一层校验函数，不认识的关键字直接丢掉，缺失的必填参数用默认值补齐。第三道是执行失败容忍，万一参数不合法也不要直接抛异常，给模型回传一条错误提示，让它重新生成参数。

def safe_call_skill(skill, args): clean_args = {} props = skill.parameters.get("properties", {}) for key, meta in props.items(): if key in args: clean_args[key] = args[key] elif key == skill.required or key in skill.required: default = meta.get("default") if default is not None: clean_args[key] = default else: return "Error: missing required param: " + key try: return skill.execute(**clean_args) except Exception as e: return f"Error: {str(e)}"

这道防线不是万能的，但它能让你从“模型乱传参数导致系统崩溃”的坑里爬出来，把问题收敛到可追踪的错误信息里。

4.3 技能冲突与优先级：多个技能同时触发怎么办

技能数量一多，新问题就来了：模型看哪个描述都像，一次调用好几个技能，结果互相影响，甚至死循环反复调用。这是技能体系设计避不开的一个坎。

解法有两个维度。一是从源头控制，保证技能之间的触发条件互斥，比如“搜索信息”和“查询本地数据库”虽然都返回值，但触发场景要明确区分开——前者面对未知外部信息，后者面对已入库的内部数据。二是每次调用只允许模型选择最相关的技能，不搞“同时执行一堆”的策略，复杂的并发需求应放在技能内部实现，而不是靠模型同时调多个技能。

如果发现模型频繁在几个技能之间来回横跳，比如先调 A 搜索、又调 B 总结、又回到 A 重新搜索，大概率是技能职责划分不清。这时候我的建议是重新审视技能边界，把重叠的逻辑合并成一个复合技能，而不是靠模型自己收住。

4.4 一套亲测有效的整链路自检清单

排查 Agent 技能问题，最忌讳的就是乱试。我给自己定的规矩是，遇到问题先按清单逐项检查，保证一套流程走下去能定位大部分问题。

这套清单看起来简单，但我每次做新技能上线前都会完整走一遍。尤其是前两条，能挡掉 70% 以上的低级问题。

5. 后面还能怎么玩：agent-skills 的进阶方向

5.1 让 Agent 自己写技能

技能体系做到中期，你会开始琢磨一个问题：能不能让模型自己定义新技能？答案是能，而且这才是 agent-skills 的终极形态之一。

我在实验里搭过一个闭环：先给模型一个“创建技能”的元技能，它负责根据用户任务描述生成新的技能代码、参数 Schema 和描述文本；生成后立刻在一个沙箱环境跑一遍冒烟测试，通过就注册进技能库，失败就带着错误信息让模型迭代修改。这个模式下，整个系统的技能库会随着任务使用而增长，用越多越聪明。

当然风险也很明显。自动生成技能如果控制不好，代码注入、无限递归调用都出现过。我的建议是：自动生成的技能必须单独标记，不赋予高危权限，而且先经过一轮人工或自动的代码审查再决定是否启用。你要是图省事直接放开，迟早出事。

5.2 技能评估与回归：不能让 Agent 越用越笨

技能只会加不会减，最后一定是灾难。所以我强烈建议给技能库配一套回归评估机制，每次模型升级、技能调整之后都能看到效果曲线。

我自己的做法是维护一个任务用例集，大概 100 个左右，覆盖技能的典型场景、边界场景和异常场景。每次技能变更，跑一遍用例集，统计通过率、平均调用步数、平均耗时、失败原因分布。通过率下降了，就说明这次改动引入了回归，需要回滚或修 bug。这套机制不复杂，但能让技能体系的迭代走上正轨，而不是靠感觉东改一下西改一下。

5.3 跟现有工具链怎么结合

最后说说和现有系统的关系。agent-skills 从来不是一个孤立的东西，它必须跟你的日常开发工具链嵌在一起才有价值。

常见搭配是：把命令执行能力封装成技能，Agent 就能操作开发环境里的脚本；把函数接口封装成技能，Agent 就能编排业务流程；把文件读写、数据查询封装成技能，Agent 就能做数据分析。核心原则是，技能对外暴露的接口要稳定，内部实现可以随版本迭代频繁替换。

我在实际项目里习惯把一个技能对应的实现代码和测试用例放在同一个目录下，技能描述里自动附带版本号。这样技能变更时可以追溯到具体版本，出问题了也能快速定位是模型的问题还是技能代码的问题。

最后说几句实在话

做 agent-skills 这么久，我的核心体会其实一句话：Agent 的智能化程度，不取决于你用了多大的模型，而取决于你给它沉淀了多少可复用的高质量技能。模型负责聪明，技能负责靠谱，两者缺一不可。

如果你现在正在做 Agent 相关的东西，我的建议是可以从一个最小可用的技能开始，不用上来就搭完整平台。先把一个技能做扎实，跑通注册、调用、结果回传、异常兜底的整条链路，再慢慢往里面加技能。最后再送一个小技巧：每次新增技能之前，先反问自己三遍“模型真的需要这个技能吗”，能砍掉的技能越多，你的 Agent 反而越稳定。